La fonction “api.declare_parcel”¶
Cette fonction permet :
- l’annonce d’un colis ;
- l’obtention d’un numéro et d’une url de suivi du distributeur final ;
- l’obtention d’une étiquette de taille 10cmx15 cm au format PDF ou ZPL, pour impression sur les imprimantes Tochiba TEC ou Zebra.
Description de la requête¶
Cette fonction prend trois arguments en paramètre :
username
: donné par IMX ;password
: donné par IMX ;data
: dictionnaire de données contenant les données de votre requête.
L'objet data
¶
Les champs noté en gras sont obligatoires. Les champs suffixés par un point sont des membres de dictionnaires (exemple : options
). Les champs suffixés par [] sont des listes (exemple : parcel_content
).
Nom | Description |
---|---|
Dictionnaire donnant des informations sur le colis. Contient les champs suivants : | |
delivery_to_imx . |
|
True , la fonction retournera l’étiquette au format PDF (si disponible), ou au format indiqué dans options.label_format .True |
|
pdf et zpl_203 , zpl_300 et certains déclinaisons de chaque dpi pour le zpl Voir la liste des modalités |
|
Données de collecte | |
name , address1 , address2 , address3 , postcode , town , country , phone , email . Selon les réseaux, un identifiant address_id peut être exigé. |
|
Dictionnaire donnant les informations pour la livraison en relais |
|
parcelshop_delivery.parcelshop_id est renseigné. Non implémenté. |
|
Dictionnaire décrivant le colis. Contient les champs suivants : | |
Dictionnaire donnant des informations sur le destinataire du colis. Contient les champs suivants : | |
Dictionnaire donnant des informations sur l'expediteur du colis. Contient les champs suivants : | |
Liste de dictionnaires décrivant le contenu du colis à l'usage des douanes. Pour chaque item, on définit les champs suivants : | |
Remarques¶
- IMX autorise des champs d’adresse assez long, mais certains distributeurs sont plus restrictifs. Spécifier les champs adresses au plus juste pour éviter tout problème ;
- IMX impose seulement la présence des champs
name
ettown
pour l’adresse de destinataire, mais l’adresse doit être la plus complète possible, les champspostcode
etaddress1
sont généralement nécessaire. Certains distributeurs exigent également un email et/ou un téléphone du destinataire. - Les données de l’expéditeur ne sont pas obligatoires ;
- L’objet parcel_content est une liste contenant tous les différents articles d'un colis. Il doit être renseigné avec au moins un éléments pour les destinations hors UE.
Champs à modalités fixes¶
options.service ¶
Les modalités du champ
Valeur | Description |
---|---|
0 |
Pack Prio |
10 |
Pack Standard |
1 |
Pack Sign |
3 |
Pack Premium |
4 |
Pack Relais |
5 |
Pack Easy |
11 |
Retour Suivi |
13 |
Retour Premium |
14 |
Retour Relais |
options.entry_mode ¶
Valeur | Description |
---|---|
delivery_to_imx |
Colis est déposé au hub d'IMX ou collecté par IMX |
parcelshop_dropoff |
Colis est laissé dans un relais |
pickup |
Colis récupéré chez vous (entrepôt, boutique) par le distributeur. Cette solution doit être paramétrée, veuillez contacter notre service commercial. |
options.carrier¶
Dans la majorité des cas, ce champ doit être laissé à blanc. Des modalités sont disponibles sur demande, en fonction du paramétrage de votre compte client.
options.cod_currency, options.insurance_currency, parcel_content[].currency¶
La liste des codes ISO 4216 est disponible sur https://fr.wikipedia.org/wiki/ISO_4217
options.label_format ¶
Un certain nombre d'options sont disponibles pour le zpl, afin de pouvoir s'adapter aux différentes configurations pouvant être rencontrées chez le client.
Valeur | Description |
---|---|
pdf |
|
zpl_203 |
ZPL pour imprimante 203 dpi |
zpl_203_no_markup |
ZPL 203 dpi sans wrapper XML (pour impression monopage) |
zpl_203_no_markup_no_mmc |
ZPL 203 dpi sans instruction MMC |
zpl_203_v2 |
ZPL 203 dpi alternatif |
zpl_300 |
ZPL pour imprimante 300 dpi |
zpl_300_no_markup |
ZPL 300 dpi sans wrapper XML (pour impression monopage) |
zpl_300_no_markup_no_mmc |
ZPL 300 dpi sans instruction MMC |
zpl_300_v2 |
ZPL 300 dpi alternatif |
parcel_description.shipping_category ¶
Les modalités du champ
Valeur | Description |
---|---|
0 |
Cadeau |
1 |
Echantillon |
2 |
Vente de marchandises |
3 |
Document |
4 |
Retour de marchandises |
5 |
Autre |
addressee.country et sender.country¶
La liste des codes ISO-3166-1 alpha2 est disponible sur http://www.iso.org/iso/fr/french_country_names_and_code_elements Le code “SP” est également autorisé pour les expéditions vers les adresses ARMEES.
parcel_content[].classification ¶
Les codes de classifications douanières sont disponibles sur http://ec.europa.eu/taxation_customs/customs/procedural_aspects/general/community_code/index_en.htm Il n’y a pas actuellement de validation par le Web Service de la validité des codes de classification douanière.
Description de la réponse¶
Champs | Description |
---|---|
Liste contenant les données des erreurs. Contient les champs suivants : | |
country , options.networks , addressee.postcode , etc. |
|
Liste contenant les données des avertissements. Contient les champs suivants : | |
Liste contenant les données de suivi du colis. Contient les champs suivants : | |
Remarques¶
- Le champ
success
contient la valeur True si et seulement si la liste Errors est vide, mais il peut y avoir des alertes (warnings) ; - Si l’étiquette a été demandée (options.label=True dans la requête objet), le champ
label
contient le contenu binaire du fichier PDF. La dimension des pages est 10cm par 15cm et peut contenir plusieurs pages selon le pays de destination et le distributeur. Nous fournissons une étiquette CN23 pour les colis à destination d’un pays hors Union Européenne. Le contenu du fichier est encodé en base64 et doit être décodé avant enregistrement sur disque local ou impression. - Les champs
errors
etwarnings
sont des listes d’objet (cf. infra).infos
est une liste de chaînes de caractères.
Messages d’erreurs¶
En cas d’erreurs, le champ errors
de la réponse est une liste non vide d’objets possédant les champs suivants :
code
: typologie d’erreurs; Voir les modalités infra ;message
: message tentant de rendre l’erreur plus explicite. Il s’agit le plus souvent d’un message d’erreur transmis par le distributeur final.field
: champ responsable de l’erreur. Dans le cas où l’erreur provient d’une combinaison de champs, cette donnée peut ne pas être renseigné ;value
: valeur responsable de l’erreur. Modalités du champcode
En production, la majorité des erreurs proviennent d’adresses ne respectant pas les normes du distributeur final. A des fins de simplification, le Web Service synthétise ces erreurs en cinq grand types d’exception.
Valeur | Description |
---|---|
INVALID | Valeur invalide. L’invalidité peut concerner le type de données (champs poids non-numérique) ou la donnée elle-même (code postal trop long ou trop court) |
MANDATORY | Valeur non-renseignée alors que le champ est obligatoire. Un champ peut être facultatif pour le Web Service mais obligatoire pour le distributeur final |
ROUTING_ERROR | Erreur de routage transmise par le distributeur final. Peut par exemple concerner un code postal temporairement non desservi pour raison de chutes de neige |
TOO_LONG | Valeur trop longue. Pour les champs d’adresse, il s’agit souvent d’une limitation provenant du distributeur ; |
UNKNOWN | Erreur inconnue ou pas encore classifiée |
Longueur des champs d’adresse¶
Le Web Service accepte des champs de longueur 80. Néanmoins, la plupart des distributeurs ont des limites beaucoup plus basses. Il est prudent de se limiter à des champs de longueur 32.