Chrono-API

Version: 1.0.1

Affranchissez rapidement et facilement tous vos colis Chronopost.

Introduction

Chrono-API est une plateforme d'édition d'étiquettes Chronopost automatiquement.
Il est possible pour un développeur de :

Notre API est une API Rest JSON. Tous les appels sont en JSON c'est pourquoi vos requêtes HTTP doivent spécifier l'attribut "Content-type: application/json".

Prérequis

Votre client doit créér un compte sur www.chrono-api.fr nécessitant:

Comment ça fonctionne ?

Le client doit créer un compte Chrono-API sur www.chrono-api.fr au préalable. Il obtiendra alors une clé API vous permettant de faire la majorité des appels au WebService. En effet, il n'est pas possible de modifier l'email du client par exemple, sans s'être authentifié au préalable. Pour s'identifier, vous avez besoin de l'email et du mot de passe du client. Le WebService vous donnera un token appelé sessionId qui vous permettra de réaliser les appels plus risqués.

Le coeur de l'API est la génération d'étiquettes d'envoi Chronopost. Une redirection vers www.chrono-api.fr est nénécessaire afin de terminer l'affranchissement. Vous devrez donc rediriger le client vers une page dédiée afin de terminer l'affranchissement.
Les étapes pour générer les étiquettes:

Terminologie

Pour notre API, lorsque l'on parle d'un ID, il s'agit toujours de l'identifiant de la donnée (au sens base de données). Par exemple, la propriété "taskId" signifie qu'il s'agit de l'identifiant de la donnée "Task". Les identifiants de données sont toujours des entiers.
Info: Pour une tâche (Task), il y a deux valeurs permettant l'identification, la référence et l'id. Veillez à bien utiliser le bon identifiant.

Accès au WebService et authentification

Voici l'url d'appel au WebService: https://ws.chrono-api.fr/services
Certains appels nécessitent la clé API, vous verrez alors dans les URLs le paramètre {api_key}. La clé API s'obtient dans la tableau de bord du compte du client sur www.chrono-api.fr. Attention: Les appels ne fonctionneront pas si la clé API n'est pas active. Pour qu'elle soit active, il faut que le client ait rempli les conditions de Chrono-API.fr.

Certains appels nécessitent une authentification forte à l'aide de l'adresse email et du mot de passe du client. Vous verrez alors dans les URLs le paramètre {session_id}. En effet, vous devez récupérer cet identifiant de session en vous authentifiant au travers du WebService. Attention: L'identifiant n'est valide que 30 minutes. Passé ce délai, vous serez bloqué par un code 403. Dans ce cas, soit vous vous réauthentifiez, soit vous rafraichissez la durée de validité de l'identifiant avant les 30 minutes. (toutes les 15 minutes par exemple).

Pour rediriger vers la page de l'affranchissement, voici l'url à compléter: https://www.chrono-api.fr/admin/admin.html#/mes_affranchissements/{reference_task} ou il faut remplacer {reference_task} par la référence de la tâche retourné lors de la création de la tâche.

Faire des tests durant le développement

Vous devez vous créér un compte sur www.chrono-api.fr. Vous devez le rendre actif. Il est préférable que votre client s'en occupe afin de se familiariser avec l'interface de Chrono-API.fr et pour qu'il puisse procéder au renseignement des données de paiement.
Une fois l'api active (instantané). Vous pourrez récupérer la clé API du tableau de bord.

ATTENTION: Lorsque vous faites des tests pour affranchir des étiquettes, vous testerez la redirection vers le site pour terminer l'affranchissement.

Le passage au paiement n'est pas fictif. Ne dépassez pas l'étape du calcul du prix.

J'ai dépassé l'étape du paiement et j'ai généré des étiquettes alors que je n'aurai pas dû. Pas de panique, il vous ait possible d'annuler les envois en vous rendant sur Chronopost.fr dans le menu Historique de mes envois. Une croix rouge vous permettra d'annuler les étiquettes.

Une configuration automatique ?

Lors d'un affranchissement, il est demandé au client de renseigner certains champs comme le type d'envoi (chrono-express / chrono-classic...) avant de pouvoir générer les étiquettes. Il est possible d'appliquer en prévention un ensemble de valeurs par défaut, évitant de saisir la même valeur des 10 ènes de fois.

Un menu sur Chrono-API.fr permet au client de saisir ces configurations et d'en définir une par défaut.
En effet, il est possible d'avoir plusieurs configurations, que l'on peut appliquer aux colis d'une tâche d'affranchissement via un bouton. On peut définir une configuration par défaut, dans ce cas la configuration est appliquée automatiquement sans action de l'utilisateur.
Une configuration appliquée est l'équivalent de faire remplir les champs des colis par un robot. La modification avant validation est toujours possible.

Comportements automatiques

Lors de l'affranchissement, vous pouvez spécifier une liste de produits incrutés sur l'étiquette (IncrustedProducts). Un calcul automatique du poids de la commande est réalisé par la somme des poids des produits spécifiés excepté si vous assignez la propriété "weight" de l'objet TaskParcel. (l'objet parent à la liste d'IncrustedProduct). Dans ce cas, la propriété prend le dessus.
Info: Vous pouvez spécifier une liste de produits à incruster en mettant le booléen "displayOnLabel" à "false" afin de ne pas les écrire sur l'étiquette mais de réaliser tout de même le calcul automatique du poids.

Les webhooks

