La fonction “api.declare_shipment”

Cette fonction permet d'annoncer l'expédition d'un ensemble de colis vers le HUB IMX. Elle sert à contrôler la bonne réception et le traitement des colis. IMX construit et fournit quotidiennement à ses client un "rapport d'arrivage" en croisant les données d'expédition fournies par le client et les données internes de réception et de traitement.

Description de la requête

Cette fonction prend trois arguments en paramètre :

• username: fourni par IMX ;
• password: fourni par IMX ;
• data: dictionnaire de données contenant les données de votre requête.

L'objet data

Les champs notés en gras sont obligatoires. Les champs suffixés par un point sont des membres de dictionnaire (exemple : options). Les champs suffixés par [] sont des listes (exemple : parcel_content).

Nom	Description
account	char(40)Identifiant compte clientDans la plupart des cas, est égal au paramètre “username”.
shipment	Dictionnaire donnant des informations sur l'expédition. Contient le champ suivant :
.name	c(40)Nom unique du colisageHabituellement, le client horodate le nom pour en garantir l'unicité
imx_tracking_ids	[]Liste des références IMX concernées par l'expéditionLes références IMX sont fournies par la réponse de la fonction declare_parcel, dans le champ tracking_data.imx_tracking_id

Description de la réponse

Le retour de la fonction contient un objet result contenant les champs suivants :

Nom	Description
statut	char(40)ok ou failed selon la bonne exécution de la fonction
message	textSi statut est failed, descriptif de l'erreur
done	listListe des identifiants traités avec succès
invalid	listListe des identifiants invalides (non numériques, non liés au compte, en erreur, etc.)
already_handled	listListe des identifiants déjà associés à un colisageOn renvoie un objet contenant le nom et la timestamp de création du colisage associé au colis
warnings	listListe des avertissements

Exemple

import datetime
import requests

URL = "https://webservice.imxpostal.fr/smc/rpc/"
# Données d'identification fournies par IMX.
USERNAME = "..." # fourni par IMX
PASSWORD = "..." # fourni par IMX
ACCOUNT = "..." # fourni par IMX

data = {
    "jsonrpc": "2.0",
    "method": "api.declare_shipment",
    # identifiant de requête. A la convenance du client, pas nécessairement unique.
    "id": "__test__",
    "params": [
        USERNAME,
        PASSWORD,
        {
            "account": ACCOUNT,
            "imx_tracking_ids": [9408106, 9408065],
                "shipment": {
                    "name": "shipment-%s" % datetime.date.today(),
                }
        }

La première exécution du code suivant, lancée le 15 juin 2021, renvoie le résultat suivant :

{
    'jsonrpc': u'2.0',
    'id': '__test__',
    'result': {
        'status': 'ok',
        'done': [9409196, 9409195],
        'already_handled': {},
        'invalid': [],
        'warnings': None
    }
}

Une deuxième exécution, le même jour, renverrait :

{
    'jsonrpc': u'2.0',
    'id': '__test__',
    'result': {
        'status': 'ok',
        'already_handled': {
            '9409195': {
                'shipment_name': 'shipment-2021-06-15',
                'shipment_ts': '2021-06-15T19:48:51.413'
            },
            '9409196': {
                'shipment_name': 'shipment-2021-06-15',
                'shipment_ts': u'2021-06-15T19:48:51.413'
            }
        },
        'done': [],
        'invalid': [],
        'status': 'ok',
        'warnings': [
            'Nothing to do. All imx_tracking_ids are invalid or already handled.'
        ]
    }
}

Cross-docking

Pour les clients autorisés à faire du cross-docking, il faut rajouter un paramètre carrier à l'objet shipment. Les rapamètres sont donc les suivants :

Nom	Description
account	char(40)Identifiant compte clientDans la plupart des cas, est égal au paramètre “username”.
shipment	Dictionnaire donnant des informations sur l'expédition. Contient le champ suivant :
.name	c(40)Nom unique du colisageHabituellement, le client horodate le nom pour en garantir l'unicité
.carrier	c(40)Nom du distributeur finalFourni par IMX
imx_tracking_ids	[]Liste des références IMX concernées par l'expédition

La réponse est semblable au cas général, avec un champ additionnel label contenant le pdf 10x15 cm d'une étiquette à apposer sur le sac ou la palette, encodé en base64.

Exemple

data = {
    "jsonrpc": "2.0",
    "method": "api.declare_shipment",
    # identifiant de requête. A la convenance du client, pas nécessairement unique.
    "id": "__test__",
    "params": [
        USERNAME,
        PASSWORD,
        {
            "account": ACCOUNT,
            "imx_tracking_ids": [9408106, 9408065],
                "shipment": {
                    "name": "shipment-%s" % datetime.date.today(),
                    "carrier": "mrw",
                }
        }

La réponse au premier appel serait

{
    'jsonrpc': u'2.0',
    'id': '__test__',
    'result': {
        'status': 'ok',
        'done': [9409196, 9409195],
        'already_handled': {},
        'invalid': [],
        'warnings': None,
        "label": <base64-encoded pdf>
    }
}