the technical documentation - pdf - Colissimo

Transcription

Simplicité - Shipping
Business Solutions
Colissimo Retour Online Page
Colissimo Retour France and International
Technical document – version November 2015
Implementation guideline of Colissimo Retour Online Page
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
CONTENTS
1. INTRODUCTION ......................................................................................................................................... 4
1.1. Purpose of the Simplicité Retour Online solution.................................................................................. 4
1.2. Purpose of the document...................................................................................................................... 4
1.3. Glossary ............................................................................................................................................... 4
2. CONFIGURATION OF THE RETOUR ONLINE FUNCTIONALITIES.......................................................... 5
2.1. General................................................................................................................................................. 5
2.2. Configuration of return addresses ........................................................................................................ 7
2.3. Configuration of return options ............................................................................................................. 8
2.3.1. Cobranding of web pages and e-mails .......................................................................................... 8
2.3.2. Cobranding of the freight lists (for Colissimo Retour France) ........................................................ 8
2.3.3. Selection of an optional insurance level by default ........................................................................ 9
2.3.4. Reasons for return......................................................................................................................... 9
2.3.5. Customer Service Information ..................................................................................................... 10
2.3.6. Notification by e-mail to sender of the delivery of his parcel ........................................................ 10
2.3.7. Confirmation of the configuration................................................................................................. 10
2.4. Configuration of the Front Office page................................................................................................ 11
3. CALL OF COLISSIMO RETOUR WEB PAGES ........................................................................................ 11
3.1. General information about the exchanges on the Internet .................................................................. 12
3.2. La Poste's recommendation for using this service .............................................................................. 12
3.3. Liability linked to the electronic data exchanges ................................................................................. 12
3.4. Parameters to transmit ....................................................................................................................... 14
3.4.1. Your Retour Online identifier ....................................................................................................... 17
3.4.2. Request number .......................................................................................................................... 17
3.4.3. ParamPlus................................................................................................................................... 17
3.4.4. Notes relating to the other fields .................................................................................................. 17
3.4.5. Calculation of the signature ......................................................................................................... 18
3.4.6. Example of transmission of mandatory parameters .................................................................... 19
3.4.7. Example of sending all parameters ............................................................................................. 21
3.5. ERROR MANAGEMENT .................................................................................................................... 23
3.6. RETURN TO YOUR WEB SITE ......................................................................................................... 26
3.6.1. Overview diagram ....................................................................................................................... 28
4. CONTACT ................................................................................................................................................. 29
5. ANNEXES.................................................................................................................................................. 30
5.1. Annex 1 .............................................................................................................................................. 30
5.2. Annex 2 .............................................................................................................................................. 32
5.3. Annex 3 .............................................................................................................................................. 33
5.4. Annex 4 .............................................................................................................................................. 34
5.5. Annex 5 .............................................................................................................................................. 38
5.6. Annex 6 .............................................................................................................................................. 39
5.7. Annex 8 .............................................................................................................................................. 41
5.8. Annex 9 .............................................................................................................................................. 42
5.9. Annex 10 ............................................................................................................................................ 43
5.10.
Annex 11......................................................................................................................................... 44
Simplicité – Colissimo Retour Online Page – November 2015
2
5.10.1.
Freight lists departure from France .......................................................................................... 44
5.10.2.
Freight lists departure from International locations .................................................................. 47
5.11.
Annex 12......................................................................................................................................... 48
3
1.
INTRODUCTION
1.1.
Purpose of the Simplicité Retour Online solution
Directly accessible from your web site, this solution enables your customers
and partners to print their own Colissimo Retour France and/or Colissimo
freight list.
1.2.
Purpose of the document
This document describes the various operations to be carried out for access to
the functionalities of this solution.
The solution comprises 2 modules:
• The Back Office (BO): called "Configure your franking solutions –
Colissimo Retour",
it can be accessed on http://www.laposte.fr/colissimo-entreprise.
It enables you to administer the functionalities of the Colissimo Retour Online
product.
• The Front office (FO): called "Retour Online web pages", these are La
Poste web pages to which you redirect your customer so that he can create his
own freight list.
1.3.
Glossary
DEFINITION
Addressee’s
Address
Sender
Freight list
Alphanumeric
character
SHA1
BC
Online Return
Identifier
Pick-up request
The Addressee’s address is the delivery address where you
want your customers/partners to return the goods.
The sender is the customer/partner who sends you "return"
parcels
The freight list comprises two parts:
-The left-hand pane, which contains the bar codes (BC),
must be affixed to the parcel,
-The right-hand pane constitutes the certificate of posting
and must be kept by the sender.
The term alphanumeric character in this document
describes: • numeric and alphabetic characters:
• alphabetic characters (upper and lower case),
• lower case accented characters and 'ç'
as well as the space,'-' and '_' characters unless explicitly
mentioned otherwise
Cryptographic hashing function Enables the securing of the
calling of Colissimo Retour Online web pages
Bar code
This is the identifier that is displayed in the "Configuration
of Front office pages" section in your Colissimo Retour
Customer web account
Appointment with the Post Office for pick-up of the parcel
by the postman from the mailbox.
4
2.
2.1.
CONFIGURATION OF THE RETOUR ONLINE
FUNCTIONALITIES
General
Configuration of the functionalities of the Retour Online solution is made
through your Colissimo Retour Customer web account, accessible on
colissimo.fr/entreprises.
Prior condition: Only customers who have signed up to Simplicité Retour
Online solution have access to these functionalities.
To enable or customise the use of Colissimo Retour Online you must
carry out the following operations:
OPERATIONS TO
CARRY OUT IN THE
"COLISSIMO
RETOUR
CUSTOMER WEB
ACCOUNT" BACKOFFICE
1/ Enter at least one
return address
2/ Choose a logo for
the Colissimo Retour
Online Web pages
3/ Choose an image
for the transport
slips
4/
Select
the
insurance level
COMPULSORY
Yes, at least one address.
CORRESPONDING PAGE
No.
Configuration
of
return
addresses
Configuration of return options
No.
Optional (may also be Configuration of return
transmitted via the URL –
see rules).
5/ Define the return Optional list
Configuration of return
reasons
Possibility of activating free
entry
May also be transmitted via
the url.
6/
Enter
the Optional (otherwise display Configuration of return
information relating at bottom of page).
to your Customer
Services
7/
Activate
the Optional.
Configuration of return
notification by email to your sender
of the receipt of his
parcel
options
options
options
options
5
8/ Define the SHA
key
9/ Define the return
urls of your web site
9/ Define the return
urls of your web site
Yes, 5 to 12 characters.
Configuration
Office page
Yes, both addresses can be Configuration
the same.
Office page
Yes, both addresses can be Configuration
the same.
Office page
of
the
Front
of
the
Front
of
the
Front
NEW: As of May 2015, Colissimo Retour France parcels can be deposited in a
post office or Pick-up Location, but also from the return sender’s personal
mailbox, if the address of the sender customer is eligible for this service.
The return sender may make his request for pick-up from a mailbox from the
La Poste's website www.colissimo.fr, using the parcel number found on the
Colissimo Retour label. The date and time of deposit of the parcel will be
indicated on the site, as well as the conditions for using the service (mailbox
accessible and able to contain the parcel, eligibility of the address etc.). For
more information, go to https://www.colissimo.fr/retourbal, then select "Learn
more about Colissimo Retour".
The postman picks up the parcel from the mailbox, on the agreed date,
leaving written notice in the form of a collection advice. This document
confirms that the Colissimo Retour was picked up as planned, or if not, states
the reason why the parcel could not be collected.
6
2.2.
Configuration of return addresses
This is the list of the possible destination addresses for the parcel. These data
must be entered into the "Your Retour addresses" section in your Colissimo
Retour Customer Web Account. The entry of at least one return address is
required and the maximum number of possible addresses is 100.
Each address is identified by an address name. This information must be sent
to the web pages of Retour Online when making a request for a freight list.
Each address is comprised of the following fields:
NAME
TYPE
COMPULSORY
Name of the
address: is used
as the identifier
when selecting
an address
Company name
Department
Title
Name
15 alphanumeric characters
Space characters are not allowed
(separate words using '-' or '_')
Yes
Mr/Mrs/Miss drop down list
Yes
No
No
No
First Name
Address: 4 lines
in all
Post Code
City
No
1st line compulsory
Non-modifiable drop-down list displaying
all localities matching the entered post
code
35 characters – Drop-down list: Default
value "France"
15 numeric characters
Yes
Yes
Country
Telephone
Yes
No
7
2.3.
The configuration described in this chapter matches the section "Configuration
of return options" in your Colissimo Retour Customer Web Account. This stage
is not indispensable to the operation of the Retour Online web pages.
2.3.1.Cobranding of web pages and e-mails
In this module you can select the logo that you wish to display cobranding it
with the La Poste group's on:
Colissimo Retour Online web pages
confirmation e-mails sent by La Poste to your senders.
Note about e-mails:
2 e-mails are sent to your customers/partners:
- an e-mail allowing them online access to their "retour" freight list, which may
therefore be cobranded with your logo.
- an e-mail confirming delivery of their parcel (if the corresponding option is
enabled) (see section 2.3.6 "Notification by e-mail"), which can be cobranded
with your logo only in the case of Colissimo Retour France.
The restrictions for this logo are the following:
gif or jpeg format
40 KB maximum size
maximum resolution of 200 wide by 60 high (this restriction is checked
during the uploading of the logo into the "Configuration of return options"
section).
It is not necessary to keep the same width/height ratio and there is no
restriction on the number of colours. The logo will be centred on the righthand part of the upper orange strip.
Checks will be made regarding the file size and image resolution during
uploading and only files which comply with the set rules will be accepted.
After the selection of a new logo, the previewing buttons enable the web and
e-mail pages to be displayed including this new logo.
2.3.2.Cobranding of the freight lists (for Colissimo Retour France)
You can select the image that you wish to include in the proof of deposit part
of the created freight list. The restrictions are the following:
gif or jpeg format
100 KB maximum size
8
maximum resolution of 700 wide by 360 high: warning, this resolution
will be reduced by a factor of 2 during the creation of the PDF (the restriction
regarding the 700 by 360 resolution is checked during the uploading of the
logo in the "Configuration of return Options" section).
It is not necessary to keep the same width/height ratio and there is no
restriction on the number of colours.
The logo will be centred on the reserved area in the upper part of the proof of
deposit. After the selection of a new image, the preview button enables a
specimen freight list to be displayed.
2.3.3.Selection of an optional insurance level by default
The "Configuration of return options" section also enables an optional
insurance level by default to be defined.
However, you can send a specific insurance level for each of the shipments
when calling the Web Retour OnLine pages.
The following rules apply:
AN INSURANCE LEVEL
HAS BEEN DEFINED IN
THE "Configuration of
return options" SECTION
OF YOUR COLISSIMO
RETOUR CUSTOMER WEB
ACCOUNT
AN INSURANCE
LEVEL HAS BEEN
TRANSMITTED IN
THE URL WHEN
CALLING COLISSIMO
RETOUR WEB PAGES
Yes
Yes
No
Yes
No
No
RULES
The level of insurance
transmitted in the url
applies.
defined
in
the
"Configuration
of
return options" section
applies.
transmitted in the url
applies.
No optional insurance
level
2.3.4.Reasons for return
The "Configuration of return options" section allows a maximum 5 reasons for
return to be defined. This list will appear in the Colissimo Retour web pages in
the form of a drop-down list where your customer can select a suitable reason
for his parcel.
9
It is also possible in the "Configuration of return options" section to authorise
free entry of a reason.
The reason may also by transmitted as a parameter when calling Retour
Online web pages A reason is composed of a maximum of 35 alphanumeric
characters. (see section 3.4 " Parameters to transmit").
NB:
To transmit a reason other than those defined in the "Configuration of return
options" section in the url, the "Other reason" field must be selected ("Yes"
box checked).
2.3.5.Customer Service Information
It is also possible to enter information regarding your Customer services. This
information is displayed at the bottom of the Retour Online web pages. These
are:
DEFINITION
Company name or
Customer services
service name
Telephone
Note about the cost of
the call to Customer
services – e.g.: 30
cents/minute
TYPE
Maximum 35 alphanumeric characters
Maximum 200 alphanumeric characters
This information will appear in this form:
Company name 0123456789 (30 cts/min)
2.3.6.Notification by e-mail to sender of the delivery of his parcel
By default, the sender does not receive notification when his parcel is
delivered. This notification can be activated by the corresponding option at the
bottom of the "Configuration of return options" section.
The notification for a Colissimo Retour France is in French.
The notification for a Colissimo Retour International can be in French but is
also possible in several other languages (see section 3.4 "Parameters to
transmit").
2.3.7.Confirmation of the configuration
The possible modification of the configuration defined in the
"Configuration of return options" section will be taken into account as
soon as this page is confirmed.
10
Request for slips made after a modification of this configuration will
immediately use this new configuration.
In the particular case of the Retour Online web pages, since this is
managed by the use of a cache, taking a new logo into account may
take up to an hour.
When modifying logos all the necessary checks using the previewing
functions integrated into the "Configuration of return options" section
should be used before confirming.
2.4.
Configuration of the Front Office page
The various fields of the "Configuration of the Front Office page" section
in your Colissimo Customer web account must be filled in to enable the
operation of the Retour Online web pages. These are:
DEFINITION
SHA Key
TYPE
COMPULSORY
COMMENT
5
to
12 YES
Key used for the calculation
alphanumeric
of the SHA signature
characters
Return URL to 256 characters YES
your web site respecting the
after
the URL format
creation
of
the
freight
list
Return URL to 256 characters YES
your web site respecting the
after
the URL format
failure of the
freight list
These 2 URLs may however be the same.
In another part of the "Configuration of the Front Office pages" section your
customer identifier is displayed which must be transmitted when Colissimo
Retour Online web pages are called. This identifier cannot be modified.
3.
CALL OF COLISSIMO RETOUR WEB PAGES
The Retour Online web pages are La Poste web pages to which you redirect
your customer so that he can create his own freight list. Your web site must
transmit data of the following type:
Retour Online identifier
Name of the parcel destination address
if appropriate, data regarding the parcel (insurance, large parcel etc.)
11
if appropriate, data which will pre-initialise the data to be filled in by the
parcel sender
The pages check the identifier and the transmitted data.
If these are correct, the sender can then enter and confirm the data regarding
his parcel and can create his freight list. Following these operations, and
depending on the success or failure of the creation of the slip, the customer
may be redirected to a specific page (2 possible URLs) of your web site.
Moreover, in the event of a failure, an error code is returned to your web site.
3.1.
General information about the exchanges on the Internet
HTTP, standing for HyperText Transfer Protocol, is a client-server
communication protocol developed for the World Wide Web.
When they are transmitted using the HTTP protocol, the data are sent in plain
text
(with
no
encryption).
Additional
references:
http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol
HTTPS, standing for HyperText Transfer Protocol Secure — is the combination
of the HTTP protocol with an encryption layer such as SSL or TLS.
In theory, it guarantees the confidentiality and integrity of the data sent by
the user and received by the server.
Additional references: http://en.wikipedia.org/wiki/HTTP_Secure
The protocol used is HTTPS and the methods POST and GET may be used.
The use of POST is however strongly advised.
3.2.
La Poste's recommendation for using this service
Since access to Retour Online web pages is protected by an identifier and a
password which are sensitive data, La Poste recommends you use the HTTPS
protocol for sending these data.
Not using this protocol leaves the Customer open to these identifiers being
intercepted by a malicious third party which would allow it to steal the
Customer's identity and thus:
- to gain access to its corporate space (online invoice, parcel tracking)
- to order products, which will then be charged to the hijacked customer
account.
- to gain access to the other solutions made available by La Poste.
3.3.
Liability linked to the electronic data exchanges
The Customer undertakes to take all relevant measures to ensure the security
and confidentiality of its identifier and password.
12
Any access and transmission of data made, and more widely, any operation
made by using the Customer's identifier and password are deemed to have
been made by the latter.
13
3.4.
Parameters to transmit
The following parameters may or must be transmitted to the Colissimo Retour
Online web pages.
MODIFIA
BLE IN
THE
RETOUR
ONLINE
WEB
PAGES
Does not
appear
FIELD TO TRANSMIT
FOR CALLING RETOUR
ONLINE WEB PAGES
COMP
ULSO
RY
Retour OnLine
identifier
YES
orosld
Sender
address
Professional
NO
YES
Company
Name
NO
crFlagProfess
ional
crCompanyN
ame
Siret
NO
crSiret
YES
Title
Name
NO
NO
crCivility
crName
YES
YES
First Name
NO
cfFirstName
YES
Address line
1
NO
crAdress1
YES
Address line
2
NO
cfAdress2
YES
Address line
3
NO
crAdress3
YES
Address line
4
NO
crAdress4
YES
ISO
CountryCode
NO
crCountryCo
de
YES
PARAMETE
R NAME
YES
POSSIBLE
VALUE
Up to 35 upper
case
alphanumeric
characters
True/false
50
alphanumeric
characters
14
alphanumeric
characters
mr/mrs/miss
35
alphanumeric
characters
35
alphanumeric
characters
50
alphanumeric
characters
35
alphanumeric
characters
35
alphanumeric
characters
35
alphanumeric
characters
2 alphabetic
characters
- For Colissimo
Retour France,
countryCode
must be set to
14
Address
ee’s
Address
Parcel
Display
language
NO
codelangue
YES
Town
NO
crTown
YES
PostalCode
NO
crZipCode
YES
PhoneNumb
er
NO
crTel
YES
Mail
NO
crEmail
YES
Name
address
YES
destinationN
ame
Does not
appear
Insurance
level
Bulky
NO
insuranceRa
nge
flagBulky
Does not
appear
Not
editable if
transmitte
d in the
url
NO
"FR".
- For Colissimo
Retour
International,
countryCode
must not be set
to FR.
Currently, DE,
GB, LU, NL, BE,
IE, SK, SI, FI.
2 alphanumeric
characters
By default, FR.
The possible
languages for a
Colissimo
International
return are: EN
(English), DE
(German), NL
(Dutch), ES
(Spanish) and
IT (Italian).
35
alphanumeric
characters
5 alphanumeric
characters for
France and up
to 9 for
international
destinations
15
alphanumeric
characters
200 email
compliant
characters
15
alphanumeric
characters
Integer from 0
to 10
true/false
15
Custome
r
Specific
Data
Request
Control
Reason for
return
NO
returnMotive
Customer
no.
NO
trClientNumb
er
Product ref
NO
trProductRef
Order no.
NO
trOrderNumb
er
Return
reference
NO
trReturnRef
Parameter
to return to
your web
site
NO
trParamPlus
Request
number
YES
orderld
SHA
signature
YES
signature
Not
editable if
transmitte
d in the
url
Not
editable if
transmitte
d in the
url
Not
editable if
transmitte
d in the
url
Not
editable if
transmitte
d in the
url
Not
editable if
transmitte
d in the
url
Not
editable if
transmitte
d in the
url
Does not
appear
Does not
appear
35
alphanumeric
characters
30
alphanumeric
characters
30
alphanumeric
characters
30
alphanumeric
characters
15
alphanumeric
characters
256
alphanumeric
characters
25
alphanumeric
characters
40
alphanumeric
characters
Determined by
calculation
Convention regarding the certain parameter names:
the prefix cr designates sender data (consignor)
the prefix tr designates your specific data (trader).
If the length of a parameter exceeds the authorised length defined in the
above table, the end of the character string will be truncated to respect this
condition.
For Boolean parameters, any other value than "true" or "TRUE" is considered
to be equal to FALSE.
16
3.4.1.Your Retour Online identifier
This is the identifier that is displayed in the "Configuration of Front office
pages" section in your Colissimo Retour Customer Web Account.
(see section 2.4 "Configuration of the Front Office" page)
3.4.2.Request number
Each slip request must be accompanied by its own request number (for a
given e-trader).
When you call Retour Online web pages, your web site must therefore
generate a new request number.
It is completely free to generate this number incrementally or otherwise (e.g.
using the current date and time in milliseconds with precautions of use which
guarantee its uniqueness).
Requests for freight lists which contain an already used request number and
because of this have resulted in a slip being generated will be rejected (even if
the sender has not used this freight list).
3.4.3.ParamPlus
This parameter allows your web site to transmit to the Retour Online web
pages specific data for the freight list request that La Poste will not interpret.
These data will be returned to your web site after the request has been
processed on the return to your web site.
They must be in the form: trParamplus=XXX
With XXX: alphanumeric string of up to 256 characters
This parameter will be returned in the same form; (see section 3.6
"Return to your web site").
3.4.4.Notes relating to the other fields
1.1.1.1
Postcode/City correspondence:
The correspondence between the post code and the city will be checked, for
France only, but it does not generate an error. If this check fails, the town will
not be pre-selected in the drop-down list corresponding to the 1st Colissimo
Retour Online web page.
17
1.1.1.2
Optional insurance level:
The insurance level field must be an integer, between 0 and 10 i.e.:
INSURANCE RANGE
OPTIONAL INSURANCE LEVEL UP
TO (IN €)
00
01
02
03
04
05
06
07
08
09
10
1.1.1.3
0
150
300
450
600
750
900
1050
1200
1350
1500
Return reference:
This field is a data item which belongs to you and is not interpreted by the
Colissimo Retour web pages.
If your web site transmits it when calling Retour Online web pages, it is
displayed without processing on the freight list in the form of text and also in
the form of vertical bar codes.
3.4.5.Calculation of the signature
The purpose of the signature is to guarantee that the data you transmit to the
Colissimo Retour web pages will not undergo any later modification.
In particular, it makes the memorisation of the calling url in a browser
unusable. This is unusable as it is and the SHA signature prevents it from
being modified.
Also, the signature, based on a SHA key which you is particular to you
(see section 2.4 "Configuration of the Front office page") allows control of
access to the Retour Online web pages.
This involves applying the SHA algorithm to the concatenation of the following
fields:
FIELDS USED FOR THE SIGNATURE
Online Return Identifier
Addressee’s
Name address
Address
Parcel
Insurance level
FIELD NAME
orosld
destinationName
insuranceRange
sent)
(if
18
Bulky
Customer Specific
Data
Request Control
Customer no.
Return reference
Request number
flagBulky (if sent)
trClientNumber
(if
sent)
trReturnRef (if sent)
trOrderNumber
The SHA key must also be concatenated at the end of the string:
String_to_convert = orosId + destinationName + InsuranceRange + flagBulky
+ trClientNumber + trReturnRef + trOrderNumber + 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.
The SHA-1 algorithm (Secure Hash Algorithm) is a cryptographic hash
function. It produces a 160-bit signature (40 characters).
There are implementations in the various environments. You must therefore
use a library adapted to the technology that you use. A java implementation is annexed.
3.4.6.Example of transmission of mandatory parameters
This static html code, when the specified fields are filled in, enables Retour
Online web pages to be called exclusively with the compulsory parameters.
<html>
<head>
<title>Appel de Retour Online Front Office</title>
</head>
<body>
<br/><br/><br/>
    En attente du site retour Online
<form name="formretouronlinecall"
action="http://www.colissimo.fr/retouronline/storeCall.do" method="post">
<input type="hidden" name="orosId" value="123456">
<input type="hidden" name="destinationName" value="SITE_VELIZY">
<input type="hidden" name="orderId" value="1000001">
<input
type="hidden"
value="5066041628908bed27ff54881de9210ec20aff1c">
name="signature"
</form>
<script>document.formretouronlinecall.submit();</script>
</body>
</html>
The signature is calculated, in accordance with the above procedure with the
contents of the fields orosId+ destinationName+orderID+SHAkey (in this
19
example
the
SHAkey
used
"123456SITE_VELIZY1000001LAPOSTE"
is
LAPOSTE),
i.e.
20
Initial test using a web browser:
After replacing the "hidden" parameters with valid parameters, just open this
html page with a web browser and you will be redirected automatically to the
Colissimo Retour web pages with transmission of these parameters.
The 1st Colissimo Retour web page which enables the entry of the freight list
information will then appear.
Note:
Many web sites offer the possibility of making SHA-1 cryptographic
calculations online (search possible using keywords: sha-1 on line for
example). They can be useful for this first test to calculate the signature.
The following information must already have been defined in your
Retour Online Customer Web Account:
o return address "destinationName" (in this example, SITE_VELIZY),
o the SHA key.
The orosld parameter must have as its value the contents of the Retour
Online identifier that is displayed in the "Configuration of Front office pages"
section in your Colissimo Retour Online Customer Web Account.
3.4.7.Example of sending all parameters
This html code, when the specified fields are filled in, enables Retour Online
web pages to be called exclusively with parameters authorised for a
Colissimo
Retour
France.
The signature will be calculated, as described above from the concatenation
of the following parameters:
orosId
destinationName
insuranceRange
flagBulky
trClientNumber
trReturnRef
orderId
i.e. in the example below:
123456SITE_VELIZY2falseCL45678RET89545CMD78954
In order not to send a parameter in the url, this line must be completely
deleted (do not transmit this parameter with an empty value).
An example of not transmitting the insurance level: You must delete the
whole line:
<input type="hidden" name="insuranceRange" value="2">
21
<html >
<head>
<title> Appel de Retour Online Front Office </title></head>
<body><br/><br/><br/>
action=" https://www.colissimo.fr/retouronline/storeCall.do" method="post">
<input type="hidden" name="crName" value="Dubreuil">
<input type="hidden" name="crForename" value="Henri">
<input type="hidden" name="crFlagProfessional" value="true">
<input type="hidden" name="crCompanyName" value="AGFR International">
<input type="hidden" name="crSiret" value="38396013500739 ">
<input type="hidden" name="crCivility" value="Mr">
<input type="hidden" name="crAdress1" value="Escalier B">
<input type="hidden" name="crAdress2" value="Porte C">
<input type="hidden" name="crAdress3" value="5, rue des tilleuls">
<input type="hidden" name="crAdress4" value="hameau de Villeneuve"><input
type="hidden" name="crCountryCode" value="fr">
<input type="hidden" name="crTown" value="Maurepas">
<input type="hidden" name="crZipCode" value="78310">
<input type="hidden" name="crTel" value="0132323232">
<input type="hidden" name="crEmail" value="[email protected]">
<input type="hidden" name="destinationName" value="SITE_VELIZY"><input
type="hidden" name="insuranceRange" value="2">
<input type="hidden" name="flagBulky" value="false">
<input type="hidden" name="returnMotive" value="Erreurs livraison"><input
type="hidden" name="trClientNumber" value="CL45678">
<input type="hidden" name="trProductRef" value="NIKON FTP78">
<input type="hidden" name="trOrderId" value="CMD78954">
<input type="hidden" name="trReturnRef" value="RET89545">
<input type="hidden" name="trAddParameter" value="ABC123456DE789'">
<input type="hidden" name="signature"
value="c64b9e00f3f7bf212983b6c5a463724af049190f">
</form>
</body>
</html>
22
Example for a Colissimo Retour International:
<html >
<head>
<title> Appel de Retour Online Front Office </title></head>
<body><br/><br/><br/>
action=" https://www.colissimo.fr/retouronline/storeCall.do" method="post">
<input type="hidden" name="crName" value="GRUBER">
<input type="hidden" name="crForename" value="Friedrich">
<input type="hidden" name="crFlagProfessional" value="true">
<input type="hidden" name="crCompanyName" value="AGFR International">
<input type="hidden" name="crSiret" value="38396013500739 ">
<input type="hidden" name="crCivility" value="Mr">
<input type="hidden" name="crAdress1" value="Esc B">
<input type="hidden" name="crAdress2" value="C">
<input type="hidden" name="crAdress3" value="5, Strasse tilleuls">
<input type="hidden" name="crAdress4" value="hameau">
<input type="hidden" name="crCountryCode" value="DE">
<input type="hidden" name="codeLangue" value="DE">
<input type="hidden" name="crTown" value="BERLIN">
<input type="hidden" name="crZipCode" value="10871">
<input type="hidden" name="crTel" value="0132323232">
<input type="hidden" name="crEmail" value="[email protected]">
<input type="hidden" name="destinationName" value="SITE_VELIZY"><input
type="hidden" name="insuranceRange" value="2">
<input type="hidden" name="flagBulky" value="false">
<input type="hidden" name="returnMotive" value="Erreurs livraison"><input
type="hidden" name="trClientNumber" value="CL45678">
<input type="hidden" name="trProductRef" value="NIKON FTP78">
<input type="hidden" name="trOrderId" value="CMD78954">
<input type="hidden" name="trReturnRef" value="RET89545">
<input type="hidden" name="trAddParameter" value="ABC123456DE789'">
<input type="hidden" name="signature"
value="c64b9e00f3f7bf212983b6c5a463724af049190f">
</form>
</body>
</html>
3.5.
ERROR MANAGEMENT
The errors that may be triggered when calling Colissimo Retour web pages are
23
referred to by a code.
A message using this code will be displayed on the Retour Online web pages.
The table below lists all possible cases:
ERROR
CODE
10
11
12
13
14
15
16
17
18
19
MEANING
CHECKS /ACTION
The
"orosId"
customer The orosId parameter is compulsory
identifier has not been and therefore must be transmitted to
transmitted (*)
the Online Return web pages.
Check that the orosId identifier
transmitted is the one that appears in
The
"orosId"
customer the
"Configuration of Front office
identifier does not exist in pages" section in your Colissimo
the database (*)
Retour Customer Web Account. If this
is the case, contact La Poste- Parcel
Unit.
Impossible to access the This is a problem of access to the
data
matching
this database. Wait a short time then
customer code (*)
renew the call or contact Colissimo
You do not have (or no In this case, the Colissimo Retour
longer
have)
access space is also not accessible in the
permission
to
the Customer web account. To reactivate
Colissimo
Retour the Colissimo Retour functionalities,
functionalities.
contact La Poste- Parcel Unit
The destinationName parameter is
The addressee address
compulsory and therefore must be
name
has
not
been
transmitted to the Colissimo Retour
transmitted
web pages.
The destinationName parameter must
The addressee address match an address name entered into
name does not exist in the the "Your Retour addresses" section in
database
your Colissimo Retour Customer Web
Account.
The orderId parameter is compulsory
The
request
number
and therefore must be transmitted to
(orderId) has not been
the Colissimo Online Return web
transmitted
pages.
The transmission of an orderId which
The label corresponding to has already been used for generating a
this
request
number previous slip is not allowed. Ensure
(orderId) has already been that the generation algorithm for
generated
for
this orderId cannot create the same
customer.
identifier for distinct calls and then
transmit a new orderId.
The signature parameter is compulsory
The SHA signature has not
and therefore must be transmitted to
been transmitted.
the Retour Online web pages.
The SHA key has not been In the "Configuration of the Front office
24
filled
out
in
the
"Configuration of Front
office pages" section of
your
Colissimo
Retour
Customer Web Account.
20
The SHA signature is not
correct
21
transmitted could not be
interpreted.
30
Failure
during
generation of the slip
the
page" section of your Colissimo Retour
Customer Web Account, enter the field
"SHA key" and validate the page.
The call of Retour Online web pages
can now be carried out with a
signature calculated using this key.
Check that the signature has be
calculated correctly in accordance with
the rule set out in the paragraph
"Calculation of the signature" (section
3.4.5)
Ensure
that
the
insuranceRange
parameter is an integer between 0 and
10.
This is a technical problem. Wait a
short time and then renew the
operation or contact the La Poste Parcel Unit hotline
(*) The error code will not be returned to you because you are not identified
25
3.6.
RETURN TO YOUR WEB SITE
The diagram below shows the various possible sequences.
The generation of the freight list is carried out in 3 stages:
Stage 1: the sender completes the transmitted data
Stage 2: the sender confirms all of the data
Stage 3: Display of the "Your request has succeeded" page o The freight list is ready to be printed,
o an e-mail referring to this freight list has been sent to the sender,
o a button enables you to return to your web site. Returning to your web site is done to one of the 2 addresses stated in the
"Configuration of the Front Office page" section in your Colissimo Retour
Customer Web Account depending on the success or failure of the generation
of the freight list. The return url is made up by concatenating the various following fields: • If the generation of the freight list was successful:
CONTENTS OF THE RETURN FOR EXAMPLE
URL
The URL success entered in http://www.emarchand.fr/OROSReturn1
the "Configuration of Front
office pages" section of your
Colissimo Retour Customer
Web Account.
Parcel number
? parcelNumber=XXX
The contents of ParamPlus if &trParamPlus =ABC123456DEF789
they were transmitted by
your web site.
In this example the return url will be:
http://www.emarchand.fr/OROSReturn1?parcelNumber=XXX&trParamPlus=ABC
12345DEF789
If the generation of the freight list failed:
CONTENTS OF THE RETURN FOR EXAMPLE
URL
The URL failure entered in http://www.emarchand.fr/OROSReturn2
the "Configuration of Front
office pages" section of your
Colissimo Retour Customer
Web Account.
OROS error code
? ErrorCoderOROS=XXX
The contents of ParamPlus if &trParamPlus =ABC123456DEF789
they were transmitted by
26
your web site.
In this example the return url will be:
http://www.emarchand.fr/OROSReturn2?ErrorCoderOROS=XXX&trParamPlus=A
BC12345DEF789
27
3.6.1.Overview diagram
RETOUR ONLINE WEB
PAGES
YOUR WEB SITE
Call to
Colissimo
Retour Online
web page
Data(*) signature
ParamPlus
ok
Validation of
parameters
"Stage 1" Page:
Data entry/confirmation
Validation of
sender
failure
Return Management
Page
Parameter
error page
Data
validation
failure
Validation
sender
"Failure to generate a
freight list" return
page
ok
"Stage 2" Page:
Data confirmation
ParamPlus error
code
Request to
return to your
web site
ok
data validation by
the sender
failure
Validation of sender
Error page for
transport slip
generation
Error page for
returning to your web
site
No
Yes
failure
Generation of
freight list
ok
failure
Return page:
"Freight list
generated"
ParamPlus parcel
number
ok
"Stage 3" Page:
"Your request was
successful"
Request to
return to your
web site
Validation of
sender
28
4.
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 (standard rate
call), from Monday to Friday, 9 am to 6
pm.
To confirm the solution chosen:
• Your La Poste – Colissimo sales contact
Operational phase,
after solution deployment
In case of failure, anomaly or incident:
• The Service Centre
on 0825.086.005 (€0.15/min),
from Monday to Friday from 8am to 6pm,
except on public holidays.
Say"Incident",
then "Retour online" when asked to
choose.
The availability and proper operation of our
systems are supervised, even outside these
hours.
29
5.
ANNEXES
5.1.
Annex 1
Colissimo Retour Customer Web Account Home:
30
31
5.2.
Annex 2
Colissimo Retour Customer Web Account: return parcel tracking
32
5.3.
Annex 3
Colissimo Retour Customer Web Account
Configuration of return addresses
33
5.4.
Annex 4
Configuration of return options:
34
35
36
37
5.5.
Annex 5
Example of the first Colissimo Retour Online web page:
38
5.6.
Annex 6
Examples of access e-mail for the freight list:
English version:
39
Examples of delivery confirmation e-mail:
English version:
40
5.7.
Annex 8
Selection of an optional insurance level by default:
41
5.8.
Annex 9
Configuration of the Front office pages
42
5.9.
Annex 10
Calculation of the SHA signature in java:
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import org.apache.commons.codec.binary.Hex;
/* Chiffre en SHA une chaine fournie en parametre 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 calculation of the SHA signature is carried out using an internal jdk class
(version >=1.4.2)
• the library performing the conversion into hexadecimal is:
commons-codec 1.3 (http://commons.apache.org/codec/)
43
5.10. Annex 11
Examples of freight lists
5.10.1.Freight lists departure from France
Examples of freight lists with or without an image
Model 1- If the address of the sender does not allow him to ship the parcel
from his personal mailbox:
44
Model 2- If the address of the sender allows him to ship the parcel from his
personal mailbox:
45
46
5.10.2.Freight lists departure from International locations
Example of freight lists with or without an image - from international
locations:
<
47
5.11. Annex 12
Example: Error message
48

the technical documentation - pdf - Colissimo

Transcription

Similar documents

Products Catalogue 2014

CONFIDENCE

On Range Road 25, Innisfail T4G 1T8

4 - Missouri Trucking Association

47th Missouri Truck Driving Championships 2014

Pushing the Package-Locker Box Solutions

XGames.ESPN.go.com

Read here more about our excellent logistics services. - Weiss

the hidden smile - Press | Sundance Institute

Sets - Hank`s Truck Pictures