Importer les correspondances Transporteurs

img_API_importTLa procédure d’importation se déroule en 2 étapes :
• Identification avec récupération d’un jeton
• Envoi des données.

Le jeton d’authentification est obtenu en appelant la fonction connectNotation et en fournissant l’email du membre et son mot de passe crypté sha1. Cette fonction retourne un jeton d’authentification.

Il faut ensuite appeler la fonction putCarrierCorrespondancyList avec l’email précédemment fourni, le jeton d’authentification retourné , une chaine de caractères pour décrire les options de transfert choisies et une chaine de caractères contenant les informations sur les transporteurs à importer dont le format est prédéterminé.

Si le nombre retourné « Imported » n’est pas égal au nombre « Valid », cela signifie que des informations importées sont en erreur.

Identification avec récupération d’un jeton

Le jeton d’authentification est obtenu en appelant la fonction connectNotation.
Cette fonction a 2 paramètres en entrée, l’email du membre et son mot de passe crypté sha1. Cette fonction retourne un jeton d’authentification à utiliser par la suite dans les appels des autres fonctions.

Paramètres en entrée

Nom du champ Type Description
Email String Identifiant de connexion du membre sur la plateforme
Mot de passe String Encryptage sha1 du mot de passe de connexion sur la plateforme

Paramètres en sortie
Le champs « jeton d’authentification » est une chaine de caractères à utiliser dans l’appel de putCarrierCorrespondancyList

Exemple de code

// lier le client au fichier WSDL
$clientSOAP = new SoapClient('https://sandbox-notation.tkblueagency.eu/res/tkblue_sandbox.wsdl');
// executer la methode connectNotation
$_SESSION[‘ETKBAtoken’] = $clientSOAP->connectNotation($_POST['Email'],sha1($_POST['Password']));

Envoi des données

Une fois le jeton d’authentification obtenu en appelant la fonction connectNotation il faut appeler la fonction putCarrierCorrespondacyList.
Cette fonction a 4 paramètres en entrée, l’email du membre, le jeton d’authentification, un champ d’options de transfert et un champ Correspondance Transporteurs. Elle indique en retour le nombre de prestations correctement importées.

Paramètres en entrée

Nom du champ Type Description
Email String Identifiant de connexion du membre sur la plateforme
Jeton d’authentification String Retourné par la fonction ConnectNotation
Options de transfert String Détaillé ci-dessous
Correspondance Transporteurs String Détaillé ci-dessous


Le champ « options de transfert » est une chaine de caractères qui sera analysée par un appel PHP de type PARSE QUERY, c’est à dire qu’elle se compose d’une ou plusieurs options de la forme « nom_option1=valeur_option1&nom_option2=valeur_option2…. ».

Les options possibles sont décrites ci-dessous :

Nom du champ Type Description Valeurs
dataType String Si ce paramètre n’est pas précisé, le format JSON sera utilisé JSON ou CSV
csvDelimiter String Uniquement pour l’option dataType=CSV. Indication du caractère délimitant les champs, par défaut le point-virgule est utilisé.
csvHeader Int Uniquement pour l’option dataType=CSV. Valeur par défaut 0 : les entêtes de colonnes ne sont pas à inclure, sinon indiquer 1 si elles le sont. 0 ou 1
sendInvitation Int Valeur par défaut 1 : des invitations sont à envoyer aux transporteurs pour lesquels un email et une raison sociale ont été précisés 0 ou 1
Exemples :
• dataType=CSV&csvDelimiter=,
• dataType=JSON

Chaîne de caractères contenant les correspondances Transporteurs
Lorsque le format choisi est JSON, pour chaque prestation, la structure json doit contenir les champs :

Nom du champ Nature Type Description Valeurs
Name M String Libellé du transporteur tel que mentionné dans les flux Ex : ”TRPT Valognes » ou « F10XZ33 »
NumTVA M String Numéro de TVA intracommunautaire* Ex : ”FR01378901946”
idModality O String Intitulé du mode de transport* ”Urban Road” , ”Interurban Road” , ”Rail” , “River” , ”Short Sea” , ”Air” , ”Forwarding Agent”
idFlotteTransporteur O String Identifiant de la flotte du transporteur* Ex : ”FPTRANPO_90_1”
FlotteSpec O String Spécificité de la flotte Vide ou ”Reefer”
idAdemeCO2 O String Référence de l’indice CO2 de niveau 1 A|30
Email O String Email du contact chez le transporteur Ex : « transport@tkblueagency.eu
LastName O String Nom du contact chez le transporteur  Ex : « DURAND »
FirstName O String Prénom du contact chez le transporteur Ex : « Pierre »
BusinessName O String Raison sociale du transporteur Ex : « Transports Valognes SARL »
idLanguage O Int Identifiant de langue du transporteur Ex: 1 pour Anglais, 2 pour Francais
CountryCode O String Code Pays ISO. Ce code doit obligatoirement être précisé lorsqu’il n’est pas présent dans les deux premiers caractères du numéro de TVA Ex: « FR » pour la France
  • Nature des champs
  • Information CO2
  • Mode de transport
  • Paramètres d’appel
