API

The import procedure consists of 3 steps:
• Identification with token recovery,
• Sending data,
• Recovery of possible errors.

The authentication token is obtained by calling the connectNotation function and providing the member’s email and sha1 encrypted password. This function returns an authentication token.

Then call the sendChargeurDeclaration function with the email previously provided, the returned authentication token, a string to describe the selected transfer options and a string containing the transport services to import whose format depends on the selected options.

Once the data has been imported, a feedback is given on its quality, providing the number of imported flows (Import) and the number of valid flows (Valid). If the number returned “Imported” is not equal to the number “Valid”, it means that benefits have been imported incompletely. It will not be possible to take these flows into account. These errors can be fixed on the platform, but it is planned to obtain information by calling the getLastErrorList function.

IDENTIFICATION WITH TOKEN RECOVERY

The authentication token is obtained by calling the connectNotation function
This function has two input parameters, the member’s email and sha2 encrypted password. This function returns an authentication token to be used later in calls to other functions.

Input parameters

Output parameters

The “authentication token” field is a string of characters to be used in the call from sendChargeurDeclaration

Example of a code

// link the client to the WSDL file
$clientSOAP = new SoapClient('https://sandbox-notation.tkblueagency.com/res/tkblue_sandbox.wsdl');
// execute the connectNotation method
$_SESSION['ETKBAtoken'] = $clientSOAP->connectNotation($_POST['Email'],hash("sha256", utf8_encode($_POST['Password'])));

DATA DISPATCH

Once the authentication token is obtained by calling the connectNotation function, it is necessary to call the sendChargeurDeclaration function.

This function has 4 input parameters: the member’s email, the authentication token, a transfer options field and a transport services field. It indicates in return the number of services correctly imported.

Input parameters

The field “transfer options” is a string of characters that will be analyzed by a PHP call of the PARSE QUERY type, 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:

Examples:

• csvDelimiter=,
• csvDelimiter=,&fileFormatName=nomformat

String of characters containing transport services

If field “fileFormatName” is empty, each CSV row must contains the following fields in correct order:

Nature of the fields

Fields with the nature M (mandatory) are mandatory. The absence of such a field or a nil value will result in the benefit being processed in error.

Those whose nature is C (correspondence) can be omitted if the correspondence settings allow them to be determined. Otherwise, the absence of such a field or a nil value will result in the benefit being processed in error.

Those whose nature is O (optional) may be absent or filled in with a null value, without causing misleading processing.

Fields marked with an asterisk can be filled in using the correspondence settings.

CO₂ Information

The fields concerning CO₂ are to be filled in only if the transport organiser or shipper wishes to manage the calculation of CO₂ information himself. In this case no automatic calculation of CO₂ information will be made.

On the other hand, if zero values are transmitted for these fields, the CO₂ information and the level of information will be automatically calculated based on the information collected by the carriers performing the transport services.

Internal references

The Ref and RefAgr fields are to be treated differently depending on whether the customer is a transport organiser or a shipper:

→ For a freight forwarder:
• The Ref field corresponds to the internal reference of the TMS. In the case of a service comprising several segments, 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 reference to the TMS common to the entire service. When the transport service consists of only one segment, the Ref and RefAgr fields will be identical.
• The transport organiser must communicate the value of RefAgr to its principal so that the latter can follow its CO₂ information.

→ For a shipper:
• The Ref field corresponds to the internal reference of the TMS. In the case of a service with several segments, if each segment is directly entrusted 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 reference to the TMS 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 organiser, the possible splitting of the service into several segments is managed in the data flow of the transport organiser.
The RefAgr field must contain the reference communicated by the transport organiser to the shipper in order to allow him to track his CO₂ information.

Mode of transport

Special case of the shipper entrusting a service to a freight forwarder

The shipper can choose to specify “Forwarding Agent” as the mode of transport, so he does not need to specify the fleet identifier used.
This will be particularly the case when the service entrusted to the transport organiser is split into several segments in its 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 organiser entirely free to choose the most suitable mode of transport.

Parameters of call

Each row of CSV data must be separated by an end of line character and must contain the information previously described separated by the character defined in the csvDelimit option.

When using the fileFormatName parameter, the different fields must be ordered according to the import format specified by this parameter. Similarly, the units used must correspond to those defined in the specified import format.

Output parameters

The return of the sendChargeurDeclaration function is a string in json format containing, for compatibility with previous versions, the total number of imported services (complete or incomplete), the total number of rejected services as well as the total number of imported services without missing information.
Note: since processing is always carried out on a deferred basis, the total number of services imported without missing information will be artificially equal to the total number of services imported.

Example of a code

The import can be tested from a web page containing the following php code as an example:

