Importer des flux dans la plateforme TK’Blue

img_API_importLa procédure d’importation se déroule en 3 étapes :
• Identification avec récupération d’un jeton
• Envoi des données,
• Récupération des erreurs éventuelles.

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 sendChargeurDeclaration 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 prestations de transport à importer dont le format dépend des options choisies.

Une fois les données importées, un retour est donné sur leur qualité, en fournissant le nombre de flux importés (Importer) et le nombre de flux valides (Valid). Si le nombre retourné « Imported » n’est pas égal au nombre « Valid », cela signifie que des prestations ont été importées de façon incomplète. Il ne sera pas possible de prendre en compte ces flux. Ces erreurs peuvent être corrigées sur la plateforme, mais il est prévu d’obtenir des renseignements en appelant la fonction getLastErrorList.

Identification avec récupération d’un jeton

Le jeton d’authentification est obtenu en appelant la fonction connectNotation.
Cette fonction a deux 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 sendChargeurDeclaration

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 sendChargeurDeclaration.
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 prestations de transport. 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
Prestations de transport 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
fileFormatName String Nom du format d’exportation préalablement créé dans l’espace TK’Blue et permettant dans le cas d’un envoi au format CSV de préciser un ordre différent pour les colonnes, des unités spéciales et des champs de données complémentaires (en particulier Origine et Destination)
uniqueRef Int Indication de la présence d’une référence unique et utilisation de la fonction Dédoublonnage.
Valeur par défaut 1 : chaque flux possède une référence unique et il faut procéder au dédoublonnage lorsque plusieurs flux possèdent la même référence.
Sinon, valeur 0 pour ne pas procéder au dédoublonnage.
0 ou 1
year Int Indication de l’année de notation concernée.
Valeur par défaut: l’année en cours au moment de l’importation des flux.
Pour importer des flux sur une autre année, il faut indiquer l’année correspondante.
2015 ou 2016 ou 2017
postponed Int Utilisation de la fonction d’importation en différé. Valeur par défaut 0 : tous les flux sont traités avant le retour de la fonction.
Valeur 1: stockage des flux pour un retour de fonction plus rapide, le traitement est alors fait en différé.
0 ou 1
Exemples :
• dataType=CSV&csvDelimiter=,
• dataType=CSV&csvDelimiter=,&fileFormatName=nomformat

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

Nom du champ Nature Type Description Valeurs
Ref O String (20c max) Référence interne au TMS identifiant un segment d’une prestation Ex : ”C13123-002“
idTransporteur M String Numéro de TVA intracommunautaire* Ex : ”FR01378901946”
idModality C String Intitulé du mode de transport* ”Urban Road” , ”Interurban Road” , ”Rail” , “River” , ”Short Sea Shipping” , ”Deep Sea” , ”Air” , ”Forwarding Agent”
idFlotteTransporteur C String Identifiant de la flotte du transporteur* Ex : ”FPTRANPO_90_1”
FlotteSpec M String Spécificité de la flotte ”ou ”Reefer”
DateTransport M String YYY-MM-DD Date de la prestation
WeightPos M Int, en kg poids
KmPos C Int, en km Distance
CO2 O Int, en gCO2 Information CO2
CO2Level O Int Niveau de l’information CO2 De 1 à 4
RefAgr O String (20c max) Référence interne au TMS identifiant une prestation multi-segment Ex: ”C13123”
  • Nature des champs
  • Information CO2
  • Références internes
  • 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 prestation.

Ceux dont la nature est C (correspondance) peuvent être omis si le paramétrage des correspondances permet de les déterminer. Dans le cas contraire, l’absence d’un champ de cette nature ou une valeur nulle entrainera le traitement en erreur de la prestation.

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.

Les champs concernant le CO2 sont à renseigner uniquement si l’organisateur de transport ou le chargeur désire gérer lui-même le calcul de l’information CO2. Dans ce cas aucun calcul automatique d’information CO2 ne sera fait.

