Exporter des flux depuis la plateforme TK’Blue

img_API_exportLa procédure d’exportation se déroule en 2 étapes :
• Identification avec récupération d’un jeton
• Récupération 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 downloadChargeurDeclaration avec l’email précédemment fourni, le jeton d’authentification retourné et une chaine de caractères pour décrire les options de transfert choisies.

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 champ « jeton d’authentification » est une chaine de caractères à utiliser dans l’appel de downloadChargeurDeclaration

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']));

Récupération des données

Une fois le jeton d’authentification obtenu en appelant la fonction connectNotation il faut appeler la fonction downloadChargeurDeclaration.
Cette fonction a 3 paramètres en entrée, l’email du membre, le jeton d’authentification et un champ d’option de transfert. Elle retourne les informations concernant les prestations sélectionné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

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…. » et d’un ou plusieurs critères de recherche

Les options possibles sont décrites ci-dessous :

Les options de format
Les options de format possibles sont :

Nom du champs 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 chargeur 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)
pagenumber Int Numéro de la page dans l’ensemble des résultats de la recherche lorsqu’on utilise une recherche paginée. La plage de sélection se précise par un numéro de page et un nombre de résultats (linenumber) par page à retourner. La valeur par défaut est 0
linenumber Int Nombre maximal de prestations à retourner. La plage de sélection se précise par un numéro de page (pagenumber) et un nombre de résultats par page à retourner. La valeur par défaut est 100, c’est aussi la valeur maximale possible. Pour récupérer plus de 100 prestations vous devez programmer des appels successifs et gérer la pagination. La valeur par défaut est 100
Exemples :
• dataType=CSV&csvDelimiter=,
• dataType=CSV&csvDelimiter=,&fileFormatName=nomformat
• dataType=CSV&csvDelimiter=,&pagenumber=2&linenumber=10

Les critères de recherche
Les critères de recherche correspondent à ceux disponibles sur la plateforme, dans l’historique des déclarations.

Nom du champ Type Correspondance Valeurs
Pb Int « Afficher seulement » 1 : Saisies valides
2 : Saisies incorrectes
3 : Modifications
minDate String « Afficher seulement du » ‘YYYY-MM-DD’
maxDate String « Afficher seulement au » ‘YYYY-MM-DD’
CO2 Int « Suivi CO2 » 0 : inconnu
-1 : connu tout niveau
1 : niveau 1
2 : niveau 2
3 : niveau 3
4 : niveau 4
TKB Int « Suivi TK’T » 0 : inconnu
-1 : connu tout niveau
1 : niveau Provisoire
2 : niveau Déclaré
3 : niveau Validé
VatNumber String « Transporteur » Ex ‘FR01378901046’
FieldLabel String « Rechercher : champ » ‘Ref’, ‘RefAgr’, ‘Origin’, ‘Destination’
FieldValue String « Rechercher : valeur »
Year Int « Année » y-2, y-1, y, y+1 où y est l’année en cours au moment du lancement de l’exportation

Dépendance des critères
Les critères minDate et maxDate sont à rapprocher du critère Pb, et correspondent aux dates de la prestation si le critère Pb est omis ou différent de 3. Ils correspondent aux dates de modifications si le critère Pb vaut 3.

Exemples :
• Pb=2&minDate=2013-06-01&maxDate=2013-12-31
• Pb=3&minDate=2013-06-01&maxDate=2013-08-31

Le critère FieldValue est à rapprocher du critère FieldLabel. La sélection portera sur les prestations dont le champ FiledLabel prend la valeur FieldValue.

Exemples :
• FieldLabel=RefAgr&FieldValue=Man1
• FieldLabel=Origin&FieldValue=Nice

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

Nom du champs Type Description
Total Int Le total des prestations concernées par les critères de recherche hors pagination
data JSON Une chaine JSON contenant les prestations retournées au format choisi (CSV ou JSON), chaque prestation comportant les champs sélectionnés par le format d’exportation indiqué dans les options
{"total":"18","data":
[{"Ref":"4A","DateTransport":"2013-04-07","idModality":"Routier Urbain","idFlotteTransporteur":"FPgoodgnv-105- 1","FlotteSpec":"","Km":"400","Weight":"10000","CO2":"120","CO2Level":"2","RefAgr":"4","idTransporteur":"FR01378901946","Origin":null,"Destination":nulle},
{"Ref":"7001-9153","DateTransport":"2013-04-25","idModality":"Routier Interurbain","idFlotteTransporteur":"","FlotteSpec":"","Km":"12","Weight":"97","CO2":"0","CO2Level":"0","RefAgr":"7001-9153","idTransporteur":"","Origin":null,"Destination":nulle},
{"Ref":"7001-9152","DateTransport":"2013-04-25","idModality":"Routier Interurbain","idFlotteTransporteur":"","FlotteSpec":"","Km":"14","Weight":"130","CO2":"0","CO2 Level":"0","RefAgr":"7001-9152","idTransporteur":"","Origin":null,"Destination":nulle},
{"Ref":"7645-10002","DateTransport":"2013-04-27","idModality":"Routier Interurbain","idFlotteTransporteur":"","FlotteSpec":"Frigo","Km":"12","Weight":"107","CO2":"0","CO2Level":"0","RefAgr":"7645-10002","idTransporteur":"","Origin":null,"Destination":nulle},
{"Ref":"7464-10003","DateTransport":"2013-04-28","idModality":"Routier Interurbain","idFlotteTransporteur":"","FlotteSpec":"","Km":"11","Weight":"339","CO2":"0","CO2 Level":"0","RefAgr":"7464-10003","idTransporteur":"","Origin":null,"Destination":nulle}
]}

Pagination
Le paramètre « total » retourné par la fonction downloadChargeurDeclaration permet de gérer une pagination. Lorsque celui-ci est supérieur à 100, il est impératif de préciser le numéro de page à retourner et de procéder à des appels successifs de la fonction en incrémentant ce numéro de page jusqu’à épuisement.

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

<? // determiner les données utilisateurs $email,$password
// première étape : obtenir le token
if (isset($_POST['ETKBAconnect'])) {
// 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']));
}
// deuxième étape : déterminer les critères de recherche et télécharger les prestations concernées
if (isset($_POST['export']) )
{
// désactiver le cache lors de la phase de test
$options = $_POST[‘option’] ;
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');
$linenumber = 5 ;
$pagenumber = 1 ;
$options = $_POST[‘option’].’&linenumber=’.$linenumber.’&pagenumber=’.$pagenumber ;
$retourexport = $clientSOAP->downloadChargeurDeclaration($_POST['Email'],$_SESSION[‘ETKBAtoken’] ,$_POST['option'] );
$result = json_decode($retourexport) ;
$data = $result->data ;
// tester si la pagination est nécessaire
if($result->total > count($data)) do{
$pagenumber++;
$options = $_POST[‘option’].’&linenumber=’.$linenumber.’&pagenumber=’.$pagenumber ;
$retourexport = $clientSOAP->downloadChargeurDeclaration($_POST['Email'],$_SESSION[‘ETKBAtoken’] ,$_POST['option'] );
$result = json_decode($retourexport) ;
$data = $result->data ;
} while (count($data) == $linenumber);
}
?>

Revenir en haut de la page