Colissimo Delivery Options I-Frame Page · 2020-02-29 · Simplicité – Colissimo "Delivery Options" I-Frame Page – November 2015 4 5.0 19/03/2012 Integration of the "Delivery

La Poste – A Limited Liability Company (SA) with capital of 3,800,000,000 euros – 356 000 000 RCS PARIS

Head office: 44 BOULEVARD DE VAUGIRARD - 75757 PARIS CEDEX 15 - Phone: +33 (0)1 55 44 00 00

Simplicité - Delivery Options Business solutions

Colissimo "Delivery Options" I-Frame Page Technical document – version November 2015

Implementation guideline of the "Delivery Options" I-Frame Page

Simplicité – Colissimo "Delivery Options" I-Frame Page – November 2015

2

Change History

Revision Date Comments

2.4 16/04/2010 • Addition of the production URL in the Parameter sending examples (paragraph III.5.10.3)

• Update of the error codes (paragraph III.6.3) • Supervision URL added (paragraph III.7.4) • Update of the names of parameters for delivery mode,

commercial name and error fields (paragraph III.8.1) • Update of the parameter names (paragraph III.8.2)

2.5 27/04/2010 • Update of Parameter sending examples (paragraph III.5.10.3)

• Updated the supervision URL (paragraph III.7.4)

2.6 30/04/2010 • Updated the error code field (paragraph III.8.1) • Updated the conditions of sending of error fields

(paragraph III.8.1)

2.7 07/05/2010 • Correction: the number of characters of the signature is 40 (paragraphs III.5 and III.5.9)

• Clarification about error names (paragraph III.6.3) • Clarification about error code return (paragraph III.8.1) • Correction of parameter name and first name title error

(paragraph III.8.1) • Clarification about error code return (paragraph III.8.2) • Updated sub-paragraph numbers of paragraphs III.6 and

