Guide pratique

Comment utiliser l’API du TMS Everest ?

16 mars 2022

Dans le monde de la logistique moderne, la gestion efficace des livraisons est indispensable pour répondre aux exigences croissantes des clients. Le TMS (Transport Management System) Everest se présente comme un atout essentiel, proposant une API robuste pour faciliter l’intégration et l’optimisation de vos processus logistiques. Cet article vous guidera à travers les fonctionnalités fondamentales de l’API du TMS Everest, vous expliquant comment elle peut s’intégrer dans votre infrastructure existante et simplifier la gestion de vos livraisons.

Où trouver la documentation de l’API ?

La documentation de l’API Everest est disponible à l’adresse : https://<nomdedomaine>/api/documentation. Par exemple https://annapurna.everst.io/api/documentation.
Elle affiche une vue d’ensemble des capacités de l’API, une explication des différents appels disponibles et des exemples pratiques pour une intégration simplifiée.

Si vous êtes connectés à votre plateforme Everest, le lien de la documentation affichera la documentation complète, avec toutes les méthodes disponibles.
Si vous n’êtes pas connectés à la plateforme Everest, ou si vous êtes connectés en tant que “client”, la documentation ne listera que les méthodes disponibles pour les clients, soit une version plus limitée de l’API.

En tant que client d’une plateforme Everest, vous avez accès à une version réduite de l’API. Référez vous à la documentation qui vous a été transférée pour connaitre les méthodes et paramètres disponibles.

À quoi sert l’API du TMS Everest ?

L’API du TMS Everest permet aux utilisateurs d’automatiser et de gérer efficacement leurs processus de livraison. Elle offre une variété de fonctionnalités, notamment la création, la mise à jour et le suivi des livraisons, ainsi que la gestion des chauffeurs (référencés comme “agents” dans l’API). En fournissant un accès programmatique aux données de votre flotte et de vos missions (ou livraisons), l’API facilite la création de solutions personnalisées adaptées aux besoins spécifiques de votre entreprise ou de vos partenaires.

Exemple d’authentification

Avant de pouvoir utiliser l’API, vous devez vous authentifier. Le processus d’authentification garantit que seules les personnes autorisées peuvent accéder aux données sensibles de votre entreprise.

Certains appels API nécessitent d’être authentifiés. L’authentification s’effectue en appelant la méthode API /api/auth, et en envoyant les paramètres nommés “client_id” et “client_secret“. Ces paramètres peuvent être récupérés par un administrateur de la plateforme, dans la section Admin > API, ou dans l’onglet “API” pour les clients.

L’authentification se fait au travers d’un Bearer token. Le Bearer token peut être obtenu en appelant la méthode /api/auth.

Voici un exemple de requête pour s’authentifier auprès de l’API du TMS Everest :

Requête :

POST /api/auth HTTP/1.1
Host: demo.everst.io
Accept: application/json
Content-Type: application/json
Content-Length: 120