Un webhook est une URL qui sera appelé par les serveurs de Chrono-API afin de vous notifier d'un évènement.
Sur Chrono-API, les appels sont uniquement HTTP au travers de la méthode POST. Pour chaque hook, des informations sont envoyées en JSON directement dans le corps de la requête.
Si jamais votre serveur n'est pas joignable, les serveurs de Chrono-API rééssairont 5 fois toutes les 30 secondes. Si aucun appel ne réussi, nos serveurs abandonneront.

List des Webhooks:

Action Ressource(s) Description Paramètres envoyés par Chrono-API
CALLBACK_ONFINISHED CreateTask Cette action est réalisée lorsqu'une tâche est terminée et que les étiquettes sont prêtes.
taskId Identifiant (id) de la tâche concernée
taskReference Référence (reference) de la tâche.
downloadPdfUrl URL directe de téléchargement du fichier PDF.
downloadFullpagePdfUrl URL directe de téléchargement du fichier PDF pleine page.


Voici un exemple de requête envoyée par Chrono-API pour l'action 'CALLBACK_ONFINISHED':
{
"taskId": "128",
"taskReference": "sfd564s96df45s9d48fs65d4f6s5df",
"downloadPdfUrl": "https://ws.chrono-api.fr/services/task/XXXX/getPdf/XXXX,
"downloadFullpagePdfUrl": "https://ws.chrono-api.fr/services/task/XXXX/getPdf/XXXX
}

Exemples de code

Création d'une tâche en JQuery/AJAX

            var exempleRequest = {
        "webhooks":
        [
            {
                "action": "CALLBACK_ONFINISHED",
                "callbackUrl": "http://test.fr"
            }
        ],
        "parcels": [
            {
                "weight": "0.5",
                "data": {
                    "country": "FR",
                    "countryName": "FRANCE",
                    "socialReason": "",
                    "lastName": "Doe",
                    "firstName": "Joe",
                    "address": "145 All test",
                    "moreAddress": "",
                    "doorCode": "",
                    "zipCode": "59160",
                    "city": "Lomme",
                    "state": "",
                    "phoneNumber": "0611111111",
                    "email": "test@email.com",
                    "referenceAddress": ""
                },
                "customToken": 548745,
                "products": [
                    {
                        "reference": "port_acer",
                        "name": "Pc portable acer",
                        "quantity": 1,
                        "displayOnLabel": true
                    }
                ]
            }
        ]
    };
    $.ajax({
        url: 'https://ws.chrono-api.fr/services/task/{YOUR_API_KEY}/create',
        type: 'POST',
        data: JSON.stringify(exempleRequest), // It's important to stringify the data sent because natively jQuery send the data encoded ! Our servers need raw JSON.
        contentType: 'application/json',
        success: function(data) {
            var mytaskReference = data.response;
            // Do what you want with the task reference
        },
        error: function(jqXHR, textStatus, errorThrown)
        {
            var httpResponseStatusCode = jqXHR.status;

            if (httpResponseStatusCode == 400) {
                // You did a bad request (didn't respected a data format)
            }
            else if (httpResponseStatusCode == 402) {
                // Your API Key is in a disabled state
            }
            else if (httpResponseStatusCode == 403) {
                // You have a disabled API KEY or you are not allowed to create a task
            }
            else if (httpResponseStatusCode == 405 || httpResponseStatusCode == 406) {
                // You must wait a couple of minutes before doing another task creation call because you reach the maximum number of labels generated for now. (DOC: #/{api_key}/contraints/info)
            }
            else if (httpResponseStatusCode == 407) {
                // Another task is already running, you must either cancel it or finish it.
                var workingTaskIReference = jqXHR.responseText;
            }
            else {
                // You probably sent an invalid json string to the server.
                alert('Une erreur est survenue');
            }
        }
    });
        

Schemes:

Summary

Tag: Task service

Operation Description
POST /parcel_config_presets/{session_id}/create

Create a new parcel configuration preset.

GET /parcel_config_presets/{session_id}/list

Retrieve the list of the parcel config presets for the sessionId user.

POST /parcel_config_presets/{session_id}/{preset_id}/default/set

Update parcel preset is defaut or not.

POST /parcel_config_presets/{session_id}/{preset_id}/delete

Delete the specified parcel configuration preset.

POST /parcel_config_presets/{session_id}/{preset_id}/update

Update the specified parcel configuration preset.

GET /task/required/fields/labels

Retrieve the list of static labels associated with required fields.

GET /task/{session_id}/task/{task_id}/parcels/list

Retrieve the list of tasks parcels which are owned by the sessionId user (except if you are administrator).

POST /task/{api_key}/create

Create a new task.

GET /task/{api_key}/getPdf/{signature}

Download the specified PDF file according to its signature.

GET /task/{api_key}/tasks/parcels/not_notified/list

Retrieve the list of tasks parcels not notified for the sessionId user.

POST /task/{api_key}/tasks/parcels/set/to/notified

Update the task parcels to set it to notified state for the apiKey user.

GET /task/{api_key}/{task_reference_or_id}/get

Retrieve the specified task if you are the owner.

GET /task/{session_id}/tasks/last/{nbr_tasks}/list

Retrieve the list of {nbr_task} last tasks in the database including working tasks.

GET /task/{session_id}/tasks/list

Retrieve the list of tasks for the sessionId user.

GET /task/{session_id}/{task_reference_or_id}/cancel

Try to cancel the task.

Tag: Postage service

Operation Description
GET /postage/chronopost/{api_key}/checkApiKey

Check API KEY

GET /postage/chronopost/{api_key}/constraints/info

