The "api.declare_shipment" Function

This function allows the announcement of a set of packages to the IMX HUB. It serves to control the proper reception and processing of parcels. IMX builds and provides its clients with a daily "arrival report" by cross-referencing shipping data provided by the client with internal receipt and processing data.

Request Description

This function takes three parameters:

• username: provided by IMX;
• password: provided by IMX;
• data: a dictionary containing the data of your request.

The data Object

Fields marked in bold are mandatory. Fields suffixed with a period are dictionary members (e.g., options). Fields suffixed with [] are lists (e.g., parcel_content).

Name	Description
account	char(40): Customer account identifier. In most cases, it equals the "username" parameter.
shipment	Dictionary providing information about the shipment. Contains the following field:
.name	c(40): Unique package name. Typically, the client timestamps the name to ensure its uniqueness.
imx_tracking_ids	[]: List of IMX references concerned by the shipment. The IMX references are provided by the response of the declare_parcel function in the tracking_data.imx_tracking_id field.

Response Description

The function return contains a result object with the following fields:

Name	Description
status	char(40): ok or failed depending on the successful execution of the function
message	text: If status is failed, error description
done	list: List of identifiers processed successfully
invalid	list: List of invalid identifiers (non-numeric, not linked to the account, in error, etc.)
already_handled	list: List of identifiers already associated with a parcel. An object containing the name and creation timestamp of the parcel associated with the package is returned.
warnings	list: List of warnings

Example

import datetime
import requests

URL = "https://webservice.imxpostal.fr/smc/rpc/"
# Identification data provided by IMX.
USERNAME = "..." # provided by IMX
PASSWORD = "..." # provided by IMX
ACCOUNT = "..." # provided by IMX

data = {
    "jsonrpc": "2.0",
    "method": "api.declare_shipment",
    # request identifier. At the client's discretion, not necessarily unique.
    "id": "__test__",
    "params": [
        USERNAME,
        PASSWORD,
        {
            "account": ACCOUNT,
            "imx_tracking_ids": [9408106, 9408065],
                "shipment": {
                    "name": "shipment-%s" % datetime.date.today(),
                }
        }
    ]
}

The first execution of the following code, launched on June 15, 2021, returns the following result:

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

A second execution, the same day, would return:

{
    'jsonrpc': '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': '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

For clients authorized to do cross-docking, a carrier parameter must be added to the shipment object and a barcode can be added if the client wants to match its own barcodes. The parameters are therefore as follows:

Name	Description
account	char(40): Customer account identifier.
shipment	Dictionary providing information about the shipment. Contains the following field:
.name	c(40): Unique package name.
.carrier	c(40): Name of the final distributor. Provided by IMX.
.barcode	c(20), optional : Barcode to be printed on the label. If not provided, generated by IMX.
imx_tracking_ids	[]: List of IMX references concerned by the shipment.

The response is similar to the general case, with an additional label field containing a 10x15 cm pdf of a label to be affixed to the bag or pallet, encoded in base64.

Example

data = {
    "jsonrpc": "2.0",
    "method": "api.declare_shipment",
    # request identifier. At the client's discretion, not necessarily unique.
    "id": "__test__",
    "params": [
        USERNAME,
        PASSWORD,
        {
            "account": ACCOUNT,
            "imx_tracking_ids": [9408106, 9408065],
                "shipment": {
                    "name": "shipment-%s" % datetime.date.today(),
                    "carrier": "mrw",
                }
        }
    ]
}

The response to the first call would be:

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