Fonctionnement général

L’API MyDelivengo Conso est écrite en PHP. Les fonctionnalités de MyDelivengo Conso utilisables via l'API MyDelivengo Conso sont publiées sous forme de web service via des API en architecture REST.

Vous pouvez y accéder via des requêtes HTTPS. À chaque fonctionnalité correspond une URL. L'API MyDelivengo utilise les méthodes GET, POST, PUT et DELETE.

L' URL d'accès à l'API est :

//conso.mydelivengo.laposte.fr/api/v[VERSION]/

où [VERSION] correspond au numéro de version de l'API utilisée (la dernière version à jour est la 2.4).

À la suite de cette URL de base se positionne la fonctionnalité demandée. Par exemple, pour recevoir la liste des envois de votre compte MyDelivengo, vous pouvez utiliser l'API "envois". L'URL à fournir sera alors :

GET //conso.mydelivengo.laposte.fr/api/v2.4/envois

L'URL peut être ensuite complétée par des paramètres, au format query string. Par exemple, pour recevoir la liste des envois de votre compte MyDelivengo, vous pouvez utiliser l'API "envois" avec un paramètre length à 100 (on demande de ne renvoyer que 100 envois maximum) et un paramètre start à 3 (on demande que l'index de début de pagination soit à 3) :

 GET //conso.mydelivengo.laposte.fr/api/v2.4/envois?length=100&start=3

La liste des paramètres acceptés est défini dans la documentation détaillée de chaque API (voir Paramètres d'URL).

Pour les méthodes POST et UPDATE, des données supplémentaires peuvent être passées à la requête HTTP. Ces données doivent être structurées sous forme d'objets JSON. Le détail de l'objet JSON attendu est défini dans la documentation détaillé de chaque API (voir Requête : Liste des propriétés)

Authentification

Pour utiliser l'API MyDelivengo, vous devez avoir accès à un compte MyDelivengo ainsi qu'à votre clé API unique (Pour tout besoin d'utilisation de l'API, prenez contact avec votre interlocuteur commercial MyDelivengo Conso afin de valider le périmètre de votre projet). La clé API unique liée à votre compte est disponible dans le menu "Mon Compte" de MyDelivengo. Exemple de clé API :

Oono8eez7eez9NRZ3xaeFaeh8hee3u

Cette clé doit être envoyée à chaque requête envoyée à l'API MyDelivengo, via une entête HTTP spécifique : API-Authorization Si cette clé n'est pas fournie ou si la clé n'est pas correcte, une réponse HTTP 401 Unauthorized sera renvoyée. Exemple de requête HTTP :
GET //conso.mydelivengo.laposte.fr/api/v2.4/envois
API-Authorization: Oono8eez7eez9NRZ3xaeFaeh8hee3u

Codes Retour

Les codes retour standards HTTP sont utilisés, notamment :

  • 200 : OK. Une réponse normale est transmise.
  • 400 : Votre requête comporte une erreur ; vérifiez les paramètres obligatoires ainsi que le format des données. Un message d'erreur sera renvoyé avec le détail du problème. Corrigez votre requête et essayez à nouveau.
  • 404 : L'API demandé n'existe pas. Vérifiez l'URL.
  • 405 : La méthode n'est pas reconnue ; l'API MyDelivengo n'utilise que les méthodes GET, POST, UPDATE, et DELETE.
  • 401 : Accès non autorisé ; l'authentification a échoué : la clé d'authentification n'a pas été envoyée ou n'est pas reconnue.
  • 500 : Erreur générale coté serveur. Un message d'erreur sera renvoyé avec le détail du problème.

Votre application

Avec l'API MyDelivengo Conso, vous pouvez imaginer et développer différents types d'interactions entre vos outils et MyDelivengo Conso. Si votre objectif est de mettre sur pied rapidement une application simple permettant de déclarer des envois et de récupérer les étiquettes à imprimer et les documents douaniers liés, puis de déposer ces plis pour récupérer les documents de dépôts correspondants, alors les grandes étapes sont les suivantes :

  • Obtenir votre clé API (à ne faire qu'une fois)
  • Obtenir votre id d'utilisateur, en utilisant l'API GET /utilisateurs/{ID_UTILISATEUR}. En faisant un GET/utilisateurs/0, vous obtiendrez le détail de votre compte, dont l'ID_UTILISATEUR nécessaire pour l'utilisation des autres API (à ne faire qu'une fois, votre ID_UTILISATEUR est fixe et ne sera pas modifié)
  • Utiliser l'API POST /envois, avec l'entête "Accept" définie à "application/pdf", afin de pouvoir créer vos plis et de récupérer immédiatement les étiquettes et les éventuels documents douaniers correspondants. MyDelivengo Conso s'appuyant sur le support Delivengo Easy, il n'y pas de bordereau de dépôt à émettre : un pli imprimé passe directement dans votre suivi.
  • et voilà ! Vous pouvez ensuite utiliser les autres API selon vos besoins (récupération des données de suivi (on recommandera alors l'usage de webhooks, listage des données pour contrôle ou réaffichage dans vos interfaces...). N'hésitez pas à contacter le support si vous souhaitez valider votre projet d'API et si vous avez des questions relatives l'application.