<? // determine the user data $email,$password
if (isset($_POST['ETKBAconnect'])) {
// first step: disable the cache during the test phase
ini_set("soap.wsdl_cache_enabled", "0");
// link the client to the WSDL file
$clientSOAP = new SoapClient('https://sandbox-notation.tkblueagency.com/res/tkblue_sandbox.wsdl');
// execute the connectNotation method
$_SESSION[‘ETKBAtoken’] = $clientSOAP->connectNotation($_POST['Email'],hash("sha256", utf8_encode($_POST['Password'])));
}
if (isset($_POST['export']) )
{
ini_set("soap.wsdl_cache_enabled", "0");
// link the client to the WSDL file
$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 the content of the variable $_POST[‘list’] with the choice of the CSV format:

“4A”,”FR01378901946″,”Urban Road”,”FPgoodgnv-105-1″,””,”2013-04-07″,10, 40, “”,””,”4″
“4B”,”FR01378901946″,”Urban Road”,”FPTRANPO-90-1″,””,”2013-04-04″,10,40, “1203”,”3″,”4″

Example of the returned string:

[{"Imported":2, "Rejected":0, "Valid":2}]

MANAGEMENT OF DEFERRED PROCESSING

The getPostponedImportStatus function has 3 input parameters: the member’s email, the token returned by the connection function and the deferred processing ID, and returns a string in JSON format, indicating the status of the deferred processing and the date and time corresponding to this status. The deferred processing identifier to be provided is the one that was previously returned when the postponed transfer option=1 was used.

Input parameters

Output parameters

getPostponedImportStatus is a string in json format containing:

→ Status: one text among:
• 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 in which the deferred processing generated by webservice is located just after the sendChargerDeclaration function
• Processing: the first step of deferred processing is in progress
• First pass import done: the second step of the deferred processing is in progress
• Import done: deferred processing is complete

→ SatusDate: the date and time corresponding to the returned status

Example of return of the getPostponedImportStatus function

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

ERROR HANDLING

The getLastErrorList function has 2 input parameters: the member’s email and the token returned by the login function, and returns a string in JSON format, indicating on the one hand the number of services in error during the last import, and on the other hand the list of detected errors. Since the processing of an import is delayed, it is recommended not to call this function immediately after sending data.

Input parameters

Output parameters

The return of the getLastErrorList function is a string in json format containing:

→ Error: the number of imported services causing a problem,
→ List: string in json format containing the details of an error:
• Field: name of the field
• How: description of the error
• Value: field value
• N: number of times the error was encountered

There may be more errors detected than benefits misunderstood since the same benefit may have been misled for several reasons.
For each type of error returned, we find the name of the field, a comment explaining the rejection, the incorrect value transmitted as well as the number of benefits affected by this error.

Code examples

Example of poorly 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 numerical field and should not contain the unit

Example of return of the getLastErrorList function

{"Error":"2","List":
[{"Field":"Weight","How":"Weight non num\u00e9rique","Value":"10T","N":"1"},
{"Field":"FlotteLabel","How":"Fleet without carrier","Value":"FPgoodgnv-105-1","N":"1"},{"Field":"VatNumberString","How":"Unknown carrier","Value":"01378901946","N":"1"}]
}

The export procedure is carried out in 2 steps:
• Identification with token recovery
• Data recovery,

The authentication token is obtained by calling the connectNotation function and providing the member’s email and sha1 encrypted password. This function returns an authentication token.

Then call the downloadChargeurDeclaration function with the email previously provided, the returned authentication token and a string of characters to describe 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 email and sha2 encrypted password. This function returns an authentication token to be used later in calls to other functions.

Input parameters

Output parameters

The “authentication token” field is a string of characters to be used in the call from downloadChargeurDeclaration

Example of a code

// link the client to the WSDL file
$clientSOAP = new SoapClient('https://sandbox-notation.tkblueagency.com/res/tkblue_sandbox.wsdl');
// execute the connectNotation method
$_SESSION['ETKBAtoken'] = $clientSOAP->connectNotation($_POST['Email'],hash("sha256", utf8_encode($_POST['Password'])));;

DATA RECOVERY

Once the authentication token obtained by calling the connectNotation function you must call the downloadChargeurDeclaration function
This function has 3 input parameters, the member’s email, the authentication token and a transfer option field. It returns information about the selected services.

Input parameters

The field “transfer options” is a string of characters that will be analyzed by a PHP call of type PARSE QUERY, 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 possible format options are:

Examples :

• dataType=CSV&csvDelimiter=,
• dataType=CSV&csvDelimiter=,&fileFormatName=nomformat
• dataType=CSV&csvDelimiter=,&pagenumber=2&linenumber=10

The search criteria

The search criteria correspond to those available on the platform, in the declaration history.

Dependency on criteria

The criteria minDate and maxDate are to be compared to criterion Pb, and correspond to the dates of the service if criterion Pb is omitted or different from 3. they correspond to the dates of modifications if criterion Pb 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 to be compared to the FieldLabel criterion. The selection will focus on services whose FiledLabel field has the FieldValue value.
Examples :
• FieldLabel=RefAgr&FieldValue=Man1
• FieldLabel=Origin&FieldValue=Nice

Output parameters

The return of the downloadChargeurDeclaration function is a string in json format containing 2 parameters :

{"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 downloadChargeurDeclaration function allows to manage a paging. When it is greater than 100, it is imperative to specify the page number to be returned and to make successive calls to the function by incrementing this page number until it is used up

Example of a code

The export can be tested from a web page containing the following php code as an example:

<? //determine user data $email,$password
// first step: get the token
if (isset($_POST['ETKBAconnect'])) {
// disable the cache during the test phase
ini_set("soap.wsdl_cache_enabled", "0");
// link the client to the WSDL file
$clientSOAP = new SoapClient('https://sandbox-notation.tkblueagency.com/res/tkblue_sandbox.wsdl');
// execute the connectNotation method
$_SESSION[‘ETKBAtoken’] = $clientSOAP->connectNotation($_POST['Email'],hash("sha256", utf8_encode($_POST['Password'])));
}
// second step: determine the search criteria and download the relevant services
if (isset($_POST['export']) )
{
// disable the cache during the test phase
$options = $_POST[‘option’] ;
ini_set("soap.wsdl_cache_enabled", "0");
// link the client to the WSDL file
$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 ;
// test if pagination is necessary
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);
}
?>