API
This page details the procedures for automatic data exchange between a Shipper's or Transport Organizer's information system and the TK'Blue platform.
Once the data exchange has been programmed, we recommend you run tests on the TK'Blue Sandbox site: sandbox-notation.tkblueagency.com. Logins are provided by the TK'Blue team.
Once the test phase is complete, replace the address https://sandbox-notation.tkblueagency.com with notation.tkblueagency.com and tkblue_sandbox.wsdl with tkblue.wsdl.
The TK'Blue API has been developed using Soap Client/Server (Simple Object Access Protocol) technology.
See en.wikibooks.org/wiki/Programming_PHP/Examples/webService for programming explanations, and soapclient.com/soaptest.html to test the server.
Find all the functions of the TK'Blue API on this link: tkblueagency.com/api/reference/
Importing flows into the TK'Blue platform
The import procedure takes place in 3 stages:
- Identification with recovery of a token,
- Data transmission,
- Recovery of any errors.
The authentication token is obtained by calling the connectNotation function function and providing the member's e-mail address and encrypted password sha1. This function returns an authentication token.
Then call the sendChargerDeclaration function function with the email previously supplied, the authentication token returned, a character string describing the transfer options chosen and a character string containing the transport services to be imported, the format of which depends on the options chosen.
Once the data has been imported, feedback is given on its quality, providing the number of imported feeds (Imported) and the number of valid feeds (Valid). If the number returned as "Imported" is not equal to the number returned as "Valid", this means that some services have been imported incompletely. It will not be possible to take these flows into account. These errors can be corrected on the platform, but it is planned to obtain information by calling the function getLastErrorList function.
IDENTIFICATION WITH TOKEN RECOVERY
The authentication token is obtained by calling the connectNotation.
This function has two input parameters, the member's e-mail address and his encrypted password sha2. This function returns an authentication token to be used in subsequent calls to other functions.
Input parameters
| Field name | Type | Description |
| String | Member's platform login | |
| Password | String | sha2 encryption of platform login password |
Output parameters
The "authentication token" field is a string to be used in the call to sendChargerDeclaration
Sample code
// lier le client au fichier WSDL
$clientSOAP = new SoapClient('https://sandbox-notation.tkblueagency.com/res/tkblue_sandbox.wsdl');
// executer la methode connectNotation
$_SESSION['ETKBAtoken'] = $clientSOAP->connectNotation($_POST['Email'],hash("sha256", utf8_encode($_POST['Password'])));
SENDING DATA
Once you've obtained the authentication token by calling the connectNotationfunction, call the sendChargerDeclaration.
This function has 4 input parameters: the member's email address, the authentication token, a transfer options field and a transport services field. It returns the number of correctly imported services.
Input parameters
| Field name | Type | Description |
| String | Member's platform login | |
| Authentication token | String | Returned by the ConnectNotation function |
| Transfer options | String | Detailed below |
| Transport services | String | Detailed below, in CSV format |
The "transfer options" field is a character string that will be parsed by a PARSE QUERY PHP call, i.e. it consists of one or more options of the form "option_name1=option_value1&option_name2=option_value2....".
The possible options are described below:
| Field name | Type | Description | Values |
| csvDelimiter | String | Indication of the character delimiting fields; the semicolon is used by default. | |
| csvHeader | Int | Default value 0 (column headers are not to be included), otherwise indicate 1 if they are. | 0 or 1 |
| fileFormatName | String | Name of export format previously created in the TK'Blue space, allowing you to specify a different order for columns, special units and additional data fields (in particular Origin and Destination). | |
| uniqueRef | Int | Indication of the presence of a unique reference and use of the deduplication function. Default value 1: each stream has a unique reference and deduplication is required when several streams have the same reference. Otherwise, value 0 to avoid deduplication. |
0 or 1 |
| year | Int | Indication of the rating year concerned. Default value: the current year at the time of importing the feeds. To import feeds for another year, the corresponding year must be indicated. |
2015 or 2016 or 2017 |
| postponed | Int | Obsolete parameter, always considered equal to 1 to allow storage of flows for faster return of function, processing is then deferred. | 0 or 1 |
Examples:
- csvDelimiter=,
- csvDelimiter=,&fileFormatName=formatName
Character string containing transport services
If the fileFormatName option is not supplied, the CSV must contain the following columns in order:
| Field name | Nature | Type | Description | Values |
| Ref | O | String (20c max) | Internal TMS reference identifying a service segment | Ex : "C13123-002" |
| idTransporter | M | String | Intracommunity VAT number | Ex : "FR01378901946" |
| idModality | C | String | Transport mode* title | "Urban Road , Interurban Road , Rail River Short Sea Shipping , Deep Sea , Air , Forwarding Agent |
| idFleetTransporter | C | String | Carrier fleet identifier | Ex : "FPTRANPO_90_1" |
| FleetSpec | M | String | Fleet specificity | "or "Reefer |
| DateTransport | M | String YYYY-MM-DD | Date of service | |
| WeightPos | M | Int, in kg | weight | |
| KmPos | C | Int, in km | Distance | |
| CO2 | O | Int, in gCO2 | CO2 information | |
| CO2Level | O | Int | CO2 information level | From 1 to 4 |
| RefAgr | O | String (20c max) | Internal TMS reference identifying a multi-segment service | Ex: "C13123" |
Nature of fields
Fields marked M (mandatory) are mandatory. The absence of a field of this type, or a null value, will result in the service being processed in error.
Fields whose nature is C (correspondence) can be omitted if the correspondence settings allow them to be determined. Otherwise, the absence of a field of this type, or a zero value, will result in the service being processed in error.
Those whose nature is O (optional) can be absent or filled in with a null value, without causing error processing.
Fields marked with an asterisk can be filled in using the correspondence settings.
CO2 information
The fields concerningCO2 should only be filled in if the transport organizer or shipper wishes to manage the calculation of theCO2 information himself. In this case, theCO2 information will not be calculated automatically.
On the other hand, if zero values are transmitted for these fields, theCO2 information and the level of information will be automatically calculated on the basis of the information collected by the carriers performing the transport services.
Internal references
The Ref and RefAgr fields must be treated differently depending on whether the customer is a transport organizer or a shipper:
→ For a transport organizer:
- The Ref field corresponds to the TMS internal reference. In the case of a service comprising several segments, each segment must be the subject of a separate line of data and must therefore have its own unique reference.
The RefAgr field then contains the internal TMS reference common to the entire service. When the transport service comprises only one segment, the Ref and RefAgr fields will be identical.
- The transport organizer must communicate the value of RefAgr to his client, so that the latter can track hisCO2 information.
→ For a shipper:
- The Ref field corresponds to the TMS internal reference. In the case of a service comprising several segments, if each segment is entrusted directly to carriers, each segment must be the subject of a separate data line and must therefore have its own unique reference.
The RefAgr field then contains the internal TMS reference common to the entire service. When the transport service comprises only one segment and is entrusted directly to a carrier, the Ref and RefAgr fields will be identical.
- In the case of a service entrusted to a transport organizer, any splitting of the service into several segments is managed in the transport organizer's data flow.
The RefAgr field must contain the reference communicated by the transport organizer to the shipper to enable him to track hisCO2 information.
Mode of transport
Special case of a shipper entrusting a service to a transport organizer
The shipper can choose to specify "Forwarding Agent" as the mode of transport, in which case he does not need to specify the fleet identifier used.
This will be the case in particular when the service entrusted to the transport organizer is broken down into several segments in his internal flow, which may correspond to different modes of transport, and to different carriers and fleet identifiers.
This will still be the case for a single-segment service, for which the shipper leaves the transport organizer entirely free to choose the most suitable mode of transport.
Call settings
In the CSV string, each service must be separated by an end-of-line character and must contain the information described above, separated by the character defined in the csvDelimiter option.
When the fileFormatName parameter is used, the various fields must be ordered according to the import format specified by this parameter. Similarly, the units used must correspond to those defined in the import format specified.
Output parameters
The return of the sendChargeurDeclaration function function is a string in json format containing, for reasons of compatibility with previous versions, the total of benefits imported (complete or incomplete), the total of benefits rejected and the total of benefits imported without missing information.
Note: as processing is always delayed, the total of benefits imported without missing information will be artificially equal to the total of benefits imported.
Sample code
The import can be tested from a web page containing the following php code as an example:
<? // 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.com/res/tkblue_sandbox.wsdl');
// executer la methode connectNotation
$_SESSION[‘ETKBAtoken’] = $clientSOAP->connectNotation($_POST['Email'],hash("sha256", utf8_encode($_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.com/res/tkblue_sandbox.wsdl');
$retourimport = $clientSOAP->sendChargeurDeclaration($_POST['Email'],$_SESSION['ETKBAtoken'] ,$_POST['option'] ,$_POST['list']);
}
?>
Example of contents of variable $_POST['list'] in CSV format:
"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"
Example of the string returned :
[{"Imported":2, "Rejected":0, "Valid":2}]
DEFERRED TREATMENT MANAGEMENT
The getPostponedImportStatus function function has 3 input parameters: the member's email address, the token returned by the connection function and the postponed treatment identifier, and returns a string in JSON format, indicating the status of the postponed treatment and the date and time corresponding to this status. The deferred processing identifier to be supplied is the one previously returned when the postponed=1 transfer option was used.
Input parameters
| Field name | Type | Description |
| String | Member's platform login | |
| Authentication token | String | Returned by the ConnectNotation function |
| Deferred processing identifier | Int | Returned by the sendChargerDeclaration function |
Output parameters
The return from the getPostponedImportStatus function function is a string in json format containing:
→ Status: one of:
- Import file format needs to be chosen: only for file repositories not using the webservice
- First record needs to be checked: only for file repositories not using the webservice
- Ready for process: This is the state of the delayed processing generated by the webservice immediately after the sendChargerDeclaration function
- Processing: the first stage of delayed processing is underway
- First pass import done: the second stage of delayed processing is underway
- Import done: delayed processing is complete
→ SatusDate: the date and time corresponding to the returned status
Example of the return from the getPostponedImportStatus
{”Status”:"Import done","StatusDate":"2016-10-11 22:31:21"}
ERROR MANAGEMENT
The function getLastErrorList function has 2 input parameters: the member's email address and the token returned by the connection function, and returns a string in JSON format, indicating both the number of services in error during the last import, and the list of errors detected. As import processing takes time, we recommend that you do not call this function immediately after sending data.
Input parameters
| Field name | Type | Description |
| String | Member's platform login | |
| Authentication token | String | Returned by the ConnectNotation function |
Output parameters
The return from the getLastErrorList function function is a string in json format containing:
→ Error: the number of imported services with a problem,
→ List: string in json format containing the details of an error:
- Field: name of the field
- Comment: description of the error
- Value: value of the field
- N: number of times the error was encountered
There may be more errors detected than services in error, since the same service may have been in error for several reasons.
For each type of error returned, we provide the name of the offending field, a comment explaining the rejection, the erroneous value transmitted and the number of services affected by this error.
Code examples
Example of incorrectly imported services
”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" is not a correct VAT number
→ "10T" is not a numeric field and should not contain the unit
Example of the return from the 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"}]
}
Exporting feeds from the TK'Blue platform
The export procedure takes place in 2 stages:
- Identification with token recovery
- Data recovery,
The authentication token is obtained by calling the connectNotation function function and providing the member's e-mail address and encrypted password sha1. This function returns an authentication token.
Then call the downloadChargerDeclaration function function with the email previously supplied, the returned authentication token and a string describing the chosen transfer options.
IDENTIFICATION WITH TOKEN RECOVERY
The authentication token is obtained by calling the connectNotation.
This function has 2 input parameters, the member's e-mail address and his encrypted password sha2. This function returns an authentication token to be used in subsequent calls to other functions.
Input parameters
| Field name | Type | Description |
| String | Member's platform login | |
| Password | String | sha2 encryption of platform login password |
Output parameters
The "authentication token" field is a string to be used in the call to downloadChargerDeclaration
Sample code
// lier le client au fichier WSDL
$clientSOAP = new SoapClient('https://sandbox-notation.tkblueagency.com/res/tkblue_sandbox.wsdl');
// executer la methode connectNotation
$_SESSION['ETKBAtoken'] = $clientSOAP->connectNotation($_POST['Email'],hash("sha256", utf8_encode($_POST['Password'])));
DATA RECOVERY
Once you've obtained the authentication token by calling the connectNotation function function, call the downloadChargerDeclaration.
This function has 3 input parameters: the member's email address, the authentication token and a transfer option field. It returns information about the selected services.
Input parameters
| Field name | Type | Description |
| String | Member's platform login | |
| Authentication token | String | Returned by the ConnectNotation function |
| Transfer options | String | Detailed below |
The "transfer options" field is a character string that will be analyzed by a PARSE QUERY PHP call, i.e. it consists of one or more options of the form "option_name1=option_value1&option_name2=option_value2...." and one or more search criteria.
The possible options are described below:
Format options
The following format options are available:
| Field name | Type | Description | Values |
| dataType | String | If this parameter is not specified, the JSON format will be used. | JSON or CSV |
| csvDelimiter | String | Only for dataType=CSV option. Indication of the character delimiting the fields, by default the semicolon is used. |
|
| csvHeader | Int | Only for the dataType=CSV option. Default value 0: column headers are not to be included, otherwise indicate 1 if they are. |
0 or 1 |
| fileFormatName | String | Name of the export format previously created in the loader area, allowing you to specify a different order for columns, special units and additional data fields (in particular Origin and Destination) when sending data in CSV format. | |
| pagenumber | Int | Page number in the set of search results when using a paginated search. The selection range is specified by a page number and a number of results (linenumber) per page to be returned. | The default value is 0 |
| linenumber | Int | Maximum number of results to return. The selection range is specified by a page number (pagenumber) and a number of results per page to be returned. The default value is 100, which is also the maximum possible value. To retrieve more than 100 services, you need to program successive calls and manage pagination. | The default value is 100 |
Examples:
- dataType=CSV&csvDelimiter=,
- dataType=CSV&csvDelimiter=,&fileFormatName=nomformat
- dataType=CSV&csvDelimiter=,&pagenumber=2&linenumber=10
Search criteria
Search criteria correspond to those available on the platform, in the declaration history.
| Field name | Type | Correspondence | Values |
| Pb | Int | "Display only | 1 : Valid entries 2 : Incorrect entries 3 : Changes |
| minDate | String | "Display only | 'YYYY-MM-DD' |
| maxDate | String | "Display only at | 'YYYY-MM-DD' |
| CO2 | Int | "CO2tracking | 0: unknown -1: known any level 1: level 1 2: level 2 3: level 3 4: level 4 |
| TKB | Int | "Follow-up TK'T | 0: unknown -1: known any level 1: provisional level 2: declared level 3: validated level |
| VatNumber | String | "Carrier | Ex: "FR01378901946" if the identifier is an intra-Community VAT number, "123456789B|SG|UEN" for a Singapore UEN identifier. |
| FieldLabel | String | "Search: field | Ref, RefAgr, Origin, Destination |
| FieldValue | String | "Search: value | |
| Year | Int | "Year | y-2, y-1, y, y+1 where y is the current year at the time of export launch |
Criteria dependency
The minDate and maxDate criteria are related to the Pb criterion, and correspond to the service dates if the Pb criterion is omitted or different from 3. They correspond to the modification dates if the Pb criterion is 3.
Examples:
- Year=2017&VatNumber=FR89123456789|FR|VAT
- Year=2017&VatNumber=123456789B|SG|UEN
- Pb=2&minDate=2013-06-01&maxDate=2013-12-31
- Pb=3&minDate=2013-06-01&maxDate=2013-08-31
The FieldValue criterion is similar to the FieldLabel criterion. The selection will focus on services whose FiledLabel field takes the value FieldValue.
Examples:
- FieldLabel=RefAgr&FieldValue=Man1
- FieldLabel=Origin&FieldValue=Nice
Output parameters
The return of the downloadChargerDeclaration function function is a string in json format containing 2 parameters:
| Field name | Type | Description |
| Total | Int | The total number of services covered by the search criteria, excluding pagination |
| data | JSON | A JSON string containing the services returned in the chosen format (CSV or JSON), each service containing the fields selected by the export format indicated in the 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
The "total" parameter returned by the downloadChargerDeclaration function is used to manage pagination. When this parameter is greater than 100, you must specify the page number to be returned and make successive calls to the function, incrementing this page number until all pages have been paginated.
Sample code
The export can be tested from a web page containing the following php code as an example:
<? // 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.com/res/tkblue_sandbox.wsdl');
// executer la methode connectNotation
$_SESSION[‘ETKBAtoken’] = $clientSOAP->connectNotation($_POST['Email'],hash("sha256", utf8_encode($_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.com/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);
}
?>
Output parameters
The return from the putCarrierCorrespondancyList function function is a string in json format containing
| Parameter name | Description |
| Imported | Total imported matches (complete or incomplete) |
| Rejected | Total rejected matches |
| Incoherent | Total inconsistencies encountered (e.g. mode of transport and fleet ID) |
| Invitations | Total number of invitations automatically sent by e-mail |
| Errors | The list of errors encountered in json format. |
Sample code
The import can be tested from a web page containing the following php code as an example:
// 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.com/res/tkblue_sandbox.wsdl');
// executer la methode connectNotation
$_SESSION['ETKBAtoken'] = $clientSOAP->connectNotation($_POST['Email'],hash("sha256", utf8_encode($_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.com/res/tkblue_sandbox.wsdl');
$retourimport = $clientSOAP->putCarrierCorrespondancyList($_POST['Email'],$_SESSION[‘ETKBAtoken’] ,$_POST['option'] ,$_POST['list']);
}
Example of the contents of the variable $_POST['list'] with the choice of JSON format:
[{"Name": "WSTR1","TIN": "FR62421868084"}, {"Name": "DONAVIN","TIN": "06141912850013","idModality": "Urban Road","Email": "abcd@xyz.fr","FirstName": "Paul","LastName": "DUPONT","BusinessName": "SARL DUPONT","idLanguage": 2,"CountryCode":"SV","TINAcr":"NIT"}]
Example of contents of variable $_POST['list'] in CSV format:
"WSTR1","FR62421868084" "DONAVIN","06141912850013","Urban Road",,,,"abcd@xyz.fr","Paul","DUPONT","SARL DUPONT",2,"SV","NIT"
Example of the string returned :
{”Imported”:0,”Rejected”:3,”Incoherent”:0,”Invitation”:0,”Errors”:[”line o:InvalidVATNumber”,”line 1:InvalidVATNumber”,”line 2:InvalidVATNumber”]}
Import carrier connection settings
The import procedure takes place in 2 stages:
- Identification with token recovery
- Data transmission.
The authentication token is obtained by calling the connectNotation function function and providing the member's e-mail address and encrypted password sha1. This function returns an authentication token.
Then call the putCarrierCorrespondancyList function function with the email previously supplied, the authentication token returned, a character string to describe the transfer options chosen and a character string containing information on the carriers to be imported, whose format is predetermined.
If the number returned as "Imported" is not equal to the number returned as "Valid", this means that imported information is in error.
IDENTIFICATION WITH TOKEN RECOVERY
The authentication token is obtained by calling the connectNotation function.
This function has 2 input parameters, the member's e-mail address and his sha2 encrypted password. This function returns an authentication token to be used in subsequent calls to other functions.
Input parameters
| Field name | Type | Description |
| String | Member's platform login | |
| Password | String | sha2 encryption of platform login password |
Output parameters
The "authentication token" field is a string to be used in the call to putCarrierCorrespondancyList call
Sample code
// lier le client au fichier WSDL
$clientSOAP = new SoapClient('https://sandbox-notation.tkblueagency.com/res/tkblue_sandbox.wsdl');
// executer la methode connectNotation
$_SESSION['ETKBAtoken'] = $clientSOAP->connectNotation($_POST['Email'],hash("sha256", utf8_encode($_POST['Password'])));
SENDING DATA
Once you've obtained the authentication token by calling the connectNotation function function, call the putCarrierCorrespondacyList.
This function has 4 input parameters: the member's email address, the authentication token, a transfer options field and a Carrier Correspondence field. It returns the number of correctly imported services.
Input parameters
| Field name | Type | Description |
| String | Member's platform login | |
| Authentication token | String | Returned by the ConnectNotation function |
| Transfer options | String | Detailed below |
| Correspondence Carriers | String | Detailed below |
The "transfer options" field is a character string that will be parsed by a PARSE QUERY PHP call, i.e. it consists of one or more options of the form "option_name1=option_value1&option_name2=option_value2....".
The possible options are described below:
| Field name | Type | Description | Values |
| dataType | String | If this parameter is not specified, the JSON format will be used. | JSON or CSV |
| csvDelimiter | String | Only for dataType=CSV option. Indication of the character delimiting the fields, by default the semicolon is used. | |
| csvHeader | Int | Only for dataType=CSV option. Default value 0: column headers are not to be included, otherwise indicate 1 if they are. | 0 or 1 |
| sendInvitation | Int | Default value 1: invitations are sent to carriers for which an email address and company name have been specified. | 0 or 1 |
Examples:
- dataType=CSV&csvDelimiter=,
- dataType=JSON
Character string containing Carrier matches
When the chosen format is JSON, for each service, the json structure must contain the fields :
| Field name | Nature | Type | Description | Values |
| Name | M | String | Carrier name as mentioned in flows | Ex : "TRPT Valognes " or " F10XZ33 ". |
| TIN | M | String | Carrier NIF identifier | Ex: "FR01378901946". |
| idModality | O | String | Transport mode* title | "Urban Road , Interurban Road , Rail River Short Sea , Air , Forwarding Agent |
| idFleetTransporter | O | String | Carrier fleet identifier | Ex : "FPTRANPO_90_1" |
| FleetSpec | O | String | Fleet specificity | Reefer |
| idAdemeCO2 | O | String | Level 1 CO2 index reference | A|30 |
| O | String | Carrier contact email | Ex : " transport@tkblueagency.com | |
| LastName | O | String | Carrier contact name | Ex: "DURAND |
| FirstName | O | String | First name of carrier contact | Ex : "Pierre |
| BusinessName | O | String | Company name of carrier | Ex: "Transports Valognes SARL". |
| idLanguage | O | Int | Carrier language identifier | Ex: 1 for English, 2 for French |
| CountryCode | O | String | ISO country code. This code must be specified if it is not present in the first two characters of the VAT number. | Ex: "FR" for France |
| Acronym TIN | O | String | This acronym must be specified when the carrier identifier does not correspond to an intra-Community VAT number. | Ex: "VAT" for a VAT number |
Nature of fields
Fields marked M (mandatory) are mandatory. The absence of a field of this type, or a null value, will result in the carrier correspondence being processed in error.
Those whose nature is O (optional) can be absent or filled in with a null value, without causing error processing.
Fields marked with an asterisk can be filled in using the correspondence settings.
CO2 information
The idAdemeCO2 field is used to assign a default level 1CO2 index to the carrier awaiting its declaration.
Once the carrier has calculated its ownCO2 index, it will automatically replace the default index without any action on the part of the user.
Mode of transport
To set up a carrier connection that operates on several modes of transport with a specific fleet for each mode, you need to create several settings for each mode of transport.
Call settings
If the chosen format is CSV, each match must be separated by an end-of-line character and must contain the information described above in the JSON structure, separated by the character defined by csvDelimiter.
The various fields must be ordered according to the field order shown in the table above.
Interrogating the Blue Gallery
Interrogating the Blue Gallery
The interrogation procedure takes place in 2 stages:
- Identification with token recovery
- Data recovery.
The authentication token is obtained by calling the connectNotation function function and providing the member's e-mail address and encrypted password sha1. This function returns an authentication token.
Then call the getCarrierList function function with the email previously supplied, the returned authentication token and a string describing the chosen transfer options.
Questioning a carrier's performance
The interrogation procedure takes place in 2 stages:
- Identification with token recovery
- Data recovery.
The authentication token is obtained by calling the connectNotation function function and providing the member's e-mail address and encrypted password sha1. This function returns an authentication token.
Then call the getCarrierPerformance function function with the email previously supplied, the returned authentication token and a string describing the chosen transfer options.
Export carrier statistics
The interrogation procedure takes place in 2 stages:
- Identification with token recovery
- Data recovery.
The authentication token is obtained by calling the connectNotation function function and providing the member's e-mail address and encrypted password sha1. This function returns an authentication token.
Then call the getCarrierStatistics function function with the email previously supplied, the returned authentication token and a string describing the chosen transfer options.
IDENTIFICATION WITH TOKEN RECOVERY
The authentication token is obtained by calling the connectNotation function.
This function has 2 input parameters: the member's e-mail address and the encrypted password sha2. This function returns an authentication token to be used in subsequent calls to other functions.
Input parameters
| Field name | Type | Description |
| String | Member's platform login | |
| Password | String | sha2 encryption of platform login password |
Output parameters
The "authentication token" field is a string to be used in the call to getCarrierStatistics call
Sample code
// lier le client au fichier WSDL
$clientSOAP = new SoapClient('https://sandbox-notation.tkblueagency.com/res/tkblue_sandbox.wsdl');
// executer la methode connectNotation
$_SESSION['ETKBAtoken'] = $clientSOAP->connectNotation($_POST['Email'],hash("sha256", utf8_encode($_POST['Password'])));
DATA RECOVERY
Once you've obtained the authentication token by calling the connectNotation function function, call the getCarrierStatistics function.
This function has 3 input parameters: the member's email address, the authentication token and a transfer options field. It returns information about the selected period.
Input parameters
| Field name | Type | Description |
| String | Member's platform login | |
| Authentication token | String | Returned by the ConnectNotation function |
| Transfer options | String | Detailed below |
The "transfer options" field is a character string that will be parsed by a PARSE QUERY PHP call, i.e. it consists of one or more options of the form "param1=val1¶m2=val2....".
The possible options are described below:
| Field name | Type | Description | Value |
| pagenumber | Int | Page number in the set of search results when using a paginated search. The selection range is specified by a page number and a number of results (linenumber) per page to be returned. | The default value is 0 |
| linenumber | Int | Maximum number of results to return. The selection range is specified by a page number (pagenumber) and a number of results per page to be returned. The default value is 100, which is also the maximum possible value. To retrieve more than 100 results, you need to program successive calls and manage pagination. | The default value is 100 |
| Year | Int | The year of statistics. | y-2, y-1, y, y+1 where y is the current year when the query is launched |
| Month | Int | Allows you to retrieve results for a specific month of a year, or for an entire calendar year, or for an entire fiscal year; the period corresponding to a fiscal year is defined in the loader area. |
O (default) for annual statistics,
13 for annual fiscal year statistics, 1 to 12 for monthly statistics |
| Modality | String | Transport mode title. This information is mandatory, as results cannot be obtained for all modes combined. | "Urban Road , Interurban Road , Rail River , Short Sea Shipping , Deep Sea , Air |
Examples:
- Modality=Rail&Year=2016,
- Modality=URBAN ROAD&Year=2017&Month=3
Output parameters
The return from the getCarrierStatistics function function is a string in json format containing 2 parameters:
| Field name | Type | Description |
| Total | Int | The total number of carriers covered by the non-pagination search criteria |
| data | JSON | A JSON string containing the following information for each selected carrier: BusinessName (company name), VatNumberString (VAT number), AvgIT (average TK'T index), AvgICO2 (averageCO2/GES index according to the unit selected by the GHG parameter). |
Each item of the returned data variable contains the following information:
| Field name | Type | Description |
| BusinessName | String | Carrier's company name |
| VatNumberString | Sring | Its NIF |
| TKM | Decimal | The total number of tonne-kilometres operated on behalf of the shipper by this carrier |
| ITKT | Decimal | Its average TK'T index in flows, ranging from 0 to 100 |
| COST | Decimal | Total societal cost in € |
| SCO2 | Decimal | total CO2 emissions according to the French decree (well-to-wheel) in kgCO2 |
| SGp | Decimal | total GHG emissions according to the European standard (well-to-wheel) in kgCO2e |
| SGr | Decimal | total GHG emissions according to European standards (from tank to wheel) in kgCO2e |
| ICO2 | Decimal | Its average CO2 index in flows, according to the French decree (from well to wheel) in gCO2/t.km |
| IGp | Decimal | Its average GHG index in flows, according to the European standard (from well to wheel) in gCO2e/t.km |
| IGp | Decimal | Its average GHG index in flows, according to the European standard (from tank to wheel) in gCO2e/t.km |
"total":"2","data":[{"BusinessName":"INTERROUTEUN","VatNumber":"FR02325625440","TKM":"2000000.0000","ITKT":89.335,"COST":"3788.8880","CO2":"131114.0000",
"Gr":"108480.0000","Gp":"135386.0000","ICO2":6.56,"IGr":5.42,"IGp":6.77},{"BusinessName":"TRAUN","VatNumber":"FR49539818948","TKM":"1000000.0000","ITKT":87.515,"COST":"2914.6997","CO2":"108237.0000",
"Gr":"89551.0000","Gp":"111763.0000","ICO2":10.82,"IGr":8.96,"IGp":11.18}]}
Pagination
The "total" parameter returned by the getCarrierStatistics function function is used to manage pagination. When this parameter is greater than 100, you must specify the page number to be returned and make successive calls to the function, incrementing this page number until all pages have been paginated.
Sample code
<? // determiner les données utilisateurs $email,$password
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.com/res/tkblue.wsdl');
// première étape : obtenir le token
// executer la methode connectNotation
$login = $_POST['LoginEmail'];
$pwd = hash("sha256", utf8_encode($_POST['Pwd']));
try{
$link = $clientSOAP->connectNotation($login,$pwd);
} catch (Exception $e) {
echo 'Exception reçue : ', $e->getMessage(), "\n";
}
// deuxième étape : déterminer les critères de recherche et lancer l'interrogation
// gestion de la pagination sur getCarrierStatistics
$linenumber = 20;
$pagenumber = 1;
$options = $_POST['option']."&linenumber=".$linenumber;
try{
$res = $clientSOAP->getCarrierStatistics($login,$link,$options);
} catch (Exception $e) {
echo 'Exception reçue : ', $e->getMessage(), "\n";
}
$retour = json_decode($res);
$data = $retour->data;
if ($retour->total > count($data))
{
do{
$pagenumber++;
$options = $_POST['option']."&linenumber=".$linenumber."&pagenumber=".$pagenumber;
$res = $clientSOAP->getCarrierStatistics($login,$link,$options);
$retour = json_decode($res);
$data = $retour->data;
// gérer le contenu retourné dans $data
}while (count($data) == $linenumber);
}
}
?>
Connect to the TK'Blue platform without logging in
To be able to connect transparently to the TK'Blue areas dedicated to Shippers or Transport Organizers, i.e. without manually entering your login and password, you must request an authentication token.
Authentication tokens have a limited lifespan and become inactive as soon as they have been used, so there's no need to store them for future use. In other words, an authentication token must be requested for each connection.
IDENTIFICATION
The authentication token is obtained by calling the connectWeb.
This function has 2 input parameters: the member's e-mail address and the encrypted password sha2, and returns a redirection link containing the authentication token.
Input parameters
| Field name | Type | Description |
| String | Member's platform login | |
| Password | String | sha2 encryption of platform login password |
Output parameters
The function returns a link to be used for direct access to the member's area without authentication.
Sample code
// determiner les données utilisateurs $email, et $password
// désactiver le cache lors de la phase de test
if (isset($_POST[‘Connect']))
{
ini_set("soap.wsdl_cache_enabled", "0");
// lier le client au fichier WSDL
$clientSOAP = new SoapClient('https://sandbox-notation.tkblueagency.com/res/tkblue_sandbox.wsdl');
// executer la methode connectWeb
$link = $clientSOAP->connectWeb($email,hash("sha256", utf8_encode($password')));
?>