Returns the constraints info like maximum number of parcels which can be send to edit labels or the minimum delay between each call for editing labels...

GET /postage/chronopost/{api_key}/parcel/tracking/infos/{lang}/{parcel_ref}

Retrieve parcel (from its 'reference number') tracking information on Chronopost.fr.

GET /postage/chronopost/{api_key}/time/remaining/before/being/able/to/edit/labels

Returns time remaining before being able to edit labels again. If the value is positive and you make a call, the webservice will block you.

Tag: Prestashop Modules

Operation Description
GET /module/broadcast/message

Get broadcast message if any..

GET /module/{module_id}/download

Download a prestashop module.

GET /module/{prestashop_version_id}/last/module

Returns the last module available.

GET /module/{prestashop_version_id}/last/module/download

Download the last prestashop module version according to the prestashop version.

GET /module/{session_id}/list

List the modules.

GET /module/{session_id}/prestashop_version/list

List Prestashop versions

Tag: Users

Operation Description
POST /user/auth

Authenticate on API

POST /user/auth/refresh

Resfresh session id on API

GET /user/{session_id}/address/list

Retrieve list of addresses for the specified users.

GET /user/{session_id}/api/get

Get user api informations.

POST /user/{session_id}/disconnect

Destroy the specified session.

POST /user/{session_id}/email/update

Update the connected user email.

GET /user/{session_id}/get

Get user connected informations.

POST /user/{session_id}/option/set

Set a user option.

POST /user/{session_id}/password/update

Update the connected user password.

GET /user/{session_id}/posted/parcels/list

Returns the list of parcels posted (including canceled parcels). By default, the current month is returned.

POST /user/{session_id}/update/chronopost/identifiers

Update chronopost identifiers after testing them on Chronopost.fr.

Tag: Business

Operation Description
GET /business/{session_id}/bill/list

List user bills.

GET /business/{session_id}/bill/list/filter/by/not_paid

List user bills which are not paid.

GET /business/{session_id}/bill/{bill_id}/download

Download a bill PDF file.

Tag: Public API

Operation Description
POST /public/api/get/points/relais

Get points relais list

Paths

List user bills.

GET /business/{session_id}/bill/list

Tags: Business

Returns list of bills on success.

application/json

session_id

Session identifier retrieved during authentication.

path string

application/json

200 OK

successful operation

403 Forbidden

Forbidden access. Session is not valid.

500 Internal Server Error

Unable to list specified user bills due to server side error.

List user bills which are not paid.

GET /business/{session_id}/bill/list/filter/by/not_paid

Tags: Business

Returns list of bills on success.

application/json

session_id

Session identifier retrieved during authentication.

path string

application/json

200 OK

successful operation

403 Forbidden

Forbidden access. Session is not valid.

500 Internal Server Error

Unable to list specified user not paid bills due to server side error.

Download a bill PDF file.

GET /business/{session_id}/bill/{bill_id}/download

Tags: Business

Returns the .pdf bill file on success.

application/json

bill_id

The bill identifier.

path integer (int32)
session_id

Session identifier retrieved during authentication.

path string

application/pdf

403 Forbidden

Forbidden access. Session is not valid or you are not the bill owner.

404 Not Found

Bill not found.

500 Internal Server Error

Unable to download the bill due to server side error.

Get broadcast message if any..

GET /module/broadcast/message

Tags: Prestashop Modules

Returns message if any..

application/json

application/json

200 OK

successful operation

403 Forbidden

Forbidden access. Session is not valid.

500 Internal Server Error

Unable to get message due to server side error.

Download a prestashop module.

GET /module/{module_id}/download

Tags: Prestashop Modules

Returns the .zip module file on success.

application/json

module_id

The module identifier.

path integer (int32)

application/zip

403 Forbidden

Forbidden access. Session is not valid.

404 Not Found

Module version not found.

500 Internal Server Error

Unable to download the module due to server side error.

Returns the last module available.

GET /module/{prestashop_version_id}/last/module

Tags: Prestashop Modules

Returns last module (or 404 when no module available) on success.

application/json

prestashop_version_id

The prestashop version identifier.

path integer (int32)

application/json

200 OK

successful operation

403 Forbidden

Forbidden access. Session is not valid or you are not an administrator.

404 Not Found

No new module version available.

500 Internal Server Error

Unable to compare the specified version to the server version due to server side error.

Download the last prestashop module version according to the prestashop version.

GET /module/{prestashop_version_id}/last/module/download

Tags: Prestashop Modules

Returns the .zip module file on success.

application/json

prestashop_version_id

The prestashop version identifier.

path integer (int32)

application/zip

404 Not Found

Module version not found.

500 Internal Server Error

Unable to download the module due to server side error.

List the modules.

GET /module/{session_id}/list

Tags: Prestashop Modules

Returns list of modules on success.

application/json

session_id

Session identifier retrieved during authentication.

path string

application/json

200 OK

successful operation

403 Forbidden

Forbidden access. Session is not valid.

500 Internal Server Error

Unable to list the modules due to server side error.

List Prestashop versions

GET /module/{session_id}/prestashop_version/list

Tags: Prestashop Modules

Returns list of prestashop versions on success.

application/json

session_id

Session identifier retrieved during authentication.

path string

application/json

200 OK

successful operation

403 Forbidden

Forbidden access. Session is not valid.

500 Internal Server Error

Unable to retrieve list of the Prestashop versions due to server side error.

Create a new parcel configuration preset.

POST /parcel_config_presets/{session_id}/create

Tags: Task service

Returns nothing.

application/json

