The api.declare_parcel function¶
Request description¶
The function takes the following three arguments :
username: given by IMXpassword: given by IMXdata: a dictionary-like object containing your request data
Data object¶
data is described below.
Fields displayed as bold are mandatory, fields suffixed with a dot are dictionary members (example : options). Fields suffixed with [] are lists (example : parcel_content).
| Name | Description |
|---|---|
| A dictionary object that contains additional information about the parcel. | |
delivery_to_imx. |
|
True, the function will return a PDF file (if available), or a file with asked format in options.label_formatTrue |
|
pdf, zpl_203, zpl_300. Default value : pdf |
|
| Data relevant for pickup | |
name, address1, address2, address3, postcode, town, country, phone, email. Setup may require an address_id as well. |
|
| Data relevant for parcelshop delivery | |
4. |
|
4 |
|
parcelshop_delivery.parcelshop_id if filled. To be implemented. |
|
| A dictionary object that contains additional description about the parcel. | |
| A dictionary object that contains additional informations about the addressee. | |
| A dictionary object that contains additional informations about the sender. | |
| A dictionary object that contains additional informations about the parcel's content. | |
Notices¶
-
IMX allows address data to be fairly long, but some carriers are much more restrictive. Please specify address fields as short as possible.
-
IMX requires only name and town for addresses, but most carriers need much more. Postcodes and at least one address line are mandatory in most countries.
-
The sender object is not mandatory.
-
The parcel_content object is a list. You may fill up with all differents items that are a parcel. Within European Union, the parcel_content object is not mandatory.
References for request object fields¶
options.service ¶
| Value | Description |
|---|---|
0 |
Pack Prio |
10 |
Pack Standard |
1 |
Pack Sign |
3 |
Pack Premium |
4 |
Pack Parcelshop |
5 |
Pack Easy |
11 |
Traced Return |
13 |
Premium Return |
14 |
Parcelshop Return |
options.entry_mode ¶
| Value | Description |
|---|---|
delivery_to_imx |
Parcels will be carried to IMX's hub or collected by IMX |
parcelshop_dropoff |
Parcels will be left in a parcelshop |
pickup |
Parcels will be collected by a carrier at some of your warehouses or shops. This option requires some setup and must be discussed with your sales representative |
options.carrier¶
In most cases, this field must be left blank.
options.cod_currency, options.insurance_currency, parcel_content[].currency¶
ISO 4216 codes listing is available at https://fr.wikipedia.org/wiki/ISO_4217
parcel_description.shipping_category ¶
| Valeur | Description |
|---|---|
0 |
Gift |
1 |
Sample |
2 |
Goods sales |
3 |
Document |
4 |
Goods return |
5 |
Others |
addressee.country and sender.country¶
ISO-3166-1 alpha2 codes listing is available at http://www.iso.org/iso/fr/french_country_names_and_code_elements The value “SP” is also allowed for delivery towards French military addresses.
parcel_content[].classification¶
The customs classification codes are available at http://ec.europa.eu/taxation_customs/customs/procedural_aspects/general/community_code/index_en.htm We currently don’t do any validation on this field.
Response description¶
| Field | Description |
|---|---|
| List of error data. Contains the following fields : | |
country, options.networks, addressee.postcode, etc. |
|
| List of warning data. Contains the following fields : | |
| List of tracking data. Contains the following fields : | |
Notices¶
-
Success is True if and only if errors is an empty list, but there may be some warnings.
-
If requested (options.label=True), the field label contains binary content of the PDF file. Pages dimension is 10cmx15cm. The file can contain multiple pages according to destination country and carrier. We provide a CN23 label for countries outside UE. The file content is base64-encoded and has to be decoded before to be saved on disk or printed.
-
Errors and warnings fields are lists of objects.
-
Infos is a string.
¶
Error messages¶
In case or errors, the errors field is a non-empty list of objects with the following properties :
· code: type of error. See values below ;
· message : message attempting to give an explicit description of the problem. Most of the time, it’s a message transmitted by the final carrier.
· field: field causing the error. In case the error is caused by a combination of fields, this data may not be available.
· value : value causing the error.
code field options¶
In live condition, most errors come from addresses not matching the final carrier’s specifications. To make debugging easier, we summarize those errors in five categories.
| Value | Description |
|---|---|
| INVALID | Invalid value. It may be caused by invalid data type (for instance, non-numerical value for weight field) or invalid data itself (postcode too long or too short). |
| MANDATORY | Blank value whereas the field is mandatory. |
| ROUTING_ERROR | Transmitted by final carrier. For instance, can be a postcode which is temporary not deserved because of snow falls. |
| TOO_LONG | Too long value. In most cases, the limitation comes from the final carrier. |
| UNKNOWN | Error to be classified. |
Address fields length¶
WS allows fields as long as 80 characters. However, most carriers have lower limits. It is safer to limit address fields to 32 characters.