{
    "client_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Réponse :

{
    "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Le token ainsi obtenu doit être transmis dans chaque requête HTTP subséquente au sein de l’entête HTTP Authorization: Bearer <token>.

Exemple d’utilisation du Bearer token : 

GET /api/missions HTTP/1.1
Host: demo.everst.io
Accept: application/json
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Réponse :

{
    "missions": [{
        …
    }],
    “success”: true
}

Le token n’a pas de durée d’expiration. Le token expire dès lors qu’un nouveau token a été généré avec /api/auth.

Nous vous recommandons de sauvegarder en mémoire le Bearer token, afin de ne pas appeler la méthode /api/auth à chaque fois. Ne régénérez le token avec /api/auth que si l’API répond une HTTP 401 Unauthorized.

Timestamps

Les timestamps attendus par Everest sont de la forme UNIX POSIX.
En PHP il s’agit de la fonction time().
En JavaScript il s’agit de : parseInt(Date.now() / 1000)
Ils doivent être localisés en GMT+2 (pas de timestamp UTC, mais bien un timestamp GMT+2).

Exemple pour le 20/09/2024 06:30 :
start_date: 1726806600

Création de livraisons via API

Dans Everest, les livraisons sont des “missions”.

La documentation complète de l’API précise le détail des champs possibles et leur type. Voici un exemple de requête de création de livraison :

Requête :

POST /api/missions/create HTTP/1.1
Host: demo.everst.io
Accept: application/json
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Content-Length: 1482

{
    "client_id": 2,
    "service_id": 6,
    "start_date": 1726826756,
    "comment": "Ring twice, sometimes it does not work",
    "client_ref": "MY_CUSTOM_ID",
    "address_start": "3 rue des Juges Consuls, 75004 Paris",
    "address_start_name": "John Doe",
    "address_start_tel": "0557000400",
    "address_end": "7 Rue Bonnefin, 33100 Bordeaux",
    "address_end_name": "Senior Bonnefin",
    "custom_infos": [
        {
            "name": "OTHER_ID",
            "value": "XXxXXxXXxXX"
        },
        {
            "name": "Or any other useful information I wish to store",
            "value": "XXxX XxX XxXX"
        }
    ],
    "packages": [
        {
            "name": "First product",
            "weight": 2.5,
            "volume": 0.002873,
            "length": 34,
            "width": 26,
            "depth": 3.25,
            "ref": "SCANCODE",
            "quantity": 1
        },
        {
            "name": "Another product",
            "weight": 0,
            "volume": 0,
            "length": 0,
            "width": 0,
            "depth": 0,
            "ref": "My ean",
            "quantity": 1
        }
    ]
}

Réponse :
Cela renvoie le détail complet de la mission, et notamment un champ ref qui est l’identifiant unique de la livraison Everest.

{
    "mission": {
        "ref": "2R8Q4JNO0Y",
        "type": 0,
        "client_ref": "MY_CUSTOM_ID",
        "start_date": 1726827000,
        …
    },
    "success": true
}

Mise à jour de livraisons

Il est possible de mettre à jour seulement une partie des informations d’une livraison. Cela fonctionne comme la création de livraison, à l’exception du fait qu’il faut spécifier le champ ref.

Attention, si vous mettez à jour le champ packages (le détail des colis d’une livraison), il faut renvoyer TOUS les colis, et non pas seulement ceux à ajouter.

Idem pour custom_infos.

Exemple de requête mettant à jour, pour la livraison 2R8Q4JNO0Y, la liste des colis à livrer.

Requête : 

PUT /api/missions/update HTTP/1.1
Host: demo.everst.io
Accept: application/json
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Content-Length: 575

{
    "ref": "2R8Q4JNO0Y",
    "packages": [
        {
            "name": "First product",
            "weight": 2.5,
            "volume": 0.002873,
            "length": 34,
            "width": 26,
            "depth": 3.25,
            "ref": "SCANCODE",
            "quantity": 1
        },
        {
            "name": "Another product",
            "weight": 0,
            "volume": 0,
            "length": 0,
            "width": 0,
            "depth": 0,
            "ref": "My ean",
            "quantity": 1
        }
    ]
}

Réponse :
Cela renvoie le détail complet de la mission modifiée.

{
    "mission": {
        "ref": "2R8Q4JNO0Y",
        "type": 0,
        "client_ref": "ID MICROLIDE",
        "start_date": 1726827000,
        …
    },
    "success": true
}

Conclusion

L’API du TMS Everest est un outil puissant qui permet aux entreprises de rationaliser leurs opérations logistiques et de rester compétitives sur le marché. Avec des fonctionnalités allant de la création de livraisons à la gestion des chauffeurs et l’optimisation de tournées, elle offre une flexibilité et une puissance inégalées pour personnaliser vos processus logistiques. Pour en savoir plus et pour explorer d’autres fonctionnalités, consultez la documentation complète à l’adresse fournie ci-dessus.

Intégrez l’API dans votre workflow et découvrez la simplicité de la gestion logistique moderne.

Sur le même thème