Les champs dont la nature est M (mandatory) sont obligatoires. L’absence d’un champ de cette nature ou une valeur nulle entrainera le traitement en erreur de la correspondance transporteur.

Ceux dont la nature est O (optional) peuvent être absents ou renseignés par une valeur nulle, sans entrainer un traitement en erreur.

Les champs marqués d’un astérisque peuvent être renseignés à l’aide des paramétrages des correspondances.

Le champ idAdemeCO2 permet d’affecter un indice CO2 de niveau 1 par défaut au transporteur en attente de sa déclaration.

Une fois que le transporteur aura calculé son propre indice CO2, il remplacera automatiquement et sans action de l’utilisateur l’indice affecté par défaut.

Pour paramétrer une correspondance transporteur qui opère sur plusieurs modes de transport avec une flotte spécifique pour chaque mode, il faut alors créer plusieurs paramétrages pour chaque mode de transport
Si le format choisi est CSV, chaque correspondance doit être séparée par un caractère de fin de ligne et doit contenir les informations décrites précédemment dans la structure JSON, séparées par le caractère défini par csvDelimiter.

Les différents champs doivent être ordonnés selon l’ordre des champs indiqué dans le tableau ci-dessus.

Paramètres en sortie
Le retour de la fonction putCarrierCorrespondancyList est une chaine au format json contenant

Nom du paramètre Description
Imported Le total des correspondances importées (complètes ou incomplètes)
Rejected Le total des correspondances rejetées
 Incoherent Le total des incohérences rencontrées (mode de transport et identifiant de flotte par exemple)
Invitations Le total des invitations envoyées automatiquement par courrier électronique
Errors La liste des erreurs rencontrées au format json.

Exemple de code

L’importation peut être testée à partir d’une page web contenant le code php suivant à titre d’exemple :

// determiner les données utilisateurs $email,$password
if (isset($_POST['ETKBAconnect'])) {
// première étape : désactiver le cache lors de la phase de test
ini_set("soap.wsdl_cache_enabled", "0");
// lier le client au fichier WSDL
$clientSOAP = new SoapClient('https://sandbox-notation.tkblueagency.eu/res/tkblue_sandbox.wsdl');
// executer la methode connectNotation
$_SESSION[‘ETKBAtoken’] = $clientSOAP- >connectNotation($_POST['Email'],sha1($_POST['Password']));
}
if (isset($_POST['export']) )
{
ini_set("soap.wsdl_cache_enabled", "0");
// lier le client au fichier WSDL
$clientSOAP = new SoapClient('https://sandbox-notation.tkblueagency.eu/res/tkblue_sandbox.wsdl');
$retourimport = $clientSOAP->putCarrierCorrespondancyList($_POST['Email'],$_SESSION[‘ETKBAtoken’] ,$_POST['option'] ,$_POST['list']);
}

Exemple de contenu de la variable $_POST[‘list’] avec le choix du format JSON:

[{« Name »: « BIMAT », »NumTVA »: « FR483237xxxxx »}, {« Name »: « DONAVIN », »NumTVA »: « FR483237yyyyy », »idModality »: « Urban Road »}, {« Name »: « DONAVIR », »NumTVA »: « FR483237zzzzz », »Email »: « abcd@xyz.fr », »FirstName »: « Paul », »LastName »: « DUPONT », »BusinessName »: « SARL DUPONT », »idLanguage »: 2}]

Exemple de contenu de la variable $_POST[‘list’] avec le choix du format CSV:

”BIMAT”,”FR483237xxxxx”,
”DONAVIN”,”FR483237yyyyy”,”Urban Road”
”DONAVIR”,”FR483237zzzzz”,””,””,””,””,”abcd@xyz.fr”,”Paul”,”DUPONT”,”SARL DUPONT”,”2”

Exemple de la chaine retournée :

{”Imported”:0,”Rejected”:3,”Incoherent”:0,”Invitation”:0,”Errors”:[”line o:InvalidVATNumber”,”line 1:InvalidVATNumber”,”line 2:InvalidVATNumber”]}

Revenir en haut de la page