session_id

Session identifier.

path string

application/json

400 Bad Request

Invalid parameter.

403 Forbidden

Forbidden access. SessionId is not valid.

405 Method Not Allowed

A preset with this name already exists.

500 Internal Server Error

Unable to create the parcel configuration preset due to server side error.

Retrieve the list of the parcel config presets for the sessionId user.

GET /parcel_config_presets/{session_id}/list

Tags: Task service

Returns list of parcel config presets.

application/json

session_id

Session identifier retrieved during authentication.

path string

application/json

200 OK

successful operation

403 Forbidden

Forbidden access. SessionId is not valid or you are not authorized.

500 Internal Server Error

Unable to retrieve the list of parcel config presets due to server side error.

Update parcel preset is defaut or not.

POST /parcel_config_presets/{session_id}/{preset_id}/default/set

Tags: Task service

Returns nothing.

application/json

The body contains 'true' or 'false' string.

preset_id

Preset db identifier.

path integer (int32)
session_id

Session identifier.

path string

application/json

403 Forbidden

Forbidden access. SessionId is not valid.

500 Internal Server Error

Unable to update the parcel configuration preset default state due to server side error.

Delete the specified parcel configuration preset.

POST /parcel_config_presets/{session_id}/{preset_id}/delete

Tags: Task service

Returns nothing.

application/json

preset_id

Preset db identifier.

path integer (int32)
session_id

Session identifier.

path string

application/json

403 Forbidden

Forbidden access. SessionId is not valid or you are not allowed to delete this preset.

404 Not Found

The preset does not exists in our database.

500 Internal Server Error

Unable to delete the parcel configuration preset due to server side error.

Update the specified parcel configuration preset.

POST /parcel_config_presets/{session_id}/{preset_id}/update

Tags: Task service

Returns nothing.

application/json

preset_id

Preset db identifier.

path integer (int32)
session_id

Session identifier.

path string

application/json

400 Bad Request

Invalid parameter.

403 Forbidden

Forbidden access. SessionId is not valid or you are not allowed to update this preset.

404 Not Found

The preset does not exists in our database.

405 Method Not Allowed

Another preset with this name already exists.

500 Internal Server Error

Unable to create the parcel configuration preset due to server side error.

Check API KEY

GET /postage/chronopost/{api_key}/checkApiKey

Tags: Postage service

Returns nothing on success.

application/json

api_key

API key.

path string

application/json

402 Payment Required

API Key is in a disabled state.

403 Forbidden

Forbidden access. ApiKey is not valid.

500 Internal Server Error

Unable to check api key due to server side error.

Returns the constraints info like maximum number of parcels which can be send to edit labels or the minimum delay between each call for editing labels...

GET /postage/chronopost/{api_key}/constraints/info

Tags: Postage service

Returns contraints info.

application/json

parcels_count path integer (int32)
api_key

API key.

path string

application/json

200 OK

successful operation

402 Payment Required

API Key is in a disabled state.

403 Forbidden

Forbidden access. ApiKey is not valid.

500 Internal Server Error

Unable to retrieve constraints info due to server side error.

Retrieve parcel (from its 'reference number') tracking information on Chronopost.fr.

GET /postage/chronopost/{api_key}/parcel/tracking/infos/{lang}/{parcel_ref}

Tags: Postage service

Returns the tracking events for the specified parcel.

application/json

lang

Tracking events language (EN|FR).

path string , x ∈ { FR , EN }
parcel_ref

Chronopost parcel reference.

path string
api_key

API key.

path string

application/json

200 OK

successful operation

402 Payment Required

API Key is in adisabled access. ApiKey is not valid.

404 Not Found

No tracking information availabled.

500 Internal Server Error

Unable to retrieve specified parcel information due to server side error.

Returns time remaining before being able to edit labels again. If the value is positive and you make a call, the webservice will block you.

GET /postage/chronopost/{api_key}/time/remaining/before/being/able/to/edit/labels

Tags: Postage service

application/json

api_key

API key.

path string

application/json

200 OK

successful operation

402 Payment Required

API Key is in a disabled state.

403 Forbidden

Forbidden access. ApiKey is not valid.

500 Internal Server Error

Unable to retrieve time remaining due to server side error.

Get points relais list

POST /public/api/get/points/relais

Tags: Public API

Returns the list of pointRelais available around the specified area.

application/json

application/json

200 OK

successful operation

400 Bad Request

Request contains invalid inputs.

Retrieve the list of static labels associated with required fields.

GET /task/required/fields/labels

Tags: Task service

Returns the list of static labels.

application/json

application/json

200 OK

successful operation

403 Forbidden

Forbidden access. SessionId is not valid or you are not authorized.

500 Internal Server Error

Unable to retrieve the required fields labels due to server side error.

Create a new task.

POST /task/{api_key}/create

Tags: Task service

Returns the task reference on success.

application/json

api_key

API key.

path string

application/json

400 Bad Request

Invalid parameter.

401 Unauthorized

Invalid identifiers.

402 Payment Required

API Key is in a disabled state.

403 Forbidden

Forbidden access. ApiKey is not valid.

405 Method Not Allowed

