Aller au contenu

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
version char(1)Version de l’APILa valeur par défaut est "1"
account char(40)Identifiant compte clientDans la plupart des cas, est égal au paramètre “username”.
business_unit c(40)Business unit
reference c(40)Référence clientVotre référence pour le colis. Chaque référence doit correspondre à un colis unique.
reference2 c(40)Seconde référence colis
comment c(400)Commentaire (libre)
sort_id c(6)Identifiant de tri
options Dictionnaire donnant des informations sur le colis. Contient les champs suivants :
.service c(1)Type de serviceVoir la liste des modalités
.entry_mode c(40)Point de départ de la livraison du colis. Voir la liste des modalités.Valeur par défaut : delivery_to_imx.
.cod_value n(10,2)Dans le cas d’un livraison contre remboursement, valeur du contre-remboursement. 2 décimales sont autorisées.Valeur par défaut : 0.
.cod_currency c(3)Monnaie du contre-remboursement, code ISO 4217. Valeur par défaut : "EUR".
.insurance_value n(10,2)Montant de l’extension d’indemnisation choisie (maximum 500€).Valeur par défaut : 0.
.insurance_currency c(3)Monnaie de l’indemnisation, code ISO 4217.Valeur par défaut : Non.
.pod booleanPositionner à “True” si une preuve de livraison est requise. Cela nécessite un service compatible (au moins égal à 1)Valeur par défaut : False.
.carrier c(20)Si renseigné, cela spécifie le transporteur final, indépendamment des règles d’affectations IMX. Certaines restrictions et autorisations sont à prendre en compte.
.carrier_tracking_id booleanSi “True”, la fonction retournera le numéro de suivi du transporteur final si celui-ci est disponible au moment de l’annonce.Valeur par défaut : False.
.label booleanSi True, la fonction retournera l’étiquette au format PDF (si disponible), ou au format indiqué dans options.label_format.Valeur par défaut : True
.label_format c(30)Format de l’étiquette. Les valeurs admises sont pdf et zpl_203, zpl_300 et certains déclinaisons de chaque dpi pour le zpl Voir la liste des modalités
.routing_option c(2)Option de routage.Option spécifique de routage, selon accord d'IMX
pickup Données de collecte
.network c(40)Réseau de distribution en charge de la collecte
.address dictAddresse de la collecte. Contient les mêmes champs que les autres adresses : name, address1, address2, address3, postcode, town, country, phone, email. Selon les réseaux, un identifiant address_id peut être exigé.
parcelshop_delivery Dictionnaire donnant les informations pour la livraison en relais Obligatoire si service 4.
.network c(30)Réseau de point relais (exemple: mondial_relay).
.parcelshop_id c(30)Identifiant du point relais.
.choice n(1,0)Si 1, IMX détermine le point relais en fonction de l’adresse du destinataire. Ignoré si parcelshop_delivery.parcelshop_id est renseigné. Non implémenté.
.choice_notification_by_imx n(1,0)Si 1, IMX envoie un mail au destinataire. Non implémenté.
parcel_description Dictionnaire décrivant le colis. Contient les champs suivants :
.weight n(10,3)Poids en kg.3 décimales sont autorisées.
.length n(5,0)Longueur en cm.Pas de décimale.
.height n(5,0)Hauteur en cm.Pas de décimale.
.width n(5,0)Largeur en cm.Pas de décimale.
.shipping_fees n(10,2)Frais de transport.
.shipping_fees_currency n(10,2)Monnaie des frais de transport, code ISO 4217.Valeur par défaut : "EUR".
.shipping_category c(1)Catégorie d’envoi.Valeur par défaut : '2' ("Vente de marchandises"). Voir la liste des modalités
.shipping_category_desc c(30)Description de la nature de l’envoi si shipping_category = '5' ("Autre").
.invoice_number c(30)N° de facture joint au colis.
.invoice base64Contenu binaire de la facture liée au contenu du colis. La facture doit être au format PDF, sa taille doit être inférieure à 1Mo. Le contenu doit être encodé en base64.
.id_sender c(30)Identifiant de l’expéditeur pour passage en douane.
addressee Dictionnaire donnant des informations sur le destinataire du colis. Contient les champs suivants :
.name c(80)Nom du destinataire.
.company c(80)Raison sociale du destinataire.
.address1 c(80)Adresse 1 du destinataire.
.address2 c(80)Adresse 2 du destinataire.
.address3 c(80)Adresse 3 du destinataire.
.postcode c(20)Code postal du destinataire
.town c(80)Ville du destinataire
.province c(80)Province, état, région du destinataire
.country c(2)Pays du destinataireClassification ISO 3166-1 alpha2
.email c(80)Email du destinataireFortement recommandé
.phone c(80)Numéro de téléphone du destinataireFortement recommandé.
sender Dictionnaire donnant des informations sur l'expediteur du colis. Contient les champs suivants :
.name c(80)Données de l’expéditeur.Mêmes champs que pour le destinataire, voir supra.
.company c(80)
.address1 c(80)
.address2 c(80)
.address3 c(80)
.postcode c(20)
.town c(80)
.province c(80)
.country c(2)
.email c(80)
.phone c(80)
parcel_content[] Liste de dictionnaires décrivant le contenu du colis à l'usage des douanes. Pour chaque item, on définit les champs suivants :
.description c(80)Description de l'item.
.classification c(20)Code classification douanière de l'item.Voir note infra..
.origine c(20)Pays d’origine de l'item.ISO 3166-1 alpha2.
.value n(10,2)Valeur unitaire de l'item. Le séparateur décimal est le point.Exemple: 10.02
.currency c(3)Monnaie de la déclaration de valeur de l'item.Code ISO 4217. Valeur par défaut : "EUR"
.amount n(10)Quantité d'items présent.Valeur par défaut : 1
.weight n(10,3)Poids unitaire de l'item, en kilos.
.prc_cov c(6)Pourcentage composés organiques volatils.Exemple : '12,24'
.reference c(80)Référence client de l'item.

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 et town pour l’adresse de destinataire, mais l’adresse doit être la plus complète possible, les champs postcode et address1 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 service sont les suivantes :

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 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 shipping_category sont les suivantes :

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
success booleanIndique si la requête s’est correctement déroulée
label binaryPDF pour l’étiquette demandée. Renvoie le contenu du fichier, encode en base64.
infos[] c(400)Messages d’information.Par exemple, deux appels successifs au WS pour une même référence client génère une information “référence déjà fournie”.
label_source c(20)Indique la source de l’étiquette (“imx” or transporteur).
errors Liste contenant les données des erreurs. Contient les champs suivants :
.field c(40)Nom du champ générant une erreur.Exemples : country, options.networks, addressee.postcode, etc.
.message c(400)Description de l’erreur.
.code c(20)Non renseigné.
Warnings Liste contenant les données des avertissements. Contient les champs suivants :
.field c(40)Nom du champ générant une alerte.
.message c(400)Description de l’alerte.
.code c(20)Vide. Non encore utilisé.
tracking_data Liste contenant les données de suivi du colis. Contient les champs suivants :
.imx_tracking_id n(20)Numéro de référence unique IMX pour le colis.
.imx_tracking_url c(100)URL de suivi IMX.
.carrier_tracking_id c(80) Numéro de suivi du distributeur finalSi demandé et disponible.
.scan_id c(100)Numéro de prise en charge.Si demandé.
.carrier_tracking_url c(200)URL de suivi du distributeur final.Si demandé et disponible.
.carrier_tracking_website c(100)Site web de suivi dans le cas où l’URL de suivi n’est pas disponible.Si demandé.
.carrier_name c(100)Nom du distributeur choisi.

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 et warnings 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 champ code

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.

Exemples

Python

Exemple basique

Exemple d'erreur

Exemple international

PHP

Exemple basique