III.7` • MSG.159 The ‘ character is authorized (paragraph III.6.1) • Correction of the CEADRESS1 heading (paragraph III.8.1) • Clarification about the signature: must be in lower case

and ISO (paragraph III.5.9)

2.8 11/06/2010 • Updated the Contact section (paragraph I.3) • Clarification about the URL of the "Delivery options" page

(paragraph III.1) • Clarification about the protocol used (paragraph III.3)


3

3.0 15/06/2010 • Methods for sending input parameters: added a parameter using GET (paragraph III.5)

• Sending output parameters: added a parameter using GET (paragraphs III.8.1 and III.8.2)

• Updated Sending examples (paragraph III.5.10.3) • Clarification about parcel weight check (paragraph

III.5.6.4) • Clarification about order preparation time check (paragraph

III.5.6.1) • Clarification about BO configuration (paragraph III.5.10.3) • MSG.159 the & character is authorised (paragraph III.6.1) • Clarification about cases generating the error codes 002

and 003, deletion of code 014, addition of code 015 (paragraph III.6.2)

• Clarification about codes 132 and 133 (paragraph III.6.3) • Modification of DBMS error code unavailable (paragraph

III.7.1) • Added paragraph on cookie (paragraph III.4) • Clarification about "retour" (return) button (paragraph

III.1) • Added URL return upon failed output (paragraphs III.8.1

and III.8.2) • Case of error code 015 at output (paragraph III.8.2)

3.1 15/07/2010 • Clarification about total forwarding charges at validation output (paragraph III.8.1)

4.0 12/10/2010 • Addition of special characters (paragraphs I.2 and III.6.1) • Clarifications about modifications to back office data

(paragraphs II.3.2, II.4.2, Erreur ! Source du renvoi introuvable. and II.6.2.2)

• Clarification about the commercial name (paragraph II.7.2.1)

• Addition of the Version number input parameter (paragraphs III.5.1, III.5.6.7 and III.6.2)

• Clarification about return forwarding charges (paragraph III.5.6.2)

• Clarification about the weight format (paragraph III.5.6.4) • Modification about the input signature calculation rules

(paragraph III.5.9.1) • Examples of calling the page updated (paragraph

III.5.10.3) • Modification about the output signature calculation rules

(paragraph III.8.1.2, III.8.1.4 and III.8.2.1) • Inclusion of routing information for customers using a

specific LIBERTE labelling solution (paragraphs III.8.1.3 and III.8.1.5)

• Example of signature calculation in Javascript (paragraph IV)

4.1 01/07/2011 • Update of the page screen shot (paragraph III.2) • Update of error messages displayed on the page

(paragraph III.6.1) • Increase in maximum logo size (paragraph II.6.2.2) • Number of characters in the corporate name (paragraph

II.7.2.1)


4

5.0 19/03/2012 Integration of the "Delivery options" page in the IFrame version. • Introduction to IFrame version (paragraph I.1) • Terminology: presentation of Interstitial and IFrame

versions (paragraph I.2) • Addition of settings of IFrame version (paragraph II.1) • Particularity of IFrame version logo (paragraph II.7) • New setting of IFrame version (paragraph II.7.2.2) • URL of the IFrame version and definition of the steps of the

page (paragraph III.1) • Presentation of the IFrame version page (paragraph III.2) • Update of error handling for the IFrame version (paragraph

III.6) • Reminder about not using special characters in call settings

(paragraph III.5) • Precision about ISO-8859-1 encoding (paragraph III.5.7) • Supervision URL of the IFrame version (paragraph III.7.4) • Annex 1 update of the fields of the page for the IFrame

version (paragraph IV) • Addition of Annex 3 Example of an IFrame call method

using POST • Addition Annex 4 Exit from the IFrame

The rules for calculating the signature defined in this document need to be applied to this IFrame version (ref. version 4.0 of 12/10/2010 of this document).

5.1 04/06/2012 Information about including additional pick-up locations, allowing parcels weights and dimensions up to 30kg and 200cm in combined size (L+W+H).

• Information about the optimal use of these points (paragraph III.5.6.4: Parcel weight)

5.2 03/04/2013 Addition of information about: • Opening up of the Colissimo solution internationally (3 new

parameters for delivery to Belgium: see III.5.7) • A new parameter allowing you to apply a specific price to

deliveries to French Pick-Up Locations (paragraphs III.5.6.2) • Possibility of calling the SO "Delivery options" page with

UTF-8 encoding (paragraphs III.5.8) • Important change: increase in version of the signature to

4.0 (paragraphIII.5.9) Deletion of paragraph " II.6.2.2 Logo"

5.3 22/11/2013 Significant change: in the return parameters, the TRRETURNURLKO variable (return URL in case of failure) is now transmitted in POST mode only (paragraph III.8)

5.4 26/02/2014 Change of the "civilité" (title) input parameter: deletion of the "Mlle" (Miss) option

5.5 26/06/2014 Multilingualism

5.6 November 2015

Update of naming and new solution of January 2016


5

I. INTRODUCTION ............................................................................................ 8

I.1 Purpose of the Document ............................................................................... 8

I.2 Terminology ................................................................................................. 8

I.3 Contact ........................................................................................................ 9

II. DELIVERY BACK OFFICE ................................................................................. 9

II.1 General .................................................................................................. 10

II.2 Access to the Delivery Back Office ............................................................. 10

II.3 Configuring the "Delivery options" Page ..................................................... 11

II.3.1 Overview ............................................................................................ 12

II.3.2 Configuration ...................................................................................... 12

II.4 Order preparation time ............................................................................ 14

II.4.1 Overview ............................................................................................ 14


II.5 "To the post office" Delivery Price .............................................................. 16

II.6 Surcharge for delivery to Belgium .............................................................. 16

II.6.1 Overview ............................................................................................ 16


II.7 Customisation of the "Delivery options" Page ............................................. 19

II.7.1 Overview ............................................................................................ 19


II.7.2.1 Commercial name ............................................................................. 21

II.7.2.2 Validation page ................................................................................ 21

II.8 Help ...................................................................................................... 22

II.9 Integration guide ..................................................................................... 22

III. "Delivery options" page ................................................................................ 22

III.1 General ............................................................................................... 22

III.2 Overview ............................................................................................. 23

III.2.1 Format ............................................................................................... 23

III.2.2 Step 1 ................................................................................................ 24

III.2.3 Step 2 ................................................................................................ 25

III.2.4 Step 3 ................................................................................................ 29

III.3 Protocol ............................................................................................... 29

III.4 Cookie ................................................................................................. 29

III.5 Call parameters .................................................................................... 30

III.5.1 Call parameters to send using the POST method ...................................... 30

III.5.2 Call parameters to send using the GET method ....................................... 33

III.5.3 Parameter length check ........................................................................ 33

III.5.4 Your FO identifier ................................................................................. 34

III.5.5 Information on the addressee ............................................................... 34

III.5.5.1 addressee title ................................................................................. 34


6

III.5.5.2 Company name ................................................................................ 34

III.5.5.3 Addressee address field ..................................................................... 34

III.5.6 Information on the order ...................................................................... 35

III.5.6.1 Order preparation time ...................................................................... 35

III.5.6.2 Forwarding charges........................................................................... 35

III.5.6.3 Transaction number .......................................................................... 36

III.5.6.4 Parcel weight ................................................................................... 36

III.5.6.5 First order parameter ........................................................................ 38

III.5.6.6 Shipper plus parameter ..................................................................... 38

III.5.6.7 Version number ................................................................................ 38

III.5.7 International ....................................................................................... 38

III.5.7.1 International Option .......................................................................... 38

III.5.7.2 Country of delivery ........................................................................... 39

III.5.7.3 Language ........................................................................................ 39

III.5.8 Encoding of the pages .......................................................................... 40

III.5.9 Signature ........................................................................................... 40

III.5.9.1 Calculation of the input signature ....................................................... 40

III.5.10 Return URL ......................................................................................... 41

III.5.10.1 "Validation" return URL ..................................................................... 41

III.5.10.2 "Failed" return URL ........................................................................... 42

III.5.10.3 Preliminary tests using a web browser ................................................ 43

III.5.10.4 Introduction .................................................................................... 43

III.5.10.5 Sending example with the mandatory parameters ................................ 43

III.5.10.6 Example of sending all parameters ..................................................... 44

III.6 "Error management" ............................................................................. 46

III.6.1 Error messages displayed in the "Delivery options" page .......................... 46

III.6.2 Error codes returned to the shipper on the Failure return URL ................... 48

III.6.3 Information codes returned to the shipper on the Validation return URL ..... 49

III.7 Unavailability and continuity of the order process ..................................... 50

III.7.1 DBMS down ........................................................................................ 50

III.7.2 Application server down........................................................................ 50

III.7.3 IT system down ................................................................................... 50

III.7.4 Order process continuity ....................................................................... 51

III.7.5 Internal error page .............................................................................. 51

III.8 Parameters for return to your web site .................................................... 52

III.8.1 Returns to Validation return URL............................................................ 52

III.8.1.1 Return for Home delivery options ....................................................... 52

III.8.1.2 Output signature for the home delivery options .................................... 58

III.8.1.3 Return for the delivery options in pick-up locations ............................... 61

III.8.1.4 Output signature for pick-up location delivery options ........................... 67

III.8.1.5 Routing information .......................................................................... 69

III.8.1.6 Network code ................................................................................... 69

III.8.2 Returns to Failure return URL ................................................................ 70

III.8.2.1 Output signature in case of failure ...................................................... 74

IV. Annexes ..................................................................................................... 76

IV.1 Annex 1: Field of the "Delivery options" page ........................................... 76

IV.2 Annex 2: Example of the calculation of an SHA signature in Java and Javascript ....................................................................................................... 77

IV.3 Annex 3: Example of an IFrame call method using POST ........................... 81


7

IV.4 Annex 4: Exit from the IFrame ............................................................... 83


8

I. INTRODUCTION

I.1 Purpose of the Document

Directly accessible from your web site, the Colissimo "Delivery options" page allows your customers to select their delivery mode.

This document describes the technical guidelines for integrating the Colissimo "Delivery options" page on your Web site.

The solution comprises 2 modules:

• The So Delivery Back Office (BO), which is accessible on www.laposte.fr/colissimo-entreprise and allows you configure the settings for the "Delivery options" Page using IFrame.

• The Front Office (FO) page or "Delivery options" Page, which is the La Poste - Colissimo hosted web page you redirect your customer to select his delivery options at the end of the purchasing process.

I.2 Terminology

Term Description Shipper E-merchant customer of La Poste - Colissimo Merchant site Shipper’s web site Purchaser Internet user, customer of the shipper Pick-up location Place of delivery to a pick up location, where

the addressee can pick up the parcel. Block Geographical zone representing a housing

block, i.e. a part of French territory bounded by roads and in line with the naming scheme defined by the INSEE

Working days From Monday to Friday excluding public holidays

Alphanumeric character Designates:

• numeric characters • alphabetical characters (lower case

and upper case), • lower case accented characters and

'ç' • as well as special characters

except: ;€~#{([|\^)]=}$¤£%µ*§!°²

unless otherwise specified SHA1 Cryptographic hashing function Secures the

call to and response from the "Delivery options" Page


9

I.3 Contact

La Poste - Colissimo provides you with support, which we advise you to call in the following cases:

Preliminary study &

Solution deployment

For any technical issue related with the solution described in this document:

• Customer Solutions Support,at 0241.742.088,from Monday to Friday, 9 am to 6 pm.

To confirm the solution chosen:

• Your Colissimo sales contact

Operational phase,

after solution deployment

In case of failure, anomaly or incident:

• The Service Centre on 0825.086.005, from Monday to Friday, from 8am to 6pm. Say "Incident", then "Solutions Web", when prompted to choose.

The availability and proper operation of our systems are supervised, even outside these hours.

II. DELIVERY BACK OFFICE


10

II.1 General

The Delivery Back Office is accessible on http://www.coliposte.fr/colissimo-entreprise using the login and password received by email when subscribing to the Colissimo service. On this site, you will retrieve the identifier and the encryption key that will enable you to access to the "Delivery options" Page:

Customised information Description Corresponding page

Front Office identifier Your unique shipper Identifier

Enables La Poste - Colissimo to identify the calling shipper

Configuration

SHA1 encryption key Encryption key unique to the shipper

Secures the data transfer

Configuration

You must also update the following settings:

Configuration Mandatory Comment

Configuration – URL’s returning to your web site

Yes Enables La Poste - Colissimo to redirect the purchaser back to the shipper’s web site, once the delivery options are chosen

Order preparation time Optional (can also be sent in your call parameters)

Logistics preparation time

Additional cost for delivery to Belgium

No Surcharge applied to forwarding charges for delivery to Belgium

Commercial name Yes Customisation of the "Delivery options" Page in the Interstitial and IFrame versions

Download your logo No Customisation of the Interstitial version "Delivery options" Page

Activation of step 3 - Validation

No Customisation of the IFrame version "Delivery options" Page

II.2 Access to the Delivery Back Office The Delivery Back Office is accessible via the "Applications" tab in your Customer web account.


11

II.3 Configuring the "Delivery options" Page The configuration of the "Delivery options" page is possible via the "Configuration" link present in the Delivery Back Office.


12

II.3.1 Overview

II.3.2 Configuration The following fields must be filled in and used to have access to the "Delivery options" Page:


13

Field Type Mandatory Comment

Encryption key 12 numeric characters Yes, cannot be modified

Unique key allocated by the Delivery solution

To be sent in the call parameters, see paragraph III.5 Call parameters

Front Office identifier

14 numeric characters Yes, cannot be modified

Unique identifier sent by the Delivery solution

To be sent in the call parameters, see paragraph III.5 Call parameters

"Validation" return URL

Up to 256 alphanumeric characters meeting the URL format

Yes, both URLs can be identical

It is the URL to which the Internet user is redirected after choosing his delivery options in the "Delivery options" Page

"Failed" return URL

Up to 256 alphanumeric characters meeting the URL format

It is the URL to which the Internet user is redirected in case of failure when calling the "Delivery options" Page

When first entered, the data are immediately updated in La Poste - Colissimo’s systems on validation of the "Configuration of the ‘Delivery options’ Page". When calling the "Delivery options" page, this information is cached for 1 hour. If back office information is changed, it will therefore be taken into account on the "Delivery options" Page 1 hour at the most after the information has been entered.


14

II.4 Order preparation time

Updating the usual order preparation time is possible via the "Délai de preparation de commande" (order preparation time) link present in the Delivery Back Office.

II.4.1 Overview


15

II.4.2 Configuration

Your order preparation time enables La Poste - Colissimo to identify the pick-up locations that are open on the day of delivery of the parcel. The parcel delivery lead time is then determined by adding the order preparation time to the transit time of the parcel by La Poste - Colissimo.


Order preparation time Up to 2 numeric characters

Yes

The default value is 3 working days.

Its value cannot be zero. A working day here means from Monday to Friday excluding public holidays. When first entered, the data are immediately updated in La Poste - Colissimo systems on validation of the "Configuration of the ‘Delivery options’ Page". When calling the "Delivery options" page, this information is cached for 1 hour. If back office information is changed, it will therefore be taken into account on the "Delivery options" Page 1 hour at the most after the information has been entered. The shipper can also send the order preparation time in the call parameters of the "Delivery options" Page. The lead time may therefore be set or variable depending on the orders. If the lead time is passed as a parameter when calling the page and the time is entered in the Back Office, the usual value is ignored and the call parameter value applies.


16

II.5 "To the post office" Delivery Price Updating the surcharge for specified time-slot delivery “à la Poste” is possible via the "Surcoût livraison à la Poste" link present in the Delivery Back Office.

II.6 Surcharge for delivery to Belgium Updating the surcharge for delivery to Belgium is possible via the "Surcoût livraison en Belgique" link present in the Delivery Back Office.

II.6.1 Overview


17


18


The surcharge for delivery to Belgium is the amount the shipper wishes to charge its customers when they choose delivery in Belgium, at home or at a pick up location. If you do not wish to offer delivery to Belgium on your merchant site, you do not need to set this field. This information appears on the "Delivery options" Page. By default, the surcharge applied is €1.80 inc-VAT. It is the amount invoiced by La Poste - Colissimo to the shipper for this service at the time of launching the Colissimo delivery to Belgium. It is a mandatory field, nevertheless its value can be:

• zero ("0") if the shipper wishes to office this service at no extra cost to its customers • negative (via the drop-down list "+/-" to the left of the surcharge field), if the shipper

wishes to apply a lower price to delivery in France for this service


"+/-" selector Drop-down list Yes N/A

Surcharge for delivery to Belgium

Up to 5 alphanumeric characters

Yes Separators accepted: "," or ". "

When first entered, the data are immediately updated in La Poste - Colissimo systems on validation of the "Configuration of the ‘Delivery options’ Page". When calling the "Delivery options" page, this information is cached for 1 hour. If back office information is changed, it will therefore be taken into account on the "Delivery options" Page 1 hour at the most after the information has been entered.


19

II.7 Customisation of the "Delivery options" Page Customising the "Delivery options" page is possible via the "Personnalisation de la page" link present in the Delivery Back Office.

The "Delivery options" IFrame Page does not include any logo. This parameter will not be used for the "Delivery options" IFrame version Page. The interstitial version of the "Delivery options" Page is now obsolete and is no longer supported. However, some existing accounts still use this version of the application, which is why some screens in this document mention it.

II.7.1 Overview


20


21


II.7.2.1 Commercial name


Commercial name Up to 35 alphanumeric characters

Yes

The customer's commercial name; this value can be different from the "Corporate name" recorded in the La Poste - Colissimo systems.

The commercial name is used to customise emails and SMS messages sent to the parcel addressee by La Poste Colissimo. In order to do so, it must be sent to your La Poste - Colissimo labelling solution.

It appears on the "Delivery options" Interstitial version Page as a caption when the mouse pointer is above the logo

II.7.2.2 Validation page

On the "Delivery methods" IFrame version Page, a summarising validation page of the selected delivery method and the total shipping cost is offered. This page is optional and it is disabled by default. If you wish to enable it, you can check the "yes" box on the customisation screen of the "Delivery options", IFrame version Page. When first entered, the data are immediately updated in La Poste - Colissimo systems on validation of the "Personalisation of the Page ‘Delivery options’ " Page. When calling the "Delivery options" page, this information is cached for 1 hour. If back office information is changed, it will therefore be taken into account on the "Delivery options" Page 1 hour at the most after the information has been entered.


22

II.8 Help

The "Aide" link provides access to the FAQ.

II.9 Integration guide

The "Guide d’Integration" link provides access to the latest version of this document.

III. "Delivery options" page

III.1 General

The "Delivery options" page is the web page hosted by La Poste - Colissimo to which your customer is redirected in order to choose a delivery option. The URL for the "Delivery options" IFrame version page is: http or https://ws.colissimo.fr/pudo-fo-frame/storecall.do Access to the "Delivery options" IFrame version Page is conditional on the use of the above URL as well as the provision of the following information: • FO identifier supplied by La Poste - Colissimo • Personal data of the Internet user • Data associated with the order • SHA1 signature using the encryption key supplied by La Poste - Colissimo If the information sent is incorrect, the Internet user is redirected to the failure return URL of your merchant site, an error code is sent to you in the return parameters (see the list of return error codes in paragraph III.6.2). If the information sent is correct, the Internet user is redirected to the "Delivery options" Page to select a delivery option. Choosing the delivery option is performed in 3 steps: • Step 1: Input of personal information. This step is optional and is presented to the user

if one of the mandatory personal data items is missing or if one of the expected formats is not respected.

• Step 2: Choice of the delivery option. The delivery options are proposed according to the address sent in the call parameters or input in step 1. If the Internet user is recognised (via a cookie), the last delivery option chosen is checked by default The Internet user can change his address to have other delivery options or pick-up locations. He can view the 20 closest locations in the form of a list or on a map.

• Step 3: Validation of the summary of the selected delivery location. This step is optional, it is presented to the user only if you have enabled this option in your customer BackOffice (see II.7.2.2).


23

Once the delivery option is chosen, the Internet user is redirected to the "Validation" return URL of your merchant site, the information entered or selected in the "Delivery options" page are sent to you.

III.2 Overview

III.2.1 Format The "Delivery options" IFrame version page is especially designed to be integrated using IFrame in your website’s Front-Office. The width of the page is as follows:

1100px

La Poste - Colissimo


24

The height of the frame may vary depending on the content to be displayed.

III.2.2 Step 1 This step is optional and is presented to the user if one of the mandatory personal data items is missing or if one of the expected formats is not respected. It is composed of several blocks: 1. A header block containing the Colissimo logo and the breadcrumb trail (non-clickable) 2. A block for entering personal information related to delivery 3. A validation block of the step 4. An information block The error messages related to this step are displayed at the top of block 2.


25

III.2.3 Step 2 Step 2 consists of two pages: Page 1 - delivery options, made up of several blocks: 1. A header block containing the Colissimo logo and the breadcrumb trail (non-clickable) 2. A block offering the home delivery option 3. A block for choosing a delivery mode from a pick-up location 4. A block for validating the choice of delivery mode


26

The total cost of the shipping costs for each delivery option is displayed in parentheses, to the right of each description, depending on the chosen delivery option and the country of delivery (see the rules in III.5.6.2). A single price may also be applied for deliveries to Belgian pick-up locations (displayed in area 5). Where the mobile phone is mandatory for the selected delivery option, if this has not been filled in beforehand, a popup will be displayed on the page to allow the web use to complete it.

4

2

1

3


27

Page 2 - pick-up locations, made up of several blocks: 1. A header block containing the Colissimo logo and the breadcrumb trail (non-clickable) 2. A block containing the reference delivery address (including the country) and the possibility to change it 3. A block allowing filters to be made on the list of eligible pick-up locations 4. A map block, showing pick-up locations and details about a pick-up location 5. A block containing the eligible pick-up locations list, with the distance in relation to the reference delivery address. 6. A block for validating the choice of pick-up location 7. An information block

La Poste - Colissimo promises to use your contact details

only for your parcel delivery


28

1

2

3

4

5

1

2

3

4

5

6

7


29

III.2.4 Step 3 This step is optional, it is presented to the user only if you have enabled this option in your customer BackOffice. It is composed of several blocks: 1. A header block containing the Colissimo logo and the breadcrumb trail (non-clickable) 2. A block summarising the chosen delivery option (including the delivery country) and the web user’s personal information 3. A block indicating the information required for notification to the addressee (NAD) with email/mobile phone 4. A block listing the total shipping costs expressed in euros inc-VAT 5. A block for validating the choice of delivery mode 6. A block for modifying the choice of delivery mode

III.3 Protocol

The protocol used is http, or its secured variant https.

III.4 Cookie The "Delivery options" page displays the last delivery option or pick-up location chosen via a cookie.

1

2

3

4

5

6


30

The last delivery option or pick-up location will be checked by default. The choice of the display language made by the user is also recorded in this cookie to show the frame in this same language for his future visits. This function is available only if the Internet user’s browser authorises the use of cookies.

III.5 Call parameters The parameters must be sent in the POST method, except for the "failed" return URL, which is the only parameter sent using both the GET and POST methods (with the same value). This ensures the continuity of service in the event of technical unavailability of La Poste - Colissimo’s system (see detail in paragraph III.7 Unavailability and continuity of the order process). Note:

• It is recommended that you do not use special characters in the call parameters. • The call parameters must have an ISO-8859-1 or UTF-8 encoding format. The

encoding type must be entered in the call parameter "Page encoding" (see III.5.8Encoding of the pages).

III.5.1 Call parameters to send using the POST method

Field Manda

tory Parameter

name Modifiable in the FO page

Type Parameter

length check

FO identifier Yes pudoFOId Does not appear

14 numeric characters

Information on the addressee

addressee title

No ceCivility Yes MR/MME(MRS)

Only these formats will be accepted (not case-sensitive)

addressee last name

No ceName Yes Up to 34 alphanumeric characters

Yes

addressee first name

No ceFirstName Yes Up to 29 alphanumeric characters

Yes

Company name

No ceCompanyName Yes Up to 38 alphanumeric characters

Yes

Floor, corridor, staircase, apartment no.

No ceAdress1 Yes Up to 38 alphanumeric characters

Yes

Entrance, building, residence


Yes

Number and street name


Yes

Named place or other particular information


Yes


31

Postcode No ceZipCode Yes 5 alphanumeric characters

Authorized: 01XXX to 95XXX, 980XX and ADXXX

Municipality No ceTown Yes Up to 32 alphanumeric characters

Yes

Country of delivery

No (FR by default)

cePays Yes if "option international" parameter = 1

2 alphanumeric characters (country code according to ISO 3166)

Possible values: FR (by default) or BE

Intercom No ceEntryPhone Yes Up to 30 alphanumeric characters

Yes

Other delivery instructions

No ceDeliveryInformation

Yes Up to 70 alphanumeric characters

Yes

Email No ceEmail Yes Up to 80 alphanumeric characters

Format [email protected]

Yes

Mobile phone No cePhoneNumber Yes Up to 12 alphanumeric characters

Must begin with 06 or 07 if the country is France, and by +324 if the country is Belgium

Yes

Door code No ceDoorCode1 Yes Up to 8 alphanumeric characters

Yes

Door code 2 No ceDoorCode2 Yes Up to 8 alphanumeric characters

Yes

Information on the order

Order preparation time

No dyPreparationTime

Does not appear

Up to 2 numeric characters In working days (Monday to Friday)

Forwarding charges

Yes dyForwardingCharges

No 1 to 5 alphanumeric characters

In € taxes included Separators "." or ". " or ". "

Shipping

costs Pick-up Location

No dyForwardingChargesCMT

No Price reserved for

delivery to Pick-up


32

Locations in France

1 to 5 alphanumeric characters

In € taxes included

Separators "." or ". " or ". "

Web client no.

No trClientNumber Does not appear


Yes

Order no. No trOrderNumber Does not appear


Yes

Transaction no.

Yes orderId Does not appear

5 to 16 alphanumeric characters

This number must be unique for each call

Parcel weight No dyWeight Does not appear

Up to 5 numeric characters

Expressed in grams

1st order No trFirstOrder Does not appear

Boolean

1(Yes): Pick-up locations will not be proposed

0(No): Pick-up locations will be proposed

Shipper plus parameter

No trParamPlus Does not appear


Yes

International International Option

No

(0 by default)

trInter Does not appear

1 numeric character

0 for France 1 for France and International 2 for International

addressee language

No (FR by default)

ceLang Does not appear

2 alphanumeric characters (according to ISO 639-1 Alpha2 standard)

Can equal "FR" (default), "EN", or "NL"

Request check

Version number

Yes numVersion Does not appear

3 alphanumeric


33

characters

Transmit the value "4.0"

See paragraph

III.5.6.7 Version number

Signature Yes signature Does not appear

40 alphanumeric characters

See paragraph

III.5.9 Signature

Page encoding

No (ISO-8859-1 by default)

CHARSET Does not appear

Set to: ISO-8859-1 or UTF-8

URL returning to the shipper site in case of success

No trReturnUrlOk Does not appear


http:// or https://

URL returning to the shipper site in case of failure

Yes trReturnUrlKo

Does not appear


http:// or https://

III.5.2 Call parameters to send using the GET method

Field Manda

tory Parameter name

Modifiable in the FO page

Type Parameter

length check

URL returning to the shipper site in case of failure

Yes trReturnUrlKo

Does not appear


http:// or https://

III.5.3 Parameter length check


34

If the length of the parameters described above exceeds the authorised length defined in the table, the end of the character string will be truncated to the authorised length. When the Internet user has completed the delivery option selection process, a return code is sent to the validation return URL indicating the truncated. See information codes in paragraph III.6.3.

III.5.4 Your FO identifier It is the identifier displayed in the "Configuration de la page" "Delivery options" page of the Delivery Back Office. If the FO identifier is: • not filled or • unknown to the application or • corresponding to a customer account terminated by La Poste - Colissimo, Access to the "Delivery options" page will not be authorised. The Internet user will be redirected to the Failure return URL. An error code will be sent, see error codes in paragraph III.6.2.

III.5.5 Information on the addressee

III.5.5.1 addressee title

If the format is not correct, the value will be ignored. The title ("civilité") field will not be checked on the "Delivery options" page. When the Internet user has completed the delivery option selection process, a return code is sent to the validation return URL with the invalid parameter. See information codes in paragraph III.6.3.

III.5.5.2 Company name

If the company name field is filled in, the "Delivery options" page takes account of this information.

III.5.5.3 Addressee address field

The information in the addressee address field determines the possible delivery options available for the Internet user. In case of an invalid postcode, access to the "Delivery options" page will not be authorised. The Internet user will be redirected to your Failure return URL. An error code will be sent, see error codes in paragraph III.6.2. Country of delivery: • If the "international option" parameter is set to 0, the country must be set to "FR" • If the "international option" parameter is set to 1, the country may be set to either "FR"

or "BE" • If the "international option" parameter is set to 2, the country must be set to "BE" If these conditions are not met, the user will be redirected to your failure return url. An error code will be sent, see error codes in paragraph III.6.2.


35

III.5.6 Information on the order

III.5.6.1 Order preparation time

In addition to the configuration made in the Back Office, an order preparation time can be included to the call parameters. The lead time may therefore be set or variable depending on the orders. If the lead time is passed as a parameter when calling the page and the time is entered in the Back Office, the usual value is ignored and the call parameter value applies. If the numeric format or size of the field is not observed upon the call, the usual order preparation time entered in the Back Office is applied. This also applies when the order preparation time is sent with a value equal to 0. When the Internet user has completed the delivery option selection process, an return code is sent to the validation return URL with the invalid parameter. See information codes in paragraph III.6.3.

III.5.6.2 Forwarding charges

There are two calling parameters for handling forwarding charges • "Forwarding charges"

The parameter is mandatory; these are the forwarding charges that the shipper wishes to apply by default for all delivery options in France.

• "Pick-up Location Forwarding Charges" This parameter is optional. It allows the shipper to apply a different price for delivery to Pick-Up Locations in France. If it is not passed, it defaults to the value of the "forwarding charges" parameter.

Surcharges may then be applied from the Back Office:

• For delivery in Belgium (see 0 • Surcharge for delivery to Belgium).

The forwarding charges and the Pick-Up Location forwarding charges must be between 1 and 5 alphanumeric characters with the "." or "," separator. Only the "forwarding charges" parameter is mandatory. If one of these criteria is not observed, access to the "Delivery options" page will not be authorised. The Internet user will be redirected to your Failure return URL. An error code will be sent, see error codes in paragraph III.6.2. The following table summarises the values used for calculating the total forwarding charges according to the delivery option and country chosen. Delivery option Total forwarding charges for delivery in

France Total forwarding charges for

delivery in Belgium At the following address

Forwarding charges Forwarding charges + Belgium surcharge configured in the back office

La Poste Pick-Up Location

Forwarding charges Forwarding charges + Belgium surcharge configured in the back office

In a Pick-Up Locker Station

Forwarding charges Not applicable

Pick-Up Location Pick-Up Location forwarding charges (if they Forwarding charges + Belgium


36

are not passed: Forwarding charges) surcharge configured in the back office All forwarding charges appear in euros, taxes included, on the "Delivery options" page. The format of the total of the shipping charges re-passed by the "Delivery Options" page is from 1 to 6 alphanumeric characters with the separator "." only. The forwarding charges returned by the "Delivery options" page have no legal value and may not replace the true calculation of the customer's forwarding charges by the shipper. Note:

• To offer the forwarding charges (except for Pick-Up Locations) to your customer, the "forwarding charges" parameter must be passed with a value of zero ("0")

• To offer delivery to a Pick-Up Location, you will need to pass the "Pick-Up Location forwarding charges" parameter a value of zero ("0"), regardless of the value of the "forwarding charges" parameter. Where the parameter is not passed, its value defaults to the value of the "forwarding charges" field.

III.5.6.3 Transaction number

Each call must be accompanied with a unique transaction number. Therefore, your web site must generate a new transaction number at each call. You are free to generate this number incrementally or otherwise (e.g. from the current date and time in milliseconds with the usual precautions guaranteeing uniqueness). The transaction number must be: • filled • between 5 and 16 alphanumeric characters If one of the criteria is not observed, access to the "Delivery options" page will not be authorised. The Internet user will be redirected to your Failure return URL. An error code will be sent, see error codes in paragraph III.6.2.

III.5.6.4 Parcel weight This information is used to filter out pick-up locations with a maximum weight authorised below or equal to the parcel’s weight. If the numeric format or size of the field is not observed, this value is ignored, the pick-up locations are hence not filtered on this criterion. This also applies if the weight is sent with a value equal to 0. When the Internet user has completed the delivery option selection process, a return code is sent to the validation return URL with the invalid parameter. See information codes in paragraph III.6.3. The weight must be sent in grams (no separator). Particularity of the ACP and CDI types of pick-up locations:


37

• Colissimo Parcel Agency (paragraph III.8.1.1, for these pick-up locations, the DELIVERYMODE field returned by the page, takes the value "ACP")

• Mail Centre (paragraph III.8.1.1, for these pick-up locations, the DELIVERYMODE field returned by the page, takes the value "CDI")

These pick-up locations accept parcels of a weight up to 30 kg, and dimensions up to 200

cm in total combined size1. To benefit from the tolerance offered by these locations, you need therefore:

- not to implement prior to the Delivery option page, filtering greater than 20 kg, - to provide the parcel weight in the appropriate call parameter (paragraph III.5.1) :

dyWeight).

1 Combined size = length + width + height


38

III.5.6.5 First order parameter You may want to filter out delivery options to pick-up locations in the case of a first order. A value "0" indicates it is not a first order, in which case the delivery option to pick-up locations are proposed. A value "1" indicates it is a first order, in which case the delivery option to pick-up locations are not proposed. Any value other than "1" is considered as being equivalent to 0, in which case the delivery option to pick-up locations are proposed.

III.5.6.6 Shipper plus parameter

This parameter enables sending specific data to the "Delivery options" page which will not be used by La Poste - Colissimo. When the Internet user completes the delivery option selection process, this parameter is returned to your "Validation" return URL. In case of error, the parameter is also returned to your "Failure" return URL. To ensure the value can be returned properly, ensure the format is observed (256 alphanumeric characters maximum).

III.5.6.7 Version number The version number parameter allows La Poste – Colissimo to identify which version of the application you are using. The version number must:

• Be sent and have the value 4.0 • Be associated with the signature calculation methods described in paragraphs III.5.9,

III.8.1.2, III.8.1.4 and III.8.2.1 If not, access to the "Delivery options" page will not be authorised. The Internet user will be redirected to your Failure return URL. An error code will be sent: the signature calculated will be incorrect. See error codes in paragraph III.6.2.

III.5.7 International

III.5.7.1 International Option This parameter allows you to specify whether you allow international delivery or otherwise. Possible values:

• 0: International delivery is not allowed. Delivery to your customer can only be in France

• 1: International delivery is allowed. Delivery to your customer can be in France or in Belgium

• 2: Only international delivery is allowed. Delivery to your customer can only be in Belgium


39

By default, if the "International option" parameter is not passed or if it is passed with a value other than those mentioned above, it will take the value "0" (delivery in France only).

III.5.7.2 Country of delivery The "country of delivery" parameter complements the "International option" parameter in order to preselect the country field in the customer's address. Depending on the value of the "International option" field, the "Country" field may or may not be changed by the customer (cf. III.5.5.3and III.5.7.1). The "Country of delivery" parameter is set to "FR" for France and "BE" for Belgium. If it is not passed or if it is passed with a value other than those mentioned above, it will take the value "FR".

III.5.7.3 Language The "Delivery options" page provides a multilingual interface via a language selector displayed at the top right of the frame.

By default it is displayed in French. The shipper can change the display language of the frame via the "addressee language" optional parameter. This will be taken into account if the end user has no language already recorded in his cookie for the "Delivery options" page. Currently, the available languages are French, English and Dutch, ("FR","EN", "NL"). Colissimo reserves the right to modify this list depending on developments to the Colissimo solution.


40

III.5.8 Encoding of the pages The "Page encoding" parameter can have two values:

• UTF-8: value to pass if you encode your merchant website and pass your settings in UTF-8

• ISO-8859-1: value by default of the parameter (where the parameter is not passed or is not recognised).

III.5.9 Signature

The signature guarantees that the data you send to the "Delivery options" page will not be modified subsequently. The signature, based on an SHA key specific to you (see paragraph II.3 Configuring the "Delivery options" Page), controls the access to the "Delivery options" page. The signature must be:

• Filled in • Transmitted in lower-case letters matching that calculated by La Poste -

Colissimo. The encoding must be performed in ISO-8859-1 or UTF-8 depending on the value entered in the call "Page encoding" parameter (see III.5.8 Encoding of the pages)

If not, access to the "Delivery options" page will not be authorised. The Internet user will be redirected to your Failure return URL. An error code will be sent, see error codes in paragraph III.6.2.

III.5.9.1 Calculation of the input signature

An SHA algorithm must be applied to a concatenation of fields: The SHA-1 algorithm (Secure Hash Algorithm) is a cryptographic hash function. It produces a 160-bit signature (40 characters). Its implementation depends on your technical environment. Java and Javascript implementation examples are provided in Annexe 2 Example of the calculation of an SHA signature in Java and Javascript. Field considered for the signature Field name Mandatory

FO identifier pudoFOId Yes

addressee last name ceName No

Order preparation time dyPreparationTime No

Forwarding charges dyForwardingCharges Yes

Pick-up Location Forwarding charges in France dyForwardingChargesCMT No

Web client no. trClientNumber No

Order no. trOrderNumber No

Transaction no. orderId Yes

Version number numVersion Yes

addressee title ceCivility No

addressee first name ceFirstName No

Company name ceCompanyName No

Floor, corridor, staircase, apartment no. ceAdress1 No


41

Entrance, building, residence ceAdress2 No

Number and street name ceAdress3 No

Named place or other particular information ceAdress4 No

Postcode ceZipCode No

Municipality ceTown No

Intercom ceEntryPhone No

Other delivery instructions ceDeliveryInformation No

Email ceEmail No

Mobile phone cePhoneNumber No

Door code ceDoorCode1 No

Door code 2 ceDoorCode2 No

Parcel weight dyWeight No

First order parameter trFirstOrder No

Shipper plus parameter trParamPlus No

Failed return URL trReturnUrlKo Yes

Validation return URL trReturnUrlOk No

Page encoding CHARSET No

Country of delivery cePays No

International Option trInter No

addressee language ceLang No

The field order must be respected. The SHA key provided by La Poste - Colissimo must also be concatenated to the end of the string. String_to_convert= pudoFOId+ceName+dyPreparationTime+dyForwardingCharges+dyForwardingChargesCMT+ trClientNumber+trOrderNumber+orderId+numVersion+ceCivility+ceFirstName+ceCompanyName+ceAdress1+ceAdress2+ceAdress3+ceAdress4+ceZipCode+ceTown+ceEntryPhone+ceDeliveryInformation+ceEmail+cePhoneNumber+ceDoorCode1+ceDoorCode2+dyWeight+trFirstOrder+trParamPlus+trReturnUrlKo+trReturnUrlOk+CHARSET+cePays+trInter+ceLang+cléSHA Signature=SHA1(String to convert) Certain of the fields above are not compulsory. If they are not transmitted by your web site, they will not be used in the calculation of the signature. Example of concatenation of the mandatory parameters only: String_to_convert= pudoFOId+dyForwardingCharges+orderId+numVersion+trReturnUrlKo+cléSHA Signature=SHA1(String to convert)

III.5.10 Return URL

III.5.10.1 "Validation" return URL

The "Validation" return URL can be sent in the call parameters of the "Delivery options" page.


42

It is an optional parameter; this possibility is offered for e-commerce platforms with several sites. If the URL is entered in the Delivery Back Office in addition to that passed in the call parameters of the Front Office page, only the one in the call parameters applies. This URL must apply the 256 alphanumeric characters maximum format, and start with http:// or https://. If not, access to the "Delivery options" page will not be authorised. The Internet user will be redirected to your Failure return URL. An error code will be sent, see error codes in paragraph III.6.2.

III.5.10.2 "Failed" return URL

To avoid losing the current order in case of service unavailability (see paragraph III.7 Unavailability and continuity of the order process), La Poste - Colissimo asks the shipper to send the "Failure" return URL in the call parameters of the "Delivery options" page using the GET method as well as transmitting it using the POST method. This URL must:

• be filled • apply the 256 alphanumeric characters maximum format, and start with http:// or

https://. • be the same as that sent using the POST method

If not, access to the "Delivery options" page will not be authorised. The Internet user will be redirected to the Failure return URL in the Back Office. An error code will be sent, see error codes in paragraph III.6.2.


43

III.5.10.3 Preliminary tests using a web browser

III.5.10.4 Introduction The return URLs must be defined and validated beforehand in the Back Office. If not, access to the "Delivery options" page will not be authorised. The Internet user will be redirected to the Failure return URL passed in parameter. An error code will be sent, see error codes in paragraph III.6.2. The pudoFOId parameter shown as an example must be filled with the contents of the FO identifier field present in your Back Office. The signature shown as an example must be calculated with the SHA key also present in the Back Office. After replacing the "hidden" parameters with valid parameters, just open this html page with a web browser to be redirected automatically to the "Delivery options" page with the transmission of these parameters. The "Delivery options" page must then be displayed.

III.5.10.5 Sending example with the mandatory parameters

Once the specified fields have been modified and filled in, the static html code below enables the "Delivery options" page to be called using only the mandatory parameters. <html> <head> <title>Appel de Livraison</title> <script type="text/javascript" src="webtoolkit.js"></script> </head> <body> <br/><br/><br/><br/><br/><br/> Livraison <form name="formpudocall" action="http://ws.colissimo.fr/pudo-fo-frame/storeCall.do? trReturnUrlKo=http://www.echec.com" method="post"> <input type="hidden" name="pudoFOId" value="05463720233029"> <input type="hidden" name="dyForwardingCharges" value="2.5"> <input type="hidden" name="orderId" value="2010217114011118">

<input type="hidden" name=" trReturnUrlKo" value="http://www.echec.com"> <input type="hidden" name="numVersion" value="4.0">

<input type="hidden" name="signature" value="de59218715162bebc8d73204ff36d65cf49d5200">

</form> <script>document.formpudocall.submit();</script> </body> </html>

As described in paragraph III.5.9.1 Calculation of the input signature, the signature is calculated from the concatenation of the following parameters: pudoFOId+dyForwardingCharges+orderId+numVersion+trReturnUrlKo+cléSHA (in this example the SHA key used is rungis) i.e. in the example below: «054637202330292054637202330292.520102171140111184.0http://www.echec.comrungis».


44

• Reminder: the signature must be in lower case and ISO-8859-1 or UTF-8 depending on the value entered in the "Page encoding" call parameter (see III.5.8 Encoding of the pages).

III.5.10.6 Example of sending all parameters Once the fields specified have been modified and filled in, the html code shown below as an example enables the "Delivery options" page to be called with all the authorised parameters. If a parameter is not sent, remove the full line (do not send this parameter with an empty value). e.g. If the client number is not sent, delete the whole line <input type="hidden" name="trClientNumber" value="CL45678"> <html> <head> <title>Appel de Livraison</title> <script type="text/javascript" src="webtoolkit.js"></script> </head> <body> <br/><br/><br/><br/><br/><br/> En attente du site Livraison <form name="formpudocall" action="http://ws.colissimo.fr/pudo-fo-frame/storeCall.do? trReturnUrlKo=http://www.echec.com" method="post">

<input type="hidden" name="pudoFOId" value="05463720233029"> <input type="hidden" name="ceName" value="Dubreuil">

<input type="hidden" name="dyPreparationTime" value="1"> <input type="hidden" name="dyForwardingCharges" value="2.5"> <input type="hidden" name="dyForwardingChargesCMT" value="2"> <input type="hidden" name="trClientNumber" value="CL45678">

<input type="hidden" name="trOrderNumber" value="CMD78954"> <input type="hidden" name="orderId" value="2010217114011118"> <input type="hidden" name="numVersion" value="4.0"> <input type="hidden" name="ceCivility" value="MR">

<input type="hidden" name="ceFirstName" value="Pierre"> <input type="hidden" name="ceCompanyName" value="AGFR International"> <input type="hidden" name="ceAdress1" value="Escalier B"> <input type="hidden" name="ceAdress2" value="Porte C"> <input type="hidden" name="ceAdress3" value="16, boulevard de reuilly"> <input type="hidden" name="ceAdress4" value="12 ème arrondissement"> <input type="hidden" name="ceZipCode" value="75012"> <input type="hidden" name="ceTown" value="Paris">

<input type="hidden" name="cePays" value="FR"> <input type="hidden" name="ceEntryPhone" value="256A">

<input type="hidden" name="ceDeliveryInformation" value="Chien méchant"> <input type="hidden" name="ceEmail" value="[email protected]">

<input type="hidden" name="cePhoneNumber" value="0124548278"> <input type="hidden" name="ceDoorCode1" value="123456">

<input type="hidden" name="ceDoorCode2" value="ABCDEF"> <input type="hidden" name="dyWeight" value="150"> <input type="hidden" name="trFirstOrder" value="1"> <input type="hidden" name="trParamPlus" value="ABC12EF"> <input type="hidden" name="trReturnUrlOk" value=”http://www.succes.com”>

<input type="hidden" name="trReturnUrlKo" value=”http://www.echec.com”> <input type="hidden" name="CHARSET" value="UTF-8"> <input type="hidden" name="trInter" value="1"> <input type="hidden" name="ceLang" value="FR"> <input type="hidden" name="signature" value=" 8d3cf8988ab2b3d404e9ee732ff920bfd8bfcb99">


45

</form> <script>document.formpudocall.submit();</script> </body>

</html>

As described in paragraph III.5.9.1 Calculation of the input signature, the signature is calculated from the concatenation of the following parameters: pudoFOId+ceName+dyPreparationTime+dyForwardingCharges+dyForwardingChargesCMT+ trClientNumber+trOrderNumber+orderId+numVersion+ceCivility+ceFirstName+ceCompanyName+ceAdress1+ceAdress2+ceAdress3+ceAdress4+ceZipCode+ceTown+ceEntryPhone+ceDeliveryInformation+ceEmail+cePhoneNumber+ceDoorCode1+ceDoorCode2+dyWeight+trFirstOrder+trParamPlus+trReturnUrlKo+trReturnUrlOk+CHARSET+cePays+trInter+ceLang+cléSHA i.e. in the example below: 05463720233865Dubreuil12.52CL45678CMD7895420102171140111184.0MRPierreAGFR I n t e r n a t i o n a l E s c a l i e r B P o r t e C 1 6 , b o u l e v a r d d e r e u i l l y 1 2 è m e a r r o n d i s s e m e n t 7 5 0 1 2 P a r i s 2 5 6 A C h i e n méchantserge.avatar@avatar.fr0124548278123456ABCDEF15011ABC12EFhttp://www.echec. c o m h t t p : / / w w w . s u c c e s . c o m F R 1 F R r u n g i s Followed by the SHA key supplied by La Poste - Colissimo (in this example the SHA key used (cléSHA) is Rungis).

• Reminder: the signature must be in lower case and ISO-8859-1 or UTF-8 depending on the value entered in the "Page encoding" call parameter (see III.5.8 Encoding of the pages).


46

III.6 "Error management"

III.6.1 Error messages displayed in the "Delivery options" page

Error code Description Check/Action Type

MSG.101 The $1, $2, $3, $4, $5, $6 field(s) is(are) mandatory(s), please fill them in.

Displayed on validation of step 1 if the following fields are not filled in: $1 corresponds to the wording of the Title field $2 corresponds to the wording of the Last name field $3 corresponds to the wording of the First name field $4 corresponds to the wording of the Postcode field $5 corresponds to the wording of the City field $6 corresponds to the wording of the Email field

Blocking

MSG.102 You have entered an unauthorised character: ;€~#{([|\^)]=}$¤£%µ*§!°²in the $1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11 field(s).

Displayed on validation of step 1 if the following fields contain an unauthorised character: $1 corresponds to the wording of the Last name field $2 corresponds to the wording of the First name field $3 corresponds to the wording of the Company name field $4 corresponds to the wording of the Floor, corridor, staircase, apartment no field. $5 corresponds to the wording of the Entrance, building, block, residence field $6 corresponds to the wording of the Number and wording of the road field $7 corresponds to the wording of the Named place or other particular information field $8 corresponds to the wording of the Other instructions to facilitate delivery of the parcel field $9 corresponds to the wording of the Email field $10 corresponds to the wording of the Mobile number field $11 corresponds to the wording of the City field

Blocking

MSG.103 The format of $1, $2 is not valid.

Displayed on validation of step 1 if the format of the following fields is incorrect: $1 corresponds to the wording of the email field

Blocking


47

$2 corresponds to the wording of the postcode field Email: The format expected is [email protected] with z containing at least 2 characters Postcode: The expected format is 01XXX to 95XXX, ADXXX and 980XX with X equal to a digit.

MSG.202 The phone number format is not valid: it must only contain numeric characters and begin with 06 or 07.

Displayed on validation of step 2 – delivery options if the format of the phone number entered is incorrect for a delivery in France. Mobile phone: The expected format is 10 numeric characters starting with 06XXXXXXXX or 07XXXXXXXX

Blocking

MSG.203 You have entered an unauthorised character: ;€~#{([|\^)]=}$¤£%µ*§!°² in the "Additional information" field, please replace it so that the information you have entered can be used.

Displayed on validation of step 2 –delivery options if the Additional information field contains an unauthorised character.

Blocking

MSG.204 The phone number format is not valid: it must only begin with +324.

Displayed on validation of step 2 – delivery options if the format of the phone number entered is incorrect for Belgium

Blocking

MSG.205 The phone number entered is not accepted.

Displayed on validation of step 2 - delivery options if the format of the phone number entered is incorrect.

Mobile phone: The last 8 digits cannot be identical or be a 12345678 series.

Blocking

MSG.300 The $1, $2 field is mandatory, please enter it.

Displayed on seeking step 2 – pick-up locations if the following fields are not filled in: $1 Postcode $2 Municipality

Blocking

MSG.301 The Postcode format is not valid. Displayed on seeking step 2 – pick-up locations if the postcode field is not valid.

Postcode: The expected format is 01XXX to 95XXX, ADXXX and 980XX with X equal to a digit.

Blocking

MSG.302 You have entered an unauthorised character: ;€~#{([|\^)]=}$¤£%µ*§!°² in the Address field.

Displayed on seeking step 2 – pick-up locations if the Address field contains an unauthorised character.

Blocking

MSG.303 Please choose a delivery option to validate.

Displayed on validation of step 2 – pick-up locations if no pick-up location has been selected.

Blocking


48

MSG.400 Delivery to a pick-up location in Belgium at the price of $1 with: $1 = forwarding charges + Surcharge for delivery in Belgium configured through the back office

Displayed in area 5 of step 2 – Delivery options if delivery in Belgium is allowed, and if the total forwarding charges to Belgium are > €0

Information

MSG.401 Free delivery to a pick-up location in Belgium

Displayed in step 2 - Delivery options if delivery in Belgium is allowed, and if the forwarding charges to Belgium are zero

Information

III.6.2 Error codes returned to the shipper on the Failure return URL

Error code Description Check/Action Type

001 Missing FO identifier The FO identifier is not sent in the call parameters. Blocking

002

FO identifier incorrect The FO identifier sent in the call parameters: is unknown to the application or non-compliant size. or could not be identified by the Delivery solution (technical error: Back Office unavailable)

Blocking

003

Client not authorised The FO identifier sent in the call parameters: corresponds to an account terminated by La Poste - Colissimo or could not be identified by the Delivery solution (technical error: authentication unavailable)

Blocking

004

Mandatory field missing A mandatory parameter is missing in the call parameters:

- Forwarding charges - Transaction no. - Failure return URL

Blocking

005a Incorrect format of the language The ceLang (this language) parameter contains

more than 2 characters Non-blocking

006 Signature missing The signature is not sent in the call parameters. Blocking

007

Invalid signature or version number

The signature sent in the call parameters is not valid.

The transaction number sent in the call parameters is not valid.

Blocking

008 Invalid postcode The postcode sent in the call parameters is not valid.

Blocking

009 Format of the Validation return URL incorrect

The URL sent in the call parameters is not valid. Blocking

010 Format of the Failure return URL incorrect

The Failure return URL sent in the call parameters is not valid.

Blocking

011 Invalid transaction number The transaction number sent in the call parameters is not valid.

Blocking

012 Format of forwarding charges incorrect

The forwarding charges sent in the call parameters are not valid.

Blocking

015 Application server unavailable The La Poste - Colissimo application server is unavailable.

Blocking


49

016 DBMS unavailable Data retrieval is unavailable Blocking

020 International Option and incompatible Countries

The value of the "International option" parameter does not allow the value of the "Country of delivery" parameter

Non-blocking

III.6.3 Information codes returned to the shipper on the Validation return URL

Information

code Description Check/Action Type

501 Email field too long, field truncated

The call parameter corresponding to the email is too long.

The value concerned is also returned.

Non-blocking

502 Mobile phone field too long, field truncated

The call parameter corresponding to the mobile phone is too long.


Non-blocking

503 Name field too long, field truncated

The call parameter corresponding to the name is too long.


Non-blocking

504 First name field too long, field truncated

The call parameter corresponding to the first name is too long.


Non-blocking

505 Company Name field too long, field truncated

The call parameter corresponding to the Company Name is too long.


Non-blocking

506 Floor… too long, field truncated

The call parameter corresponding to the Floor… is too long.


Non-blocking

507 Entrance… too long, field truncated

The call parameter corresponding to the Entrance… is too long.


Non-blocking

508 Named place field too long, field truncated

The call parameter corresponding to the Named place … is too long.


Non-blocking

509 Number and street field too long, field truncated

The call parameter corresponding to the Number and street is too long.


Non-blocking

510 Town field too long, field truncated

The call parameter corresponding to the town is too long.


Non-blocking

511 Intercom field too long, field truncated

The call parameter corresponding to the intercomis too long.


Non-blocking

512 Additional information field too The call parameter corresponding to additional Non-


50

long, field truncated information is too long.


blocking

513 Door code field too long, field truncated

The call parameter corresponding to the Door code is too long.


Non-blocking

514 Door code 2 field too long, field truncated

The call parameter corresponding to the Door code 2 is too long.


Non-blocking

515 Client number field too long, field truncated

The call parameter corresponding to the Client number is too long.


Non-blocking

516 Order number field too long, field truncated

The call parameter corresponding to the Order number is too long.


Non-blocking

517 ParamPlus field too long, field truncated

The call parameter corresponding to ParamPlus is too long.


Non-blocking

131 Civility invalid, field ignored

The civility format is incorrect Non-blocking

132 The order preparation time field is not valid, field ignored

The Order preparation time is not a valid numeric, too long or equals 0.

Non-blocking

133 The weight field is not valid, field ignored

The Order weight is not a valid numeric, too long or equals 0.

Non-blocking

134 Value of the encoding field not recognised, replaced by ISO-8859-1

The value of the encoding parameter corresponds neither to "ISO-8859-1" nor to "UTF-8"

Non-blocking

III.7 Unavailability and continuity of the order process

III.7.1 DBMS down If the La Poste - Colissimo DBMS is down, the Internet user is redirected to the Failure return URL sent in the call parameters. The blocking error code 002 is sent. If the Failure return URL is not sent in the call parameters, then an error page is displayed for the Internet user. See paragraph III.7.5.

III.7.2 Application server down If the La Poste - Colissimo application server is down, the Internet user is redirected to the Failure return URL sent in the call parameters. The blocking error code 015 is sent. If the Failure return URL is not sent in the call parameters, then an error page is displayed for the Internet user. See paragraph III.7.5.

III.7.3 IT system down


51

If the La Poste - Colissimo IT system is down, an error page is displayed for the Internet user. See paragraph III.7.5.

III.7.4 Order process continuity In addition to the supervision mechanisms of the application and hardware infrastructures which do not guarantee by themselves the availability of the entire processing chain, La Poste - Colissimo recommends shippers to implement a check prior to calling the "Delivery options" page. To do this, La Poste - Colissimo provides shippers with a supervision URL allowing checking whether the "Delivery options" page is available or not. Implementing this check eliminates the risk of losing a sale by allowing the Internet user to finalise his order. In this case, the shipper must implement a process without the So "delivery options" page, leading to the proposition of a home delivery for the Internet user. The supervision URL supplied by La Poste - Colissimo is: http://ws.colissimo.fr/supervision-pudo-frame/supervision.jsp This page displays [OK] if the IT system, the application server and the DBMS are operational. It displays [KO] otherwise.

To validate service availability, call the supervision page, and then search for the [OK] character string in this page.

III.7.5 Internal error page In case of technical error preventing to display the "Delivery options" page or send information to the shipper, the following static page is displayed to the Internet user.


52

III.8 Parameters for return to your web site

III.8.1 Returns to Validation return URL

Once the delivery option is selected by the Internet user, the parameters are sent using POST. Note: If your validation/failure URLs contain variables themselves, these will be also returned, regardless of the chosen delivery option. This transmission will be via the POST method.

III.8.1.1 Return for Home delivery options

Parameter Mandatory Parameter name Type Comment

FO identifier Yes PUDOFOID 14 numeric Identical to the call parameter

addressee last name Yes CENAME Up to 34 alphanumeric As displayed on the "Delivery options" page

Order preparation time Yes DYPREPARATIONTIME Up to 2 alphanumeric As present in call parameters

Total forwarding charges Yes DYFORWARDINGCHARGES Up to 6 alphanumeric with as a separator ". "

Corresponds to the total amount of shipping charges, calculated according to the rules described in III.5.6.2

Web client no. TRCLIENTNUMBER Up to 30 alphanumeric As present in call parameters

Order no. TRORDERNUMBER Up to 30 alphanumeric As present in call parameters

Transaction no. Yes ORDERID 5 to 16 alphanumeric As present in call parameters

addressee title Yes CECIVILITY MR/MME(MRS) As displayed on the "Delivery options" page

addressee first name Yes CEFIRSTNAME Up to 29 alphanumeric As displayed on the "Delivery options" page

addressee company name Yes (if company address)

CECOMPANYNAME Up to 38 alphanumeric As displayed on the "Delivery options" page

addressee floor, corridor, staircase, apartment no.

Yes (if not a company address)

CEADRESS1 Up to 38 alphanumeric As displayed on the "Delivery options" page

addressee entrance, construction, building, residence


addressee number and street name

Yes CEADRESS3 Up to 38 alphanumeric As displayed on the "Delivery options" page


53

Addressee named place or other particular information


addressee's postcode Yes CEZIPCODE 5 alphanumeric As displayed on the "Delivery options" page

addressee's city Yes CETOWN Up to 32 alphanumeric As displayed on the "Delivery options" page

Selected delivery option Yes DELIVERYMODE 3 alphanumeric DOM for home

Other delivery instructions CEDELIVERYINFORMATION Up to 70 alphanumeric As displayed on the "Delivery options" page

addressee's email Yes CEEMAIL Up to 80 alphanumeric As displayed on the "Delivery options" page

addressee mobile phone number

No CEPHONENUMBER Up to 12 alphanumeric As displayed on the "Delivery options" page

Door code CEDOORCODE1 Up to 8 alphanumeric As displayed on the "Delivery options" page

Door code 2 CEDOORCODE2 Up to 8 alphanumeric As displayed on the "Delivery options" page

Intercom CEENTRYPHONE Up to 30 alphanumeric As displayed on the "Delivery options" page

Shipper plus parameter TRPARAMPLUS Up to 256 alphanumeric As present in call parameters

Commercial name Yes TRADERCOMPANYNAME Up to 35 alphanumeric As entered in your Delivery Back Office

Error code ERRORCODE Up to 80 alphanumeric Combination of codes in the form xxx xxx … xxx with xxx worth 501 to 517 and/or 131 to 134.

The codes are separated by spaces. For example: 501 508 132

Failure return URL Yes TRRETURNURLKO Up to 256 alphanumeric Sent using POST

Page encoding CHARSET Up to 10 alphanumeric According to the input parameter received

addressee's country CEPAYS 2 alphanumeric By default, is set to "FR"

Signature Yes SIGNATURE 40 alphanumeric Recalculated from the new values of the parameters, see paragraph


54

III.8.1.2

Champs en erreur

Error on addressee name If error code 503 and the field is concerned by the error

ERR_CENAME Up to 34 alphanumeric

Error on addressee first name If error code 504 and the field is concerned by the error

ERR_CEFIRSTNAME Up to 29 alphanumeric

Error on addressee company name

If error code 505 and the field is concerned by the error

ERR_CECOMPANYNAME Up to 38 alphanumeric

Error on addressee floor, corridor, staircase, apartment no.


ERR_CEADRESS1 Up to 38 alphanumeric

Error on addressee entrance, construction, building, residence



Error on addressee number and street name



Error on addressee named If error code ERR_CEADRESS4 Up to 38 alphanumeric


55

place or other particular information

509 and the field is concerned by the error

Error on addressee town If error code 510 and the field is concerned by the error

ERR_CETOWN Up to 32 alphanumeric

Error on door code If error code 513 and the field is concerned by the error

ERR_CEDOORCODE1 Up to 8 alphanumeric

Error on door code 2 If error code 514 and the field is concerned by the error


Error on Intercom If error code 511 and field concerned by error

ERR_CEENTRYPHONE Up to 30 alphanumeric

Error on Other delivery instructions


ERR_CEDELIVERYINFORMATION

Up to 70 alphanumeric

Error on addressee email If error code 501 and the field is concerned by the error

ERR_CEEMAIL Up to 80 alphanumeric


56

Error on addressee mobile phone


ERR_CEPHONENUMBER Up to 12 alphanumeric

Error on web client no. If error code 515 and the field is concerned by the error

ERR_TRCLIENTNUMBER Up to 30 alphanumeric

Error on order no. If error code 516 and the field is concerned by the error

ERR_TRORDERNUMBER Up to 30 alphanumeric

Error on shipper Parameter plus


ERR_TRPARAMPLUS Up to 256 alphanumeric

Error on addressee civility If error code 131 and the field is concerned by the error

ERR_CECIVILITY Up to 3 alphanumeric

Error on parcel weight If error code 133 and the field is concerned by the error

ERR_DYWEIGHT. Up to 5 alphanumeric

Error on order preparation time

If error code 132 and the field is

ERR_DYPREPARATIONTIME Up to 2 alphanumeric


57

concerned by the error

Page encoding error If error code 134 returned

ERR_ CHARSET Up to 10 alphanumeric

Must be set to "ISO-8859-1" or "UTF-8"


58

III.8.1.2 Output signature for the home delivery options The signature guarantees that the data the "Delivery options" page sends to you will not be modified subsequently. The signature, based on an SHA key specific to you allows a check to be made on the information received. The signature must be compared to that calculated by Colissimo, in lower-case and encoded according to the configuration sent on input (by default, ISO 8859-1): these two signatures must be identical. If this is not the case, the data must be considered as having been changed and the shipper must implement a bypass process to offer delivery to its buyer. Calculation: An SHA algorithm must be applied to a concatenation of fields: The SHA-1 algorithm (Secure Hash Algorithm) is a cryptographic hash function. It produces a 160-bit signature (40 characters). Its implementation depends on your technical environment. Java and Javascript implementation examples are provided in Annexe 2 Example of the calculation of an SHA signature in Java and Javascript. Field used for the signature for Home delivery options

Field name Mandatory

FO identifier PUDOFOID Yes

addressee last name CENAME Yes

Order preparation time DYPREPARATIONTIME Yes

Total forwarding charges DYFORWARDINGCHARGES Yes

Web client no. TRCLIENTNUMBER

Order no. TRORDERNUMBER

Transaction no. ORDERID Yes

addressee title CECIVILITY Yes

addressee first name CEFIRSTNAME Yes

addressee company name CECOMPANYNAME Yes (if company address)

addressee floor, corridor, staircase, apartment no.

CEADRESS1

addressee entrance, construction, building, residence

CEADRESS2

addressee number and street name CEADRESS3 Yes

Addressee named place or other particular information

CEADRESS4

addressee's postcode CEZIPCODE Yes

addressee's city CETOWN Yes

Selected delivery option DELIVERYMODE Yes

Other delivery instructions CEDELIVERYINFORMATION

addressee's email CEEMAIL Yes

addressee mobile phone number CEPHONENUMBER

Door code CEDOORCODE1


59

Door code 2 CEDOORCODE2

Intercom CEENTRYPHONE

Shipper plus parameter TRPARAMPLUS

Commercial name TRADERCOMPANYNAME Yes

Error code ERRORCODE

Error on addressee name ERR_CENAME If error code 503

Error on addressee first name ERR_CEFIRSTNAME If error code 504 Error on addressee company name ERR_CECOMPANYNAME If error code 505 Error on addressee floor, corridor, staircase, apartment no.

ERR_CEADRESS1 If error code 506



Error on addressee number and street name ERR_CEADRESS3 If error code 508 Error on addressee named place or other particular information


Error on addressee town ERR_CETOWN If error code 510 Error on door code ERR_CEDOORCODE1 If error code 513 Error on door code 2 ERR_CEDOORCODE2 If error code 514 Error on Intercom ERR_CEENTRYPHONE If error code 511 Error on Other delivery instructions ERR_CEDELIVERYINFORMATION If error code 512 Error on addressee email ERR_CEEMAIL If error code 501 Error on addressee mobile phone ERR_CEPHONENUMBER If error code 502 Error on web client no. ERR_TRCLIENTNUMBER If error code 515 Error on order no. ERR_TRORDERNUMBER If error code 516 Error on shipper Parameter plus ERR_TRPARAMPLUS If error code 517 Error on addressee civility ERR_CECIVILITY If error code 131 Error on parcel weight ERR_DYWEIGHT. If error code 133 Error on order preparation time ERR_DYPREPARATIONTIME If error code 132 Failure return URL TRRETURNURLKO Yes

Page encoding CHARSET

addressee's country CEPAYS

Page encoding error ERR_CHARSET If error code 134

The field order must be respected. The SHA key provided by La Poste - Colissimo must also be concatenated to the end of the string. String_to_convert=PUDOFOID+CENAME+DYPREPARATIONTIME+DYFORWARDINGCHARGES+TRCLIENTNUMBER+TRORDERNUMBER+ORDERID+CECIVILITY+CEFIRSTNAME+CECOMPANYNAME+CEADRESS1+CEADRESS2+CEADRESS3+CEADRESS4+CEZIPCODE+CETOWN+DELIVERYMODE+CEDELIVERYINFORMATION+CEEMAIL+CEPHONENUMBER+CEDOORCODE1+CEDOORCODE2+CEENTRYPHONE+TRPARAMPLUS+TRADERCOMPANYNAME+ERRORCODE+ERR_CENAME+ERR_CEFIRSTNAME+ERR_CECOMPANYNAME+ERR_CEADRESS1+ERR_CEADRESS2+ERR_CEADRESS3+ERR_CEADRESS4+ERR_CETOWN+ERR_CEDOORCODE1+ERR_CEDOORCODE2+ERR_CEENTRYPHONE+ERR_CEDELIVERYINFORMATION+ERR_CEEMAIL+ERR_CEPHONENUMBER+ERR_TRCLIENTNUMBER+ERR_TRORDERNUMBER+ERR_TRPARAMPLUS+ERR_CECIVILITY+ERR_DYWEIGHT+ERR_DYPREPARATIONTIME+TRRETURNURLKO+CHARSET +CEPAYS+ERR_CHARSET+cléSHA Signature=SHA1(String to convert)


60

Certain of the fields above are not compulsory. If they are not sent by the "Delivery options" page, they must not be considered in calculating the signature. Example of concatenation of the mandatory parameters only: String_to_convert=PUDOFOID+CENAME+DYPREPARATIONTIME+DYFORWARDINGCHARGES+ORDERID+CECIVILITY+CEFIRSTNAME+CEADRESS3+CEZIPCODE+CETOWN+DELIVERYMODE+CEEMAIL+ TRADERCOMPANYNAME+TRRETURNURLKO+cléSHA Signature=SHA1(String to convert)


61

III.8.1.3 Return for the delivery options in pick-up locations


FO identifier Oui PUDOFOID 14 numeric Identical to the call parameter

addressee last name Oui CENAME Up to 34 alphanumeric As displayed on the "Delivery options" page

Order preparation time Oui DYPREPARATIONTIME Up to 2 alphanumeric As present in call parameters

Total forwarding charges Oui DYFORWARDINGCHARGES Up to 6 alphanumeric with as a separator ". "

Matches the input forwarding charges

Web client no. TRCLIENTNUMBER Up to 30 alphanumeric As present in call parameters

Order no. TRORDERNUMBER Up to 30 alphanumeric As present in call parameters

Transaction no. Oui ORDERID 5 to 16 alphanumeric As present in call parameters

addressee title Oui CECIVILITY MR/MME(MRS) As displayed on the "Delivery options" page

addressee first name Oui CEFIRSTNAME Up to 29 alphanumeric As displayed on the "Delivery options" page

addressee company name Oui (si adresse Professionnelle)

CECOMPANYNAME Up to 38 alphanumeric As displayed on the "Delivery options" page

Selected delivery option Oui DELIVERYMODE 3 alphanumeric BPR for French post office A2P for Pick-up locations / Pick-up stations in France ACP for Colissimo parcel agency CDI for a mail distribution centre BDP for Belgian post office CMT for Belgian Pick Up locations

Pick-up location identifier Oui PRID 6 numeric Unique identifier of the point to import into your labelling solution

Name of pick-up location Oui PRNAME Up to 50 alphanumeric

Address complement of pick-up location

PRCOMPLADRESS Up to 38 alphanumeric

Number and street name of the pick-up location

Oui PRADRESS1 Up to 38 alphanumeric

Named place of the pick-up location

PRADRESS2 Up to 38 alphanumeric


62

Postcode of pick-up location Oui PRZIPCODE 5 alphanumeric

pick-up location town Oui PRTOWN Up to 32 alphanumeric

Routing batch LOTACHEMINEMENT Up to 10 alphanumeric Present for the A2P and MRL locations only See paragraph III.8.1.5 Routing information

Distribution sort DISTRIBUTIONSORT Up to 10 alphanumeric

Sort plan version VERSIONPLANTRI Up to 2 alphanumeric

addressee's email Oui CEEMAIL Up to 80 alphanumeric As displayed on the "Delivery options" page

addressee mobile phone number

Oui CEPHONENUMBER Up to 12 alphanumeric As displayed on the "Delivery options" page

Shipper plus parameter TRPARAMPLUS Up to 256 alphanumeric As present in call parameters

Commercial name Oui TRADERCOMPANYNAME Up to 35 alphanumeric As entered in your Delivery Back Office

Error code ERRORCODE Up to 80 alphanumeric Combination of codes in the form xxx xxx … xxx with xxx worth 501 to 517 and/or 131 to 134.

The codes are separated by spaces. For example: 501 508 132

Failure return URL Oui TRRETURNURLKO Up to 256 alphanumeric Sent using POST

Page encoding CHARSET Up to 10 alphanumeric By default, is set to "ISO-8859-1"

addressee's country CEPAYS 2 alphanumeric By default, is set to "FR"

Pick-up location country PRPAYS 2 alphanumeric

Network code CODERESEAU 3 alphanumeric Sent only if a Belgian pick-up location is chosen for delivery

Signature Oui SIGNATURE 40 alphanumeric Recalculated from the new values of the parameters, see paragraph

III.8.1.4 Output signature for pick-up location delivery

Champs en erreur

Error on addressee name If error code ERR_CENAME Up to 34 alphanumeric


63

503 and the field is concerned by the error

Error on addressee first name If error code 504 and the field is concerned by the error

ERR_CEFIRSTNAME Up to 29 alphanumeric

Error on addressee company name


ERR_CECOMPANYNAME Up to 38 alphanumeric

Error on addressee floor, corridor, staircase, apartment no.






Error on addressee number and street name



Error on addressee named place or other particular information




64


Error on addressee town If error code 510 and the field is concerned by the error

ERR_CETOWN Up to 32 alphanumeric

Error on door code If error code 513 and the field is concerned by the error


Error on door code 2 If error code 514 and the field is concerned by the error


Error on Intercom If error code 511 and field concerned by error

ERR_CEENTRYPHONE Up to 30 alphanumeric

Error on Other delivery instructions


ERR_CEDELIVERYINFORMATION


Error on addressee email If error code 501 and the field is concerned by the error

ERR_CEEMAIL Up to 80 alphanumeric

Error on addressee mobile If error code ERR_CEPHONENUMBER Up to 10 alphanumeric


65

phone 502 and the field is concerned by the error

Error on web client no. If error code 515 and the field is concerned by the error

ERR_TRCLIENTNUMBER Up to 30 alphanumeric

Error on order no. If error code 516 and the field is concerned by the error

ERR_TRORDERNUMBER Up to 30 alphanumeric

Error on shipper Parameter plus


ERR_TRPARAMPLUS Up to 256 alphanumeric

Error on addressee civility If error code 131 and the field is concerned by the error

ERR_CECIVILITY Up to 3 alphanumeric

Error on parcel weight If error code 133 and the field is concerned by the error

ERR_DYWEIGHT. Up to 5 alphanumeric

Error on order preparation time


ERR_DYPREPARATIONTIME Up to 2 alphanumeric


66


Page encoding error If error code 134 returned

ERR_ CHARSET Up to 10 alphanumeric

Must be set to "ISO-8859-1" or "UTF-8"


67

III.8.1.4 Output signature for pick-up location delivery options

The signature guarantees that the data the "Delivery options" page sends to you will not be modified subsequently. The signature, based on an SHA key specific to you allows a check to be made on the information received. The signature must be compared to that calculated by Colissimo, in lower-case and encoded according to the configuration sent on input (by default, ISO 8859-1): these two signatures must be identical. If this is not the case, the data must be considered as having been changed and the shipper must implement a bypass process to offer delivery to its buyer. Calculation: An SHA algorithm must be applied to a concatenation of fields: The SHA-1 algorithm (Secure Hash Algorithm) is a cryptographic hash function. It produces a 160-bit signature (40 characters). Its implementation depends on your technical environment. Java and Javascript implementation examples are provided in Annexe 2 Example of the calculation of an SHA signature in Java and Javascript.

Field used for the signature for the pick-up location delivery options

Field name Mandatory

FO identifier PUDOFOID Yes

addressee last name CENAME Yes

Order preparation time DYPREPARATIONTIME Yes

Total forwarding charges DYFORWARDINGCHARGES Yes



Transaction no. ORDERID Yes

addressee title CECIVILITY Yes

addressee first name CEFIRSTNAME Yes

addressee company name CECOMPANYNAME Yes (if company address)

Selected delivery option DELIVERYMODE Yes

Pick-up location identifier PRID Yes

Name of pick-up location PRNAME Yes

Additional pick-up location address details PRCOMPLADRESS

Number and street name of the pick-up location

PRADRESS1 Yes

Named place of the pick-up location PRADRESS2

Postcode of pick-up location PRZIPCODE Yes

Pick-up location municipality PRTOWN Yes

Routing batch LOTACHEMINEMENT

Distribution sort DISTRIBUTIONSORT

Sort plan version VERSIONPLANTRI

addressee's email CEEMAIL Yes

addressee mobile phone number CEPHONENUMBER Yes


68


Commercial name TRADERCOMPANYNAME Yes

Error code ERRORCODE

Error on addressee name ERR_CENAME If error code 503

Error on addressee first name ERR_CEFIRSTNAME If error code 504 Error on addressee company name ERR_CECOMPANYNAME If error code 505 Error on addressee floor, corridor, staircase, apartment no.




Error on addressee number and street name ERR_CEADRESS3 If error code 508 Error on addressee named place or other particular information


Error on addressee town ERR_CETOWN If error code 510 Error on door code ERR_CEDOORCODE1 If error code 513 Error on door code 2 ERR_CEDOORCODE2 If error code 514 Error on Intercom ERR_CEENTRYPHONE If error code 511 Error on Other delivery instructions ERR_CEDELIVERYINFORMATION If error code 512 Error on addressee email ERR_CEEMAIL If error code 501 Error on addressee mobile phone ERR_CEPHONENUMBER If error code 502 Error on web client no. ERR_TRCLIENTNUMBER If error code 515 Error on order no. ERR_TRORDERNUMBER If error code 516 Error on shipper Parameter plus ERR_TRPARAMPLUS If error code 517 Error on addressee civility ERR_CECIVILITY If error code 131 Error on parcel weight ERR_DYWEIGHT. If error code 133 Error on order preparation time ERR_DYPREPARATIONTIME If error code 132 Failure return URL TRRETURNURLKO Yes



Pick-up location country PRPAYS

Network code CODERESEAU Sent only if a Belgian pick-up location is chosen for delivery

Page encoding error ERR_CHARSET If error code 134

The field order must be respected. The SHA key provided by La Poste - Colissimo must also be concatenated to the end of the string. String_to_convert=PUDOFOID+CENAME+DYPREPARATIONTIME+DYFORWARDINGCHARGES+TRCLIENTNUMBER+TRORDERNUMBER+ORDERID+CECIVILITY+CEFIRSTNAME+CECOMPANYNAME+DELIVERYMODE+PRID+PRNAME+PRCOMPLADRESS+PRADRESS1+PRADRESS2+PRZIPCODE+PRTOWN+LOTACHEMINEMENT+DISTRIBUTIONSORT+VERSIONPLANTRI+CEEMAIL+CEPHONENUMBER+TRPARAMPLUS+TRADERCOMPANYNAME+ERRORCODE+ERR_CENAME+ERR_CEFIRSTNAME+ERR_CECOMPANYNAME+ERR_CEADRESS1+ERR_CEADRESS2+ERR_CEADRESS3+ERR_CEADRESS4+ERR_CETOWN+ERR_CEDOORCODE1+ERR_CEDOORCODE2+ERR_CEENTRYPHONE+ERR_CEDELIVERYINFORMATION+ERR_CEEMAIL+ERR_CEPHONENUMBER+ERR_TRCLIENTNUMBER+ERR_TRORDERNUMBER+ERR_TRPARAMPLUS+ERR_CECIVILITY+ERR_DYWEIGHT+ERR_DYPREPARATIONTIME+TRRETURNURLKO+CHARSET+CEPAYS+PRPAYS +CODERESEAU +ERR_CHARSET +cléSHA


69

Signature=SHA1(String to convert)

Certain of the fields above are not compulsory. If they are not sent by the "Delivery options" page, they must not be considered in calculating the signature. Example of concatenation of the mandatory parameters only: String_to_convert=PUDOFOID+CENAME+DYPREPARATIONTIME+DYFORWARDINGCHARGES+ORDERID+CECIVILITY+CEFIRSTNAME+DELIVERYMODE+PRID+PRNAME+PRADRESS1+PRZIPCODE+PRTOWN+CEEMAIL+CEPHONENUMBER+TRADERCOMPANYNAME+TRRETURNURLKO+cléSHA Signature=SHA1(String to convert)

III.8.1.5 Routing information For shipments in France, the Routing batch, Sort distribution and Sort plan version fields are required for customers using a specific LIBERTE labelling solution. Customers using a SIMPLICITE or FLEXIBILITE labelling solution (Inet, Labelling WS) should ignore this information. Customers using a specific LIBERTE labelling solution, should refer to the documents below for the use of these data: 2_LIBERTE_Specifications - Colissimo Labels 2_LIBERTE_EDI technical specifications

III.8.1.6 Network code For international shipments, the Network code field is necessary to generate labels by your SIMPLICITE, FLEXIBILITE or LIBERTE (Inet, WS labelling) labelling solution.


70

III.8.2 Returns to Failure return URL

If the Internet user has been unable to access the "Delivery options" page, the following parameters are sent using POST.


FO identifier PUDOFOID 14 numeric Identical to the call parameter

addressee last name CENAME Up to 34 alphanumeric

As present in call parameters

Order preparation time DYPREPARATIONTIME Up to 2 numeric As present in call parameters

Forwarding charges DYFORWARDINGCHARGES

1 to 5 alphanumeric As present in call parameters

Shipping costs Pick-up Location

DYFORWARDINGCHARGESCMT

1 to 5 alphanumeric As present in call parameters

Web client no. TRCLIENTNUMBER Up to 30 alphanumeric


Order no. TRORDERNUMBER Up to 30 alphanumeric


Transaction no. ORDERID 5 to 16 alphanumeric As present in call parameters

Shipper plus parameter TRPARAMPLUS Up to 256 alphanumeric


Signature Yes SIGNATURE 40 alphanumeric

Error code Yes ERRORCODE 3 numeric 1 error code only per failure return

Failure return URL Yes TRRETURNURLKO Up to 256 alphanumeric

Sent using POST

Page encoding CHARSET Set to: ISO-8859-1 or UTF-8

addressee's country CEPAYS 2 alphanumeric characters (country code according to ISO 3166)

Possible values: FR or BE

International Option TRINTER 1 numeric character (0;1;2)

addressee language CELANG 2 alphanumeric characters (according


71

to ISO 639-1 Alpha2 standard)

May be set to "NL", "EN" or "FR" (by default)


72

Error fields

FO Identifier error Yes if error code 001, 002 or 003

ERR_PUDOFOID Up to 14 alphanumeric

Signature error Yes if error code 006 or 007

ERR_SIGNATURE Up to 40 alphanumeric

Forwarding charges error Yes, if error code 004 or 012 and concerned by error

ERR_DYFORWARDINGCHARGES


Forwarding charges error to Pick-up Locations in France

Yes, if error code 012 and concerned by error the error

ERR_DYFORWARDINGCHARGESCMT


Transaction number error Yes, if error code 011 or 004 and concerned by error

ERR_ORDERID Up to 30 alphanumeric

Addressee postcode error Yes if error code 008

ERR_CEZIPCODE Up to 5 alphanumeric

Validation return URL error

Yes if error code 009

ERR_TRRETURNURLOK Up to 256 alphanumeric

Failed return URL error Yes if error code 004 or 010

ERR_TRRETURNURLKO Up to 256 alphanumeric


73

In case of return of the error code 015 (Application server down), only the following

parameters are sent:

Parameter Mandatory Parameter name Type Comment Error code Yes ERRORCODE 3 numeric Sent using POST

Failure return URL Yes TRRETURNURLKO Up to 256 alphanumeric

Sent using POST


74

III.8.2.1 Output signature in case of failure

The signature guarantees that the data the "Delivery options" page sends to you will not be modified subsequently. The signature, based on an SHA key specific to you allows a check to be made on the information received. The signature must be compared to that calculated by Colissimo, in lower-case and encoded according to the configuration sent on input (by default, ISO 8859-1): these two signatures must be identical. If this is not the case, the data must be considered as having been changed and the shipper must implement a bypass process to offer delivery to its buyer. Calculation: An SHA algorithm must be applied to a concatenation of fields: The SHA-1 algorithm (Secure Hash Algorithm) is a cryptographic hash function. It produces a 160-bit signature (40 characters). Its implementation depends on your technical environment. Java and Javascript implementation examples are provided in Annexe 2 Example of the calculation of an SHA signature in Java and Javascript. Field used for signature in case of failure Field name Mandatory

FO identifier PUDOFOID

addressee last name CENAME

Order preparation time DYPREPARATIONTIME

Forwarding charges DYFORWARDINGCHARGES

Shipping costs Pick-up station DYFORWARDINGCHARGESCMT



Transaction no. ORDERID


Error code ERRORCODE Yes

FO Identifier error ERR_PUDOFOID Yes if error code 001, 002 or 003

Signature error ERR_SIGNATURE Yes if error code 006 or 007

Forwarding charges error ERR_DYFORWARDINGCHARGES Yes, if error code 012 or 004 and concerned by error

Forwarding charges error to Pick-up Locations ERR_DYFORWARDINGCHARGESCMT Yes, if error code 012 and concerned by error the error

Transaction number error ERR_ORDERID Yes, if error code 011 or 004 and concerned by error

Addressee postcode error ERR_CEZIPCODE Yes if error code 008


75

Validation return URL error ERR_TRRETURNURLOK Yes if error code 009

Failed return URL error ERR_TRRETURNURLKO Yes, if error code 010 or 004 and concerned by error

Failure return URL TRRETURNURLKO Yes



International Option TRINTER

addressee language CELANG

The field order must be respected. The SHA key provided by La Poste - Colissimo must also be concatenated to the end of the string. String_to_convert=PUDOFOID+CENAME+DYPREPARATIONTIME+DYFORWARDINGCHARGES+DYFORWARDINGCHARGESCMT+TRCLIENTNUMBER+TRORDERNUMBER+ORDERID+TRPARAMPLUS+ERRORCODE+ERR_PUDOFOID+ERR_SIGNATURE+ERR_DYFORWARDINGCHARGES+ERR_DYFORWARDINGCHARGESCMT+ERR_ORDERID+ERR_CEZIPCODE+ERR_TRRETURNURLOK+ERR_TRRETURNURLKO+TRRETURNURLKO+CHARSET+CEPAYS+TRINTER+CELANG+cléSHA

Signature=SHA1(String to convert) Some of the above fields cannot be sent since they have not been sent in the call parameters If they are not sent by the "Delivery options" page, they must not be considered in calculating the signature. Concatenation example with a restricted list of fields: String_to_convert=PUDOFOID+DYFORWARDINGCHARGES+ORDERID+ERRORCODE+ERR_DYFORWARDINGCHARGES+TRRETURNURLKO+cléSHA Signature=SHA1(String to convert) Particularity of error codes 001, 002 and 016: In these error cases, the calling account cannot be identified by the "Delivery options" page as the FO identifier has not been sent, is incorrect or the La Poste – Colissimo service is in downgraded mode. The page is unable to identify the SHA-1 key which is particular to you and therefore return the corresponding signature.

Simplicité – Colissimo "Delivery Options" I-Frame Page – November 2015 76

IV. Annexes

IV.1 Annex 1: Field of the "Delivery options" page

Field name Type Mandatory Modifiable Length

Step 1

Title Radio button Yes Yes

Name Alphanumeric Yes Yes 1..34

First Name Alphanumeric Yes Yes 1..29

Company name (if company address)

Alphanumeric Yes 0..38

Floor, corridor, staircase, apartment no.


Entrance, building, residence


Named place or other particular information


Number and street name Alphanumeric Yes Yes 1..38

Postcode Alphanumeric Yes Yes 5

Municipality Alphanumeric Yes Yes 1..32

Country Alphanumeric If "option international" parameter »= 1

0..32

Email Alphanumeric Yes Yes 5..80

Mobile phone Numeric Yes 0..10

Step 2 - delivery options

Door code Alphanumeric Yes 0..8

Door code 2 Alphanumeric Yes 0..8

Other delivery instructions Alphanumeric Yes 0..70

Mobile phone Numeric Yes except for home delivery

Yes 0..10

Step 2 - pick-up locations

Address Alphanumeric Yes 1..38

Postcode Alphanumeric Yes 5

Municipality Alphanumeric Yes 1..32

Country Alphanumeric If "option international" parameter »= 1

0..32


IV.2 Annex 2: Example of the calculation of an SHA signature in Java and Javascript

Java example import java.security.MessageDigest; import java.security.NoSuchAlgorithmException; import org.apache.commons.codec.binary.Hex; /* Chiffre en SHA une chaine fournie en paramètre puis effectue une conversion en hexadécimal. * Retourne <code>null</code> en cas d'exception. * @param stringToDigestAndConvert La chaine a traiter * @param algorithm L'algorithme a utiliser * @return La chaine chiffree et convertie en hexa. */ private String digestAndConvertToHexString(String stringToDigestAndConvert) { String ALGORITHM = "SHA-1"; // Encodage try { MessageDigest md = MessageDigest.getInstance(ALGORITHM); md.update(stringToDigestAndConvert.getBytes()); // Conversion en hexa avec Apache Commons Codec return String.valueOf(Hex.encodeHex(md.digest())); } catch (NoSuchAlgorithmException nsae) { return null; } }

The SHA signature calculation is performed by a class internal to jdk < (version >=1.4.2) the library performing the conversion into hexadecimal is: commons-codec 1.3 (http://commons.apache.org/codec/ )

Javascript example

function SHA1 (msg) {

function rotate_left(n,s) {

var t4 = ( n<<s ) | (n>>>(32-s));

return t4;

};

function lsb_hex(val) {

var str="";

var i;

var vh;

var vl;

for( i=0; i<=6; i+=2 ) {

vh = (val>>>(i*4+4))&0x0f;

vl = (val>>>(i*4))&0x0f;


str += vh.toString(16) + vl.toString(16);

}

return str;

};

function cvt_hex(val) {

var str="";

var i;

var v;

for( i=7; i>=0; i-- ) {

v = (val>>>(i*4))&0x0f;

str += v.toString(16);

}

return str;

};

var blockstart;

var i, j;

var W = new Array(80);

var H0 = 0x67452301;

var H1 = 0xEFCDAB89;

var H2 = 0x98BADCFE;

var H3 = 0x10325476;

var H4 = 0xC3D2E1F0;

var A, B, C, D, E;

var temp;

var msg_len = msg.length;

var word_array = new Array();

for( i=0; i<msg_len-3; i+=4 ) {

j = msg.charCodeAt(i)<<24 | msg.charCodeAt(i+1)<<16 |

msg.charCodeAt(i+2)<<8 | msg.charCodeAt(i+3);

word_array.push( j );

}

switch( msg_len % 4 ) {

case 0:

i = 0x080000000;

break;

case 1:

i = msg.charCodeAt(msg_len-1)<<24 | 0x0800000;

break;


case 2:

i = msg.charCodeAt(msg_len-2)<<24 | msg.charCodeAt(msg_len-1)<<16 | 0x08000;

break;

case 3:

i = msg.charCodeAt(msg_len-3)<<24 | msg.charCodeAt(msg_len-2)<<16 |

msg.charCodeAt(msg_len-1)<<8 | 0x80;

break;

}

word_array.push( i );

while( (word_array.length % 16) != 14 ) word_array.push( 0 );

word_array.push( msg_len>>>29 );

word_array.push( (msg_len<<3)&0x0ffffffff );

for ( blockstart=0; blockstart<word_array.length; blockstart+=16 ) {

for( i=0; i<16; i++ ) W[i] = word_array[blockstart+i];

for( i=16; i<=79; i++ ) W[i] = rotate_left(W[i-3] ^ W[i-8] ^ W[i-14] ^ W[i-16], 1);

A = H0;

B = H1;

C = H2;

D = H3;

E = H4;

for( i= 0; i<=19; i++ ) {

temp = (rotate_left(A,5) + ((B&C) | (~B&D)) + E + W[i] + 0x5A827999) & 0x0ffffffff;

E = D;

D = C;

C = rotate_left(B,30);

B = A;

A = temp;

}

for( i=20; i<=39; i++ ) {

temp = (rotate_left(A,5) + (B ^ C ^ D) + E + W[i] + 0x6ED9EBA1) & 0x0ffffffff;

E = D;

D = C;


B = A;


A = temp;

}

for( i=40; i<=59; i++ ) {

temp = (rotate_left(A,5) + ((B&C) | (B&D) | (C&D)) + E + W[i] + 0x8F1BBCDC) & 0x0ffffffff;

E = D;

D = C;


B = A;

A = temp;

}

for( i=60; i<=79; i++ ) {

temp = (rotate_left(A,5) + (B ^ C ^ D) + E + W[i] + 0xCA62C1D6) & 0x0ffffffff;

E = D;

D = C;


B = A;

A = temp;

}

H0 = (H0 + A) & 0x0ffffffff;

H1 = (H1 + B) & 0x0ffffffff;

H2 = (H2 + C) & 0x0ffffffff;

H3 = (H3 + D) & 0x0ffffffff;

H4 = (H4 + E) & 0x0ffffffff;

}

var temp = cvt_hex(H0) + cvt_hex(H1) + cvt_hex(H2) + cvt_hex(H3) + cvt_hex(H4);

return temp.toLowerCase();

}


IV.3 Annex 3: Example of an IFrame call method using POST Since passing of parameters to the "Delivery options" page uses POST it is not possible to directly call the URL of the "Delivery options" page in the IFrame tag. This can be done for example by creating an html page on your website which will be called via the IFrame tag and which will redirect to the "Delivery options" page by providing it with the parameters using POST. This page can contain a form using POST with the parameters that you want to transmit. The attribute of the form action will contain the URL of the "Delivery options" page and the form will be automatically submitted via javascript. This implementation solution is given as an example, other possibilities exist. Here is a partial example of html code (In our case the file containing the html code is called redirect.html) <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html><head><title></title> <meta http-equiv="Content-Type" content="text/html;charset=ISO-8859-1"></head> <body> <form name="formSOLivraisonSimplicite" action="http://ws.colissimo.fr/pudo-fo-frame/storeCall.do?trReturnUrlKo=http://mondomaine.fr/retour_KO.jsp" method="post"> <input type="hidden" name="pudoFOId" value="05345352473065"> <input type="hidden" name="orderId" value="SYL300"> <input type="hidden" name="trReturnUrlok" value= "http://mondomaine.fr/retour_OK.jsp"> <input type="hidden" name="trReturnUrlKo" value= "http://mondomaine.fr/retour_KO.jspp" > <input type="hidden" name="dyForwardingCharges" value="18,23"> <input type="hidden" name="numVersion" value="4.0"> <input type="hidden" name="key" value= "292051151371"> <input type="hidden" name="ceCivility" value="MLE"> <input type="hidden" name="ceName" value="Mon nom"> <input type="hidden" name="ceFirstName" value="Mon prenom"> <input type="hidden" name="ceCompanyName" value=""> <input type="hidden" name="ceAdress1" value=""> <input type="hidden" name="ceAdress2" value=""> <input type="hidden" name="ceAdress3" value="10 rue de paris"> <input type="hidden" name="ceAdress4" value=""> <input type="hidden" name="ceZipCode" value="75011"> <input type="hidden" name="ceTown" value="PARIS"> <input type="hidden" name="ceEntryPhone" value="Interphone"> <input type="hidden" name="ceDeliveryInformation" value="infos compl"> <input type="hidden" name="ceEmail" value="[email protected]"> <input type="hidden" name="cePhoneNumber" value="0600000004"> <input type="hidden" name="ceDoorCode1" value="porte 1"> <input type="hidden" name="ceDoorCode2" value="porte 2"> <input type="hidden" name="dyWeight" value="12450"> <input type="hidden" name="dyPreparationTime" value="6"> <input type="hidden" name="trClientNumber" value="num client"> <input type="hidden" name="trOrderNumber" value="num commande"> <input type="hidden" name="trFirstOrder" value="0"> <input type="hidden" name="trParamPlus" value="Param plus"> <input type="hidden" name=" CHARSET " value=" UTF-8"> <input type="hidden" name=" cePays " value="FR"> <input type="hidden" name=" trInter " value="1"> <input type="hidden" name=" ceLang" value="FR"> <input type="hidden" name=" dyForwardingChargesCMT " value="2">


<input type="hidden" name="signature" value=""> </form> <script> function validation() { var dataToCrypt="";  document.formSOLivraisonSimplicite.signature.value=SHA1(dataToCrypt); } validation();  document.formSOLivraisonSimplicite.submit(); </script> </body></html> Exemple d'appel en iframe <iframe align="right" id="SOLivraison" name="SOLivraison" style="border:0px solid #000000" marginwidth="0" marginheight="0" frameborder="0" border="0" width="" height="" src="./redirect.html"></iframe>


IV.4 Annex 4: Exit from the IFrame Note that at the end of the process on the "Delivery options" page, on validation by the Internet user, the return result transmitted to your return validation URL is displayed in the main browser window (and not in the Iframe).

Colissimo Delivery Options I-Frame Page · 2020-02-29 · Simplicité – Colissimo "Delivery Options" I-Frame Page – November 2015 4 5.0 19/03/2012 Integration of the "Delivery

Documents