You must wait several minutes before doing another call to edit labels (the number of minutes is available at #/{api_key}/contraints/info).

406 Not Acceptable

The number of parcels specified is reaching the maximum limit. (the number of maximum parcels is available at #/{api_key}/contraints/info)

407 Proxy Authentication Required

Another task is already working. Return the working task reference (not formatted in json, just the reference).

500 Internal Server Error

Unable to retrieve required fields due to server side error.

Download the specified PDF file according to its signature.

GET /task/{api_key}/getPdf/{signature}

Tags: Task service

Returns a PDF file.

text/plain

signature

PDF File signatured you retrieved from generated PDF resource call.

path string
api_key

API key.

path string

application/octet-stream

200 OK

successful operation

402 Payment Required

API Key is in a disabled state.

403 Forbidden

Forbidden access. ApiKey is not valid.

404 Not Found

Generated PDF signature not found.

500 Internal Server Error

Unable to download PDF due to server side error.

Retrieve the list of tasks parcels not notified for the sessionId user.

GET /task/{api_key}/tasks/parcels/not_notified/list

Tags: Task service

Returns list of tasks parcels.

application/json

api_key

API key.

path string

application/json

200 OK

successful operation

402 Payment Required

API Key is in a disabled state.

403 Forbidden

Forbidden access. ApiKey is not valid or you are not authorized.

500 Internal Server Error

Unable to retrieve the list of tasks parcels due to server side error.

Update the task parcels to set it to notified state for the apiKey user.

POST /task/{api_key}/tasks/parcels/set/to/notified

Tags: Task service

Returns nothing.

application/json

integer (int32)
api_key

API key.

path string

application/json

402 Payment Required

API Key is in a disabled state.

403 Forbidden

Forbidden access. ApiKey is not valid or you are not authorized.

500 Internal Server Error

Unable to update task parcels to notified state due to server side error.

Retrieve the specified task if you are the owner.

GET /task/{api_key}/{task_reference_or_id}/get

Tags: Task service

Returns the task.

application/json

api_key

API key.

path string
task_reference_or_id

Task identifier or reference.

path integer (int32)

application/json

200 OK

successful operation

403 Forbidden

Forbidden access. ApiKey is not valid or you are not authorized.

404 Not Found

Specified task is not found.

500 Internal Server Error

Unable to retrieve the specified task due to server side error.

Retrieve the list of tasks parcels which are owned by the sessionId user (except if you are administrator).

GET /task/{session_id}/task/{task_id}/parcels/list

Tags: Task service

Returns list of task parcels.

application/json

session_id

Session identifier retrieved during authentication.

path string
task_id

Task db identifier.

path integer (int32)
pagOffset query integer (int64)
pagNbrEntries query integer (int64)
sortBy query string , x ∈ { ID , CREATION_DATE , HT_AMOUNT , STATE }
sortAscending query boolean
searchBy query string[] , multiple parameters (searchBy=aaa&searchBy=bbb)
searchKeywords query string[] , multiple parameters (searchKeywords=aaa&searchKeywords=bbb)

application/json

200 OK

successful operation

400 Bad Request

Pagination inputs are not valid.

403 Forbidden

Forbidden access. SessionId is not valid or you are not authorized.

500 Internal Server Error

Unable to retrieve the list of task parcels due to server side error.

Retrieve the list of {nbr_task} last tasks in the database including working tasks.

GET /task/{session_id}/tasks/last/{nbr_tasks}/list

Tags: Task service

Returns list of tasks.

application/json

session_id

Session identifier retrieved during authentication.

path string
nbr_tasks

Maximum number of tasks returned.

path integer (int64)

application/json

200 OK

successful operation

403 Forbidden

Forbidden access. SessionId is not valid or you are not authorized.

500 Internal Server Error

Unable to retrieve the list of tasks due to server side error.

Retrieve the list of tasks for the sessionId user.

GET /task/{session_id}/tasks/list

Tags: Task service

Returns list of tasks.

application/json

session_id

Session identifier retrieved during authentication.

path string

application/json

200 OK

successful operation

403 Forbidden

Forbidden access. SessionId is not valid or you are not authorized.

500 Internal Server Error

Unable to retrieve the list of tasks due to server side error.

Try to cancel the task.

GET /task/{session_id}/{task_reference_or_id}/cancel

Tags: Task service

application/json

task_reference_or_id

Task identifier or reference.

path integer (int32)
session_id

Session identifier retrieved during authentication.

path string

application/json

403 Forbidden

Forbidden access. SessionId is not valid or you are not authorized to cancel the task beacause of its status.

404 Not Found

Specified task is not found.

500 Internal Server Error

Unable to cancel the task due to server side error.

Authenticate on API

POST /user/auth

Tags: Users

Returns a string corresponding to a SessionID, needed to use API resources.

application/json

application/json

200 OK

successful operation

400 Bad Request

Request contains invalid inputs.

403 Forbidden

Email/Password does not match.

Resfresh session id on API

POST /user/auth/refresh

Tags: Users

Returns nothing on success.

application/json

Session identifier retrieved during authentication.

application/json

200 OK

successful operation

400 Bad Request

Invalid session identifier specified or the session has expired.

Retrieve list of addresses for the specified users.

GET /user/{session_id}/address/list

Tags: Users

Returns list of addresses.

application/json

session_id

Session identifier retrieved during authentication.

path string

application/json

200 OK
500 Internal Server Error

Unable to list the addresses due to server side error.

Get user api informations.

GET /user/{session_id}/api/get

Tags: Users

Returns user api information on success.

application/json

session_id

Session identifier retrieved during authentication.

path string

application/json

200 OK

successful operation

403 Forbidden

Forbidden access. Session is not valid.

500 Internal Server Error

Unable to get user api information due to server side error.

Destroy the specified session.

POST /user/{session_id}/disconnect

Tags: Users

Returns nothing. Always returns 200.

application/json

session_id

Session identifier retrieved during authentication.

path string

application/json

default

successful operation

Update the connected user email.

POST /user/{session_id}/email/update

Tags: Users

Returns nothing on success.

application/json

New email.

session_id

Session identifier retrieved during authentication.

path string

application/json

400 Bad Request

Email specified is not valid.

403 Forbidden

Forbidden access. Session is not valid.

500 Internal Server Error

Unable to update the email due to server side error.

Get user connected informations.

GET /user/{session_id}/get

Tags: Users

Returns user information on success.

application/json

session_id

Session identifier retrieved during authentication.

path string

application/json

200 OK

successful operation

403 Forbidden

Forbidden access. Session is not valid.

500 Internal Server Error

Unable to update the passwordget user information due to server side error.

Set a user option.

POST /user/{session_id}/option/set

Tags: Users

Returns nothing on success.

application/json

Option to set.

session_id

Session identifier retrieved during authentication.

path string

application/json

403 Forbidden

Forbidden access. Session is not valid.

404 Not Found

Option key is not found.

500 Internal Server Error

Unable to set the user option due to server side error.

Update the connected user password.

POST /user/{session_id}/password/update

Tags: Users

Returns nothing on success.

application/json

New blank password. You must not encrypt the password, the server will do it.

session_id

Session identifier retrieved during authentication.

path string

application/json

400 Bad Request

Password specified is not valid.

403 Forbidden

Forbidden access. Session is not valid.

500 Internal Server Error

Unable to update the password due to server side error.

Returns the list of parcels posted (including canceled parcels). By default, the current month is returned.

GET /user/{session_id}/posted/parcels/list

Tags: Users

application/json

session_id

Session identifier retrieved during authentication.

path string
pagOffset query integer (int64)
pagNbrEntries query integer (int64)
sortBy query string , x ∈ { ID , CREATION_DATE , HT_AMOUNT , STATE }
sortAscending query boolean
searchBy query string[] , multiple parameters (searchBy=aaa&searchBy=bbb)
searchKeywords query string[] , multiple parameters (searchKeywords=aaa&searchKeywords=bbb)
startDate query string (date-time)
endDate query string (date-time)

application/json

200 OK

successful operation

400 Bad Request

Pagination inputs are not valid.

403 Forbidden

Forbidden access. Session is not valid.

500 Internal Server Error

Unable to retrieve list of posted parcels due to server side error.

Update chronopost identifiers after testing them on Chronopost.fr.

POST /user/{session_id}/update/chronopost/identifiers

Tags: Users

Returns nothing.

application/json

session_id

Session identifier retrieved during authentication.

path string

application/json

400 Bad Request

Identifier are not valid.

401 Unauthorized

Chronopost identifiers are invalid.

403 Forbidden

Forbidden access. Session is not valid.

500 Internal Server Error

Unable to update chronopost identifiers to an internal error.

Schema definitions

AEOrderTrackingStateEvent: object

date: string (date-time)
event: string
extra: string

AuthIdentifiers: object

Model which describes identifiers in order to authenticate or refresh session.

email: string

This is the user email. String length [10, 255].

password: string

This is the user password already encrypted in SHA256. String length [64, 64].

ChronopostParcelOptions: object

Chronopost parcel options at shipment

informSender: boolean

Inform sender about shipment

informSenderBy: string , x ∈ { MAIL , SMS }

Inform sender way. 'MAIL' or 'SMS'. Ignore if 'informSender' is set to false.

sendMailRecipient: boolean

Send a mail to the recipient.

shippingDate: string (date-time)

Shipment date if defered

insuranceValue: integer (int32)

Value to insure

saturdayDelivery: boolean

Option to set if you want Chronopost deliver your parcel on saturday.

CreateOrUpdateParcelConfigPreset: object

Model to create a parcel config preset

name: string

This is the preset name. String length [3,30].

entries: object

Hashmap of entries with their associated value. Keys are ParcelConfigPresetEntry and values are String. {ENUM}ParcelConfigPresetEntry: {"VALUE_TO_DECLARE_TO_CUSTOMS", "LENGTH", "WIDTH", "HEIGHT", "WEIGHT", "PRODUCT_DESCRIPTION", "CONTAINER", "SEND_TYPE_INTERNATIONAL", "SEND_TYPE_NATIONAL", "INFORM_SENDER_BY", "SEND_MAIL_RECIPIENT", "INSURANCE_VALUE"}

isDefault: boolean

This is the config default state.

EncrustedProduct: object

Model to describe an encrusted token on PDF files

reference: string

This is the product reference if any. String.

name: string

This is the product name. String.

quantity: integer (int32)

This is the product quantity. Integer.

displayOnLabel: boolean

True to display the product on the label. Boolean.

weight: number (float)

This is the product weight. Float.

File: object

Application/Octets stream.

GetAddress: object

Model describing a user address

id: integer (int32)

This is the address id.

name: string

This is the address label name.

firstname: string

This is the recipient firstname.

lastname: string

This is the recipient lastname.

country: string

This is the recipient country.

addrLine1: string

Address line 1.

addrLine2: string

Address line 2.

addrLine3: string

Address line 3.

zipCode: string

ZipCode if any.

city: string

This is the recipient city name.

phonenumber: string

This is the recipient phonenumber.

companyName: string

This is the recipient company name.

GetApi: object

Model describing user api information

apiKey: string

API key

active: boolean

GetBill: object

Model describing a bill

id: integer (int32)

Bill identifier

userId: integer (int32)

Bill user identifier

name: string

Bill name

creationDate: string (date-time)

Bill created date

amountHT: number (float)

Bill amount HT

amountTTC: number (float)

Bill amount TTC

status: string , x ∈ { WAITING_FOR_PAYMENT , PAYING , PAID , WAITING_BANKWIRE_VALIDATION , WAITING_FOR_WITHDRAW_PAYMENT , WAITING_FOR_WITHDRAW_PAYOUT , PAYMENT_REFUSED }

Bill current status

paymentWay: string , x ∈ { BANK_WIRE , HIPAY , WITHDRAW }

Bill payment way

GetConstraintsInfo: object

Model describing postage constraints

maximumNumberOfParcels: integer (int32)

Maximum number of parcels which can be sent to edit labels for each call to the webservice.

delayInMinutesBetweenCallsToEditLabels: integer (int32)

Minimum number of minutes between each webservice call to edit labels.

GetModule: object

Model describing a prestashop module

id: integer (int32)

Module identifier

creationDate: string (date-time)

Module created date

version: string

Module version

prestashopVersionInfo: GetPrestashopVersion

Prestashop version

GetOption: object

Model describing a user option

key: string , x ∈ { NOTIF_NEW_BILL , NOTIF_NEW_VERSION , NOTIF_NEW_API_STATE , PIL_REFUND_TYPE , SERVICE_INLATE_ENABLED , OPTION_CONFIRM_DIALOG_OVERSEA_PARCELS , OPTION_KEEP_INFO_AREA_IN_PDF }

Option key

value: string

Option value

GetParcelConfigPreset: object

Model describing a parcel configuration preset

id: integer (int32)

This is the preset db identifier.

name: string

This is the preset name.

fieldsList: object[]

This is the list of the fields.

default: boolean

GetParcelConfigPresetField: object

Model describing a parcel configuration preset field

id: integer (int32)

This is the preset field db identifier.

key: string , x ∈ { VALUE_TO_DECLARE_TO_CUSTOMS , LENGTH , WIDTH , HEIGHT , WEIGHT , PRODUCT_DESCRIPTION , CONTAINER , SEND_TYPE_INTERNATIONAL , SEND_TYPE_NATIONAL , INFORM_SENDER_BY , SEND_MAIL_RECIPIENT , INSURANCE_VALUE }

This is the preset field key.

value: string

This is the preset field value.

GetPointRelai: object

Model describing a pointRelai

chronopostIdentifier: string

This is the pointRelai identifier.

name: string

This is the pointRelai name.

address: string

This is the pointRelai address.

zipCode: string

This is the pointRelai zip code.

city: string

This is the pointRelai city.

openingHours: object[]

This is the pointRelai opening hours.

GetPointRelaiOpeningHours: object

openingHoursAsString: string

Opening hours as string. Exemple: '08h30-12h00 14h00-17h00'

day: integer (int32)

This is the day ordinal. 1:Monday to 7:Sunday

GetPostedParcel: object

Model describing a posted parcel

id: integer (int32)

Db identifier

creationDate: string (date-time)

Posted date

reference: string

The reference (track number)

htAmount: number (float)

HT amount

canceled: boolean

GetPostedParcelList: object

numberOfPages: integer (int64)
parcels: object[]

GetPrestashopVersion: object

Model describing Prestashop version

id: integer (int32)

This is the Prestashop version id.

name: string

This is the prestashop version name.

GetProxy: object

Model describing a proxy

index: integer (int32)

Proxy index in list

proxy: string

Proxy

users: integer[]

List of users associated

integer (int32)

GetStringAsJson: object

Model describing a string but compatible with json structure

response: string

Variable containing raw string response.

GetTask: object

Model describing a task

id: integer (int32)

This is the task db identifier.

creationDate: string (date-time)

This is the task creation date.

userId: integer (int32)

This is the associated task user id.

status: string , x ∈ { INITIALIZATION , GETTING_REQUIRED_FIELDS , GETTING_REQUIRED_FIELDS_ERROR , FILLING_REQUIRED_FIELDS , CALCULATING_PRICE , CALCULATED_PRICE_WAIT_FOR_APPROVAL , PAYING , GETTING_TRACKING_NUMBERS , BUILDING_PDF , ERROR , DONE , CANCELED }

This is the task status.

reference: string

This is the task reference.

orderNumber: string

This is the task associated chronopost order number.

ttcAmount: number (float)

This is the ttc amount calculated.

htAmount: number (float)

This is the ht amount calculated.

tvaAmount: number (float)

This is the tva amount calculated.

moneySymbol: string

This is the money symbol for amounts calculated.

pdfPath: string

This is the path to the built PDF.

logsList: object[]

This is the list of task logs associated.

parcelsList: object[]

This is the list of the task parcels associated.

GetTaskLog: object

Model describing a task log message

id: integer (int32)

This is the task log db identifier.

creationDate: string (date-time)

This is the task log creation date.

reference: string

This is the task log reference (depending on type, for steps it is the state).

type: string , x ∈ { INFO , ERROR , STEP }

This is the task log message type.

message: string

This is the task log message.

data: string

This is the task log data if any.

GetTaskParcel: object

Model describing a task parcel

id: integer (int32)

This is the task parcel db identifier.

country: string

Country in ISO format

countryName: string

Country name

type: string , x ∈ { PARTICULAR , COMPANY }

Parcel type (PARTICULAR or COMPANY)

socialReason: string

Social reason (mandatory if type is COMPANY)

lastName: string

Last name

firstName: string

First name

address: string

Address line 1

moreAddress: string

Address line 2

doorCode: string

Door code

zipCode: string

Zip code

city: string

City

state: string

State

phoneNumber: string

Phone number

email: string

Email

customToken: string

Custom token (this value is the prestashop order id when this parcel comes from the prestashop module)

trackingNumber: string

Tracking number

htAmount: number (float)

HT amount

GetTaskParcelRequiredFieldStaticLabel: object

Model describing a task required field label

name: string

This is the task required field name.

label: string

This is the task required field label.

GetTimeRemaining: object

Model describing the time remaining

hours: integer (int64)

The remaining hours.

minutes: integer (int64)

The remaining minutes.

seconds: integer (int64)

The remaining seconds.

zero: boolean

GetUser: object

Model describing a user

id: integer (int32)

This is the user id.

firstname: string

This is the user firstname.

lastname: string

This is the user lastname.

birthdayDate: string (date-time)

This is the user birthday date.

email: string

This is the user email.

phonenumber: string

This is the user phonenumber. Must be in international format.

commissionAmount: number (float)

This is the user commission amount in euros.

companyName: string

This is the user company name.

companySite: string

This is the user company website.

chronopostUsername: string

This is the chronopost user username.

chronopostPassword: string

This is the chronopost user password.

freeUntil: string (date-time)

Date until parcels are free.

apiInfo: GetApi

API information.

billAddressInfo: GetAddress

Bill address.

proxyInfo: string

Proxy used (automatically determined).

autowithdrawStatus: string , x ∈ { NONE , WAITING_FOR_READY , READY , REVOKED }

AutoWithdraw status.

optionsList: object[]

Options associated to the user.

admin: boolean

InputStream: object

ListElementViolations: object

Model describing a list element violations

id: string

This is the element id in the list passed as parameter.

violations: object[]

This is list of violations of this element.

Parcel: object

Abstract model describing a generic parcel

isSentToPointRelai: boolean

True to specifcy that this parcel is sent to a PointRelai. When unspecified, automatically set to false.

pointRelaiInfos: PointRelaiInfos

This property is mandatory if the isPointRelai property is set to true. Otherwise you can ignore it..

country: string

Recipient country in two letter. Example: FR. String length [2, 2].

countryName: string

Recipient country complete name. Example: FRANCE. String length [2, 50].

socialReason: string

Recipient social reason. String length [0, 150].

lastName: string

Recipient lastname. String length [3, 100].

firstName: string

Recipient firstname. String length [3, 100].

address: string

Recipient address. String length [1, 255].

moreAddress: string

Recipient more address. String length [0, 255].

doorCode: string

Recipient door code. String length [0, 50].

zipCode: string

Recipient zip code. String length [0, 30].

city: string

Recipient city name. String length [3, 255].

state: string

Recipient state/region. String length [0, 150].

phoneNumber: string

Recipient phone number. String length [1, 50].

email: string

Recipient email. String length [4, 255].

PointRelaiInfos: object

Model which describe a pointRelai. You can get pointRelai description by calling public resource method : GetPointsRelais

address: string

The pointRelai address from which we search for it.

zipCode: string

This is the pointRelai zip code from which we search for it.

city: string

This is the city name from which we search for it.

chronopostIdentifier: string

This is the identifier.

RequestPointRelaiList: object

Model which describe location in order to search for nearest pointRelais.

address: string

This is the address from which we search for. Can be null.

zipCode: string

This is the zip code.

city: string

This is the city name. Can contains mistakes, it will be automatically fixed thanks to provided zip code.

RequiredFieldsFilled: object

Required fields filled by user. This bean is used by webservice as a request.

taskParcelId: integer (int32)

This is the task parcel identifier.

data: object

This is the list of chosen data. This is an hashmap where the Keys are String and Values are String.

options: ChronopostParcelOptions

Chronopost parcel options

SetOption: object

Model to set user option

key: string , x ∈ { NOTIF_NEW_BILL , NOTIF_NEW_VERSION , NOTIF_NEW_API_STATE , PIL_REFUND_TYPE , SERVICE_INLATE_ENABLED , OPTION_CONFIRM_DIALOG_OVERSEA_PARCELS , OPTION_KEEP_INFO_AREA_IN_PDF }

Option key

value: string

Option value

Task: object

Model describing task

parcels: object[]

List of parcels

webhooks: object[]

List of webhooks. Optional.

TaskParcel: object

Model describing a task parcel

id: integer (int32)

This id is set by the user and is not used at server side EXCEPTING for identify the parcel in a returned error.

weight: number (float)

You can set the weight if you know it in order to pre-fill this attribute. The automatic weight calculation based on IncrutedProducts specified (if any) is overrided by this parameter.

insuranceValue: integer (int32)

You can set the insurance value for the parcel if you know it in order to pre-fill this attribute.

data: Parcel

Chronopost parcel

customToken: string

Inscrusted token on the label, when you are using a CMS like prestashop, it is better to write the id of the order.

products: object[]

Inscrusted products

UpdateChronopostIdentifiers: object

Model to update chronopost identifiers

chronopostUsername: string

This is the user chronopost username. String min [3].

chronopostPassword: string

This is the user chronopost password. String min [3].

UpdateMail: object

Model to update a mail

subject: string

Mail subject.

template: string

The mail template.

Violation: object

Model which describe a request constraint violation

propertyPath: string

This is the request model property path.

message: string

This is the request model constraint violation message (in user language) to display to the user.

Webhook: object

action: string , x ∈ { CALLBACK_ONFINISHED }
callbackUrl: string