Par contre, si des valeurs nulles sont transmises pour ces champs, l’information CO2 et le niveau de l’information seront automatiquement calculés en fonction des informations récoltées par les transporteurs exécutant les prestations de transport.

Les champs Ref et RefAgr sont à traiter différemment selon que le client est un organisateur de transport ou un chargeur :

Pour un organisateur de transport :
• Le champ Ref correspond à la référence interne au TMS. Dans le cas d’une prestation comportant plusieurs segments, chaque segment doit faire l’objet d’une ligne de données séparée et doit donc posséder une référence propre et unique.
Le champ RefAgr contient alors la référence interne au TMS commune à l’ensemble de la prestation. Lorsque la prestation de transport ne comporte qu’un seul segment, les champs Ref et RefAgr seront identiques.
• L’organisateur de transport devra communiquer la valeur de RefAgr à son donneur d’ordres pour que ce dernier puisse suivre son information CO2.

Pour un chargeur :
• Le champ Ref correspond à la référence interne au TMS. Dans le cas d’une prestation comportant plusieurs segments, si chaque segment est confié directement à des transporteurs, chaque segment doit faire l’objet d’une ligne de données séparée et doit donc posséder une référence propre et unique.
Le champ RefAgr contient alors la référence interne au TMS commune à l’ensemble de la prestation. Lorsque la prestation de transport ne comporte qu’un seul segment et est confiée directement à un transporteur, les champs Ref et RefAgr seront identiques.
• Dans le cas d’une prestation confiée à un organisateur de transport, l’éclatement éventuel de la prestation en plusieurs segments est géré dans le flux de données de l’organisateur de transport.
Le champ RefAgr doit contenir la référence communiquée par l’organisateur de transport au chargeur afin de lui permettre de faire le suivi de son information CO2.

Cas particulier du chargeur confiant une prestation à un organisateur de transport

Le chargeur peut choisir de préciser « Forwarding Agent » comme mode de transport, il n’a alors pas besoin de préciser l’identifiant de la flotte utilisée.
Ce sera en particulier le cas lorsque la prestation confiée à l’organisateur de transport sera éclatée en plusieurs segments dans son flux interne, ces segments pouvant correspondre à des modes de transports différents, et à des transporteurs et identifiants de flottes différents.

Ce sera encore le cas pour une prestation mono-segment, pour laquelle le chargeur laisse l’organisateur de transport entièrement libre du choix du mode de transport le plus adapté.

Si le format choisi est CSV, chaque prestation 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 dans l’option csvDelimiter.

Lorsque le paramètre fileFormatName est utilisé, les différents champs doivent être ordonnés selon le format d’importation précisé par ce paramètre. De même, les unités utilisées doivent correspondre à celles définies dans le format d’importation précisé.

Paramètres en sortie
Le retour de la fonction sendChargeurDeclaration est une chaine au format json contenant le total des prestations importées (complètes ou incomplètes), le total des prestations rejetées ainsi que le total des prestations importées sans informations manquantes.
Attention: Si le traitement en différé a été demandé en précisant dans les options de transfert postponed=1, le total des prestations importées sans informations manquantes sera artificiellement égal au total des prestations importées.

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->sendChargeurDeclaration($_POST['Email'],$_SESSION[‘ETKBAtoken’] ,$_POST['option'] ,$_POST['list']);
}
?>

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

[{« Ref »: « 4A », »idTransporteur »: « FR01378901946″, »idModality »: « Routier Urbain », »idFlotteTransporteur »:
« FPgoodgnv-105-1″, »FlotteSpec »: «  », »DateTransport »: « 2013-04-07″, »WeightPos »: 10, »KmPos »: 40, »CO2″:
«  », »CO2Level »: «  », »RefAgr »: « 4 »}, {« Ref »: « 4B », »idTransporteur »: « FR01378901946″, »idModality »: « Routier
Urbain », »idFlotteTransporteur »: « FPTRANPO-90-1″, »FlotteSpec »: «  », »DateTransport »: « 2013-04-
04″, »WeightPos »: 10, »KmPos »: 40, »CO2″: « 1203 », »CO2Level »: « 1 », »RefAgr »: « 4 »}]

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

