PD-IT-PR-2901 - Manual API Mondial Relay
PD-IT-PR-2901 - Manual API Mondial Relay
PD-IT-PR-2901 - Manual API Mondial Relay
Updates
Web Service
The term Web Service represents a computer program enabling the communication and the
exchange of information between heterogeneous applications and systems in distributed
environments. They are thus a set of functionalities presented on Internet or an Intranet, by and for
applications or machines, without human intervention, and in real time. Web Service is called via a
URL and bears a file name.
The software are written up in various program languages and on various platforms can use web
services to exchange data via IT networks like internet.
This interoperability is due to the use of open norms grouped in the SOA generic term (Service
Oriented Architecture).
The main advantage of the Web Service usage is the automatic information flow exchange in real
time with the Mondial Relay servers as opposed to files exchanges (via ftp) which take place at
regular intervals during the day.
The Web Services use standards and open protocols. All the exchange data are formatted in XML.
This coding can be carried out by SOAP or XML-RPC. Based on the HTTP protocol, the Web Services
can operate through numerous firewalls without filter modifications.
Mondial Relay is not responsible for contents of the above page and cannot guarantee the
information.
Regular expression
A regular expression is a character strings.
The regular expressions are used today by IT people in publishing and text control as well as in formal
language usage which are part of the IT languages.
ISO standard
The document refers to two ISO standards in order to identify the countries and languages.
The reference standard for the country codes is ISO 3166-1. Only the code alpha-2 from this
standard is used by Mondial Relay.
Mondial Relay is not responsible for the content of the above pages and cannot guarantee the
information in them.
The Mondial Relay website doesn't include all countries and language codes present in the ISO
standards mentioned above.
To obtain the list of allowed countries and languages, please inquire at Mondial Relay.
MD5 Hash
The MD5 Message-Digest Algorithm is a widely used cryptographic hash function that produces a
128-bit (16-byte) hash value. Specified in RFC 1321, MD5 has been employed in a wide variety of
security applications, and is also commonly used to check data integrity. An MD5 hash is typically
expressed as a 32-digit hexadecimal number.
Mondial Relay is not liable for the content of this page and cannot guarantee the page information.
XML transfert
XML is a meta-language. It is a tool which generalizes the principle of logical tagging and makes it
possible to build tagging languages to represent the documents in terms of logical structures,
independently of their mode of processing. The logical tagging takes place in the following order :
Identification of the formal structure of the document. The essence of the document is
described by identifying the various elements which constitute it,
Tagging of the document in accordance with the formal structure defined.
Web Service
http://api.mondialrelay.com/Web_Services.asmx
All the calls to the Web Service method will be secured with a control key. The algorithm for the
calculation of this control key is detailed further in this document.
Test credentials:
You should contact the IT Dept of Mondial Relay if help is needed for setting up the filters.
Regularity of calls
In normal mode, the Web Service method of Mondial Relay must not be called in batch , that
means that the calls must not be grouped in a big lot of calls, during the night for example. The calls
must be spread during the entire day and night, in relation to the needs of final users (search of PUP
/ orders / and so on.). This kind of organization is necessary in order not to cause problems to other
users of the Web Service due to a too big monopolization of the resources of our servers.
WSI2_RechercheCP
Example
Calculation of the method WSI3_GetEtiquettes with the following parameters:
Enseigne = BDTEST13
Expeditions = 12345678
Langue = FR
One can notice the presence of all parameters mentioned in the correct order in the document, the
optional parameters being empty, they do not appear in the concatenation, but in case they are
specified, it must be taken into consideration.
Next, the MD5 algorithm is applied to this string, the algorithm is well known in the field of
programming, this method of generation is not given here.
Online calculation
http://www.functions-online.com/md5.html
http://md5-hash-online.waraxe.us/
http://www.md5.cz/
Mondial Relay is not responsible for the content of these pages and cannot give any guarantee on
the information it contains.
Label print
Labels must be printed on white paper without any resizing.
Delivery modes
Here is a non-exhaustive list of delivery modes.
LCC : Reverse
The methods of the Mondial Relay Web Service
Point Relais search
This method permits to search the 10 nearest Points Relais from a given location (from a GPS
address or by both Zip code/Country). The results can be sorted by Points Relais trade type.
By using the filter on the Point Relais number, this method permits to obtain information about one
particular Point Relais.
24R : Search the Points Relais which suggest the delivery to Point Relais L
24L : Search the Points Relais which suggest the delivery to Point Relais XL
24X : Search the Points Relais which suggest the delivery to Point Relais XXL
DRI : Search the Points Relais wich suggest the delivery to Colisdrive
REL : Search the Points Relais which suggest the collection from Point Relais
Usage of filter Dlais denvoi (lead time)
The method results can be adapted according to the time needed to send the shipments to Mondial
Relay. Please just specify the number of days in the parameter DelaisEnvoi .
WSI3_PointRelais_Recherche method
In parameters
(F) Facultative /
Parameters Comment
(O) Obligatory
^-?[0-9]{2}\.[0-9]{7}$
Latitude to be used as search origin. If this parameter is given, the zipcode
(F) Facultative /
Parameters Comment
(O) Obligatory
^-?[0-9]{2}\.[0-9]{7}$
Longitude to be used as search origin. If this parameter is given, the zipcode
will not be taken into account.
^(XS|S|M|L|XL|XXL|3
Do not use unless specified by Mondial Relay. XL)$
^[0-9]{1,6}$
Shipment weight in grams.
^(REL|24R|24L|24X|D
Collection or delivery mode. RI)$
^-?[0-9]{2})$
Optional parameter which permit to specify the lead time : the time
necessary between order and shipment sent to Mondial Relay.
When the webservice is used on the D day with a given number of days
before the parcel shipment (ie. 28 days), the webservice gives just the Points
Relais which are open on D+28 days and will remain open for an extra 14
days beyond, in order to give the end user enough time to pick up the parcel.
^[0-9]{1,4}$
Search radius in Km from a point of search origin. If not given or blank, the
value by default is 50Km. In order not to use this filter RayonRecherche
(F) Facultative /
Parameters Comment
(O) Obligatory
please mention 0.
TypeActivite F ^(\d{3},|\d{3})*$
Specify trade type for Point Relais. Several trade types can be specified, they
have to be seperated by ,
SECURITY O 32 Alphanumerical
characters
MD5 hash in capital letters for the following string : ^[0-9A-Z]{32}$
[Enseigne][Pays][NumPointRelais][Ville][CP][Latitude][Longitude][Taille][Poid
s][Action][DelaiEnvoi][RayonRecherche] [TypeActivite][CLE PRIVEE]
Out parameters
(F) Optional / (O)
Parameters Comment
Obligatory
^[0-9]{1,3}$
The return code of the request is 0 per default (0 if all is correct). For the
others codes, please consult the return codes list.
^[0-9]{6}$
Point Relais ID
>Lgdr1 O 36 Alphanumerical
characters
Point Relais name (Line 1)
>LgAdr2 O 36 Alphanumerical
characters
Point Relais name (Line 2)
(F) Optional / (O)
Parameters Comment
Obligatory
>LgAdr3 O 36 Alphanumerical
characters
Point Relais address (Line 1)
>LgAdr4 O 36 Alphanumerical
characters
Point Relais address (Line 2)
>Ville O 32 Alphanumerical
characters
Point Relais city
>Pays O 2 Alphanumerical
characters
Point Relais ISO country code
>Latitude O 11 Characters
^-?[0-9]{2}\.[0-9]{7}$
Point Relais Latitude
>Longitude O 11 Characters
^-?[0-9]{2}\.[0-9]{7}$
Point Relais Longitude
>TypeActivite O
>Distance O
>Localisation1 O
>Localisation2 O
Monday opening hours (Data 1 : Opening hours slot 1), (Data 2 : Closing time
slot 1), (Data 3 : Opening hours slot 2), (Data 4 : Closing time slot 2).
>Debut O
>Fin O
>URL_Plan O
>URL_Photo O
WSI2_RechercheCP method
In parameters
Facultative /
Parameter Comment
Obligatory
^[0-9A-Z]{2}[0-9A-Z
This parameter is the merchant id code given in the document of parameters. ]{6}$
^[A-Z]{2}$
[A-Z_\-' ]{3,26}
The starting letters of the city for the search.
^[0-9]{5}$
NbResult O 1 to 2 numerical
characters
Quantity of results required Maximum : 15
^[0-9A-Z]{32}$
Security code.
Out parameters
Facultative /
Parameters Comment
Obligatory
^[0-9]{1,3}$
Call status
Table of communities
^[0-9]{5}$
City name
^[A-Z]{2}$
Shipment creation
This method creates shipment in Mondial Relays system and returns the data to build customized
labels.
WSI2_CreationExpedition method
In parameters
Parameters Facultative / Comment
Obligatory
^[0-9A-Z]{2}[0-9A-Z
This parameter is the merchant id code given in the document of parameters. ]{6}$
NDossier F 15 characters
^(|[0-9A-Z_ -]{0,15})$
Merchant shipment reference, e.g invoice number.
NClient F 9 characters
^(|[0-9A-Z]{0,9})$
Consignee reference (n)
^[A-Z]{2}$
Expe_Ad1 O 32 characters
^[0-9A-Z_\-'., /]{2,32}$
Shipper (Particulars Name First name)
Particulars :
Accepted particulars = 'MR', 'M.', 'MME', 'MLE' et 'MLLE' ^((MR|M.|M|MME|M
LE|MLLE) )$
Parameters Facultative / Comment
Obligatory
Expe_Ad2 F 32 characters
^[0-9A-Z_\-'., /]{0,32}$
Shipper (address extra information)
Expe_Ad3 O 32 characters
^[0-9A-Z_\-'., /]{2,32}$
Shipper (Street)
Expe_Ad4 F 32 characters
^[0-9A-Z_\-'., /]{0,32}$
Shipper (address extra information)
^[A-Z_\-' ]{2,26}$
^[0-9]{5}$
^[A-Z]{2}$
^((00|\+)33|0)[0-9][0-
9]{8}$
Parameters Facultative / Comment
Obligatory
^((00|\+)33|0)[0-9][0-
9]{8}$
Expe_Mail F 70 characters
^[A-Z]{2}$
Dest_Ad1 O 32 characters
^[0-9A-Z_\-'., /]{2,32}$
Consignee (Particulars Name First name)
Particulars :
Accepted particulars = 'MR', 'M.', 'MME', 'MLE' et 'MLLE' ^((MR|M.|M|MME|M
LE|MLLE) )$
Dest_Ad2 F 32 characters
^[0-9A-Z_\-'., /]{0,32}$
Consignee (address extra information)
Dest_Ad3 O 32 characters
^[0-9A-Z_\-'., /]{2,32}$
Consignee (Street)
Dest_Ad4 F 32 characters
^[0-9A-Z_\-'., /]{0,32}$
Consignee (address extra information)
Parameters Facultative / Comment
Obligatory
^[A-Z_\-' ]{2,26}$
^[0-9]{5}$
^[A-Z]{2}$
^((00|\+)33|0)[0-9][0-
9]{8}$
^((00|\+)33|0)[0-9][0-
9]{8}$
Dest_Mail F 70 characters
^[0-9]{3,7}$
Weight in grams
^[0-9]{0,3}$
Developped length in cm.
^[0-9]{1,2}$
Quantity of parcels in the shipment
^[0-9]{1,7}$
COD shipment value in cents
^[0-9]{0,7}$
Shipment value in cents
^[A-Z]{2}$
Parameters Facultative / Comment
Obligatory
^[A-Z]{2}$
N for No
N by default.
^(|[0-9]{1,3})$
Assembly time
0 by default.
Parameters Facultative / Comment
Obligatory
N for No
N by default
Warning : Please leave this zone empty. We don't use this information.
Assurance F 1 character
^(|[0-9A-Z]{1})$
Insurance coverage.
0 by default.
Instructions F 31 characters
^[0-9A-Z_\-'., /]{0,31}
Extra information
^[0-9A-Z]{32}$
Security code
Out parameters
Parameters Facultative / Comment
Obligatory
^[0-9]{1,3}$
Call status
^[A-Z][0-9]{2}$
Sorting group number
TRI_Agence O 30 characters
Agency name
26 fix numerical
characters
^[0-9]{26}$
N.B.:
Labels specifications are available in the EDI specifications. Please refer to this document to
implement labels. Note that Mondial Relay has to validate your labels before any Go Live.
Phone number format :
In parameters
Facultative /
Parameters Comment
Obligatory
^[0-9A-Z]{2}[0-9A-Z
This parameter is the merchant id code given in the document of parameters. ]{6}$
NDossier F 15 characters
^(|[0-9A-Z_ -]{0,15})$
Merchant shipment reference.e;g invoice number
NClient F 9 characters
^(|[0-9A-Z]{0,9})$
Consignee reference
^[A-Z]{2}$
Expe_Ad1 O 32 characters
^[0-9A-Z_\-'., /]{2,32}$
Sender (Particulars Name First name)
Particulars :
Accepted particulars = 'MR', 'M.', 'MME', 'MLE' et 'MLLE' ^((MR|M.|M|MME|M
LE|MLLE) )$
Facultative /
Parameters Comment
Obligatory
Expe_Ad2 F 32 characters
^[0-9A-Z_\-'., /]{0,32}$
Sender (Other name information)
Expe_Ad3 O 32 characters
^[0-9A-Z_\-'., /]{2,32}$
Sender (Street)
Expe_Ad4 F 32 characters
^[0-9A-Z_\-'., /]{0,32}$
Sender (Extra address information)
^[A-Z_\-' ]{2,26}$
^[0-9]{5}$
^[A-Z]{2}$
^((00|\+)33|0)[0-9][0-
9]{8}$
Facultative /
Parameters Comment
Obligatory
^((00|\+)33|0)[0-9][0-
9]{8}$
Expe_Mail F 70 characters
Format e-mail
Sender (E-mail) RFC2822
^[\w\-\.\@_]{7,70}$
^[A-Z]{2}$
Dest_Ad1 O 32 characters
^[0-9A-Z_\-'., /]{2,32}$
Consignee (Particulars Name First name)
Particulars :
Accepted particulars = 'MR', 'M.', 'MME', 'MLE' et 'MLLE' ^((MR|M.|M|MME|M
LE|MLLE) )$
Dest_Ad2 F 32 characters
^[0-9A-Z_\-'., /]{0,32}$
Consignee (Other name information)
Dest_Ad3 O 32 characters
^[0-9A-Z_\-'., /]{2,32}$
Consignee (Street)
Dest_Ad4 F 32 characters
^[0-9A-Z_\-'., /]{0,32}$
Consignee (Extra address information)
Facultative /
Parameters Comment
Obligatory
^[A-Z_\-' ]{2,26}$
^[0-9]{5}$
^[A-Z]{2}$
^((00|\+)33|0)[0-9][0-
9]{8}$
^((00|\+)33|0)[0-9][0-
9]{8}$
Dest_Mail F 70 characters
^[0-9]{3,7}$
Weight in grams
^[0-9]{0,3}$
Developped lenght in cm
^[0-9]{1,2}$
Number of parcels in the shipment
^[0-9]{1,7}$
COD shipment value in cents
^[0-9]{0,7}$
Shipment value in cents
^[A-Z]{2}$
Facultative /
Parameters Comment
Obligatory
^[A-Z]{2}$
N for No
N by default.
^(|[0-9]{1,3})$
Assembly time
0 by default.
Facultative /
Parameters Comment
Obligatory
N for No
N by default
Warning : Please leave this zone empty. We don't use this information.
Assurance F 1 character
^(|[0-9A-Z]{1})$
Insurance coverage.
0 by default.
Instructions F 31 characters
^[0-9A-Z_\-'., /]{0,31}
Extra information
^[0-9A-Z]{32}$
Security code
^([^<>&']{3,30})(\(cr\)[
10 x 30 characters separated by (cr) ^<>&']{0,30}){0,9}$
WARNING: Please do not take into consideration for the security key
calculation.
The Texte field corresponds to the items which make up the shipment, this field will be present in
the second part of the label. This field cannot have the following characters '' & " < and >.
Each end of line will be translated in the text field by the string characters (cr) .
This string of characters will permit the back to margin during print out.
In case the text field has more than 10 lines, these would be deleted during print out.
Out parameters
Facultative /
Parameters Comment
Obligatory
^[0-9]{1,3}$
Call status
URL_Etiquette O
The value given by URL_Etiquette does not include the domain name and the protocol.
After reconstitution of the complete link, the PDF URL must look like the following :
http://www.mondialrelay.com/ww2/PDF/StickerMaker2.aspx?ens=BDTEST__11&expedition=171697
84&lg=FR&format=A4&crc=FF6273F49A0CCF4C4E058D8F904C618F
You can choose the label format by mentioning the value A5 or 10x15 instead of A4 in the format
URL parameter.
Parcel tracking
WSI2_TracingColisDetaille method
In parameters
Parameters Facultative / Comment
Obligatory
^[0-9A-Z]{2}[0-9A-Z
This parameter is the merchant id code given in the document of parameters. ]{6}$
^[A-Z]{2}$
^[0-9A-Z]{32}$
Security code.
Out parameters
Facultative /
Parameters Comment
Obligatory
^[0-9]{1,3}$
Call status
Libelle01 O
Relais_Libelle F
^[0-9]{6}$
Libelle02 O
Tracing O Array
Tracking table
> Tracing_Libelle F
Tracking name
> Tracing_Date F
Tracking date
> Tracing_Heure F
Tracking hour
> Tracing_Lieu F
^[A-Z]{2}$
Point Relais country of tracking (if needed)
Concatenated labels retrieval
WSI3_GetEtiquettes method
This method allows to retrieve several labels with a unique Web Service call.
In Parameters
Facultative /
Parameters Comment
Obligatory
^[0-9A-Z]{2}[0-9A-Z ]{6}$
This parameter is the merchant id code given in the document of
parameters.
^[0-9A-Z]{32}$
Security code.
Out parameters
Facultative /
Parameters Comment
Obligatory
^[0-9]{1,3}$
Call status
URL_PDF_A4 O
URL_PDF_A5 O
URL_PDF_10x15 O
^[0-9A-Z]{2}[0-9A-Z ]{6}$
This parameter is the merchant id code given in the document of
parameters.
^[0-9]{1,3}$
Status number
^[0-9A-Z]{32}$
Security code.
Out parameters
Facultative /
Parameters Comment
Obligatory
Name
Status codes
Each answer to a web service request gives a status code for this request.
The following list gives the link between the code and the error name for the dysfunction correction.
Please note that the answer code 0 indicates the request is correct and was received successfully.
However some requests like tracking requests don't give 0 but other codes for status of the
shipment are posted.
0 Successfull operation
1 Incorrect merchant
16
17
18
19
23
25
32
35 Incorrect city
36 Incorrect zipcode
37 Incorrect country
39 Incorrect e-mail
40 Missing parameters
41
49 Incorrect action
50
51
52
53
54
Status code Description
55
56
57
58
59
63 Incorrect insurance
65 Incorrect appointement
67 Incorrect latitude
68 Incorrect longitude
72
73
74 Incorrect language
Status code Description
75
76
77
90
91
92 The Point Relais country code and the consignees country code are different.
94 Unknown parcel
96
This error hides another error from the list and can only happen in production mode.
Please notify this error to Mondial Relay with the date and time of the request as well
as the parameters sent in order to verify
As MD5 hash follows a string concatenation, we will gradually increase the size of the chain by
feeding it one field after another.
So in the first query just fill both fields Enseigne and Security
If the status of the request is different from 97, all is well.
Add the next field and send the new request.
If the status of the request is different from 97, all is well.
And we start again until the query status is 97.
In this case, we found the field with the error.
Maybe the value of the field is misinterpreted for the MD5 hash (greater than 126 characters
in the code page).
Maybe the field name is misspelled. It may miss a letter for example.
C# language
Hash MD5 generation function (Message Digest 5)
public static string GetMd5(string Args)
{
string resultat = "";
System.Security.Cryptography.MD5CryptoServiceProvider MD5_Provider
= new System.Security.Cryptography.MD5CryptoServiceProvider();
byte[] buffer = System.Text.Encoding.Default.GetBytes(Args);
buffer = MD5_Provider.ComputeHash(buffer);
foreach (byte b in buffer) { resultat += b.ToString("X2"); }
return resultat;
}
When you obtain the dialogbox Add a web reference , mention the Mondial Relay service URL into
the address zone, validate.
The Mondial Relay methods are posted on the left side of the dialogbox.
Choose a name for the web reference, e.g : WS_MondialRelay then clic on Add the reference .
This code example does a Points Relais search (mode of delivery 24R) in a radius of 20Km in France,
around the 75010 zip code in which the trade type can be defined
<?php
require_once('lib/nusoap.php');
// We define the parameters as a string array. Each Key/Val represents a parameter of the
soap call
// On dfini les paramtres dans un tableau de chanes. Chaque paire Cl/Valeur est un
paramtre de l'appel SOAP
$params = array(
'Enseigne' => $MR_ WebSiteId,
'Pays' => "FR",
//'NumPointRelais' => "",
'Ville' => "",
'CP' => "75010",
'Latitude' => "",
'Longitude' => "",
'Taille' => "",
'Poids' => "",
'Action' => "",
'DelaiEnvoi' => "0",
'RayonRecherche' => "20",
//'TypeActivite' => "",
//'NACE' => "",
);
sParams = _
"<?xml version=""1.0"" encoding=""utf-8""?><soap12:Envelope
xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance""
xmlns:xsd=""http://www.w3.org/2001/XMLSchema""
xmlns:soap12=""http://www.w3.org/2003/05/soap-envelope"">" &_
"<soap12:Body>" &_
"<WSI3_PointRelais_Recherche xmlns=""http://api.mondialrelay.com/"">" & _
"<Enseigne xsi:type=""xsd:string"">BDTEST12</Enseigne>" & _
"<Pays xsi:type=""xsd:string"">FR</Pays>" & _
"<NumPointRelais xsi:type=""xsd:string""></NumPointRelais>" & _
"<Ville xsi:type=""xsd:string""></Ville>" &_
"<CP xsi:type=""xsd:string"">75010</CP>" & _
"<Latitude xsi:type=""xsd:string""></Latitude>" & _
"< Longitude xsi:type=""xsd:string""></Longitude>" & _
"<Taille xsi:type=""xsd:string""></Taille>" &_
"<Poids xsi:type=""xsd:string""></Poids>" &_
"<Action xsi:type=""xsd:string""></Action>" &_
"<DelaiEnvoi xsi:type=""xsd:string""></DelaiEnvoi>" &_
"<RayonRecharche xsi:type=""xsd:string""></RayonRecharche>" &_
"<TypeActivite xsi:type=""xsd:string""></TypeActivite>" &_
"<Security xsi:type=""xsd:string"">" & security & "</Security> &_
"</WSI3_PointRelais_Recherche>" &_
"</soap12:Body></soap12:Envelope>"
requestXML.send sParams
%>