« 4A », »FR01378901946″,”Routier Urbain”,”FPgoodgnv-105-1”,””,”2013-04-07”,10, 40, ””,””,”4”
”4B”,”FR01378901946”,”Routier Urbain”,”FPTRANPO-90-1”,””,”2013-04-04”,10,40, ”1203”,”3”,”4”

Exemple de la chaine retournée :

[{« Imported »:2, « Rejected »:0, « Valid »:2}]

Gestion des erreurs

La fonction getLastErrorList a 2 paramètres en entrée : l’email du membre et le jeton retourné par la fonction de connexion, et retourne une chaine de caractères au format JSON, indiquant d’une part le nombre de prestations en erreur lors de la dernière importation, et d’autre part la liste des erreurs détectées. Il n’y a pas lieu d’appeler cette fonction lorsqu’un traitement en différé a été demandé.

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

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

→ Error: le nombre de prestations importées posant un problème,
→ List: chaine au format json contenant le détail d’une erreur:
• Field: nom du champ
• Comment: description de l’erreur
• Value: valeur du champ
• N: nombre de fois où l’erreur a été rencontré

Il peut y avoir plus d’erreurs détectées que de prestations en erreur puisqu’une même prestation peut avoir été mise en erreur pour plusieurs raisons.
Pour chaque type d’erreur retourné, on trouve le nom du champ incriminé, un commentaire expliquant le rejet, la valeur erronée transmise ainsi que le nombre de prestations concernées par cette erreur.

Exemples de code
Exemple de prestations mal importées

”4E”,”01378901946”,”Routier Urbain”,”FPgoodgnv-105-1”,””,”2013-04-07”,”10”, ”40”
”1E”,”FR01378901946”,”Routier Urbain”,”FPTRANPO-90-1”,””,”2013-04-04”,”10T”,”40”

→ ”01378901946” n’est pas un numéro de TVA correct
→ ”10T” n’est pas un champ numérique et ne devrait pas contenir l’unité

Exemple de retour de la fonction getLastErrorList

{"Error":"2","List":
[{"Field":"Weight","Comment":"Poids non num\u00e9rique","Value":"10T","N":"1"},
{"Field":"FlotteLabel","Comment":"Flotte sans transporteur","Value":"FPgoodgnv-105-1","N":"1"},{"Field":"VatNumberString","Comment":"Transporteur inconnu","Value":"01378901946","N":"1"}]
}

Gestion des traitements différés

La fonction getPostponedImportStatus a 3 paramètres en entrée : l’email du membre, le jeton retourné par la fonction de connexion et l’identifiant du traitement différé, et retourne une chaine de caractères au format JSON, indiquant le statut du traitement différé et la date et heure correspondant à ce statut. L’identifiant de traitement différé à fournir est celui qui a été retourné précédemment quand l’option de transfert postponed=1 a été utilisée.

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
Identifiant du traitement différé Int Retourné par la fonction sendChargeurDeclaration

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

→ Status: un texte parmi:
• Import file format needs to be chosen: uniquement pour les dépôts de fichiers hors utilisation du webservice
• First record needs to be checked: uniquement pour les dépôts de fichiers hors utilisation du webservice
• Ready for process: C’est l’état dans lequel se trouve le traitement différé généré par webservice juste après la fonction sendChargeurDeclaration
• Processing: la première étape du traitement différé est en cours
• First pass import done: la deuxième étape du traitement différé est en cours
• Import done: le traitement différé est terminé

→ SatusDate: la date et heure correspondant au statut retourné

Exemple de retour de la fonction getPostponedImportStatus

{"Status":"Import done","StatusDate":"2016-10-11 22:31:21"}

Revenir en haut de la page