Développeurs · API

Suivez vos colis et tenez vos adresses à jour depuis vos logiciels

L’API d’Ultineo Logistics, sur api.logistic.ultineo.com, permet à votre logiciel d’ajouter les colis à suivre, de tenir votre carnet d’adresses à jour avec vos autres outils et de lire le catalogue des transporteurs. Chaque appel porte une clé d’API de votre projet, limitée à ses droits.

Ce que vos logiciels peuvent faire avec ces routes

Suivre des colis

Vos logiciels ajoutent les colis à suivre, chacun avec son numéro de suivi et son transporteur. Ultineo enregistre ensuite le numéro auprès du transporteur en arrière-plan et écrit le résultat sur le colis : son statut, sa dernière position, ses dates de livraison et un événement par étape.

Tenir le carnet d’adresses

Le carnet d’adresses conserve les adresses d’expéditeurs et de destinataires que vous réutilisez, celles que vous choisissez en ajoutant un colis ou en enregistrant une étiquette d’expédition. Les routes des adresses ajoutent, listent, modifient et suppriment ses entrées, pour le tenir à jour avec vos autres outils.

Lire le catalogue des transporteurs

Lisez le catalogue pour trouver le transporteur d’un colis, par une partie de son nom, par son code de suivi ou par son pays. Vous passez son id dans carrier_id, ou son code de suivi dans carrier_code, à la création du colis.

Les routes, famille par famille

Une clé lit et écrit le carnet d’adresses et les colis du compte auquel elle appartient, et rien d’autre ; le catalogue des transporteurs est commun et en lecture seule. Les lectures exigent le droit carrier:read, parcel:read ou address:read, et créer, modifier ou supprimer un colis ou une adresse exige parcel:write ou address:write.

Transporteurs

GET /v1/carrier/list liste le catalogue avec les filtres q, code, country et source, et GET /v1/carrier/detail/carr_… lit un transporteur. Un transporteur est renvoyé avec son id, son nom, son code court, son code de suivi, son pays, son site et sa page publique de suivi.

Suivre un colis

POST /v1/parcel/create envoie un numéro de suivi de 5 à 50 caractères et le transporteur, avec un libellé facultatif, une adresse de votre carnet comme destinataire et une expédition. Un appel ajoute un colis, ou jusqu’à 100 sous items : au-delà de 100, la réponse est 413.

L’objet colis

GET /v1/parcel/detail/parc_… renvoie le colis : son statut, pending au départ puis le statut du transporteur, l’état de son suivi, son transporteur, son destinataire et son expédition, et sa progression avec la dernière position et les dates de livraison. Il renvoie aussi events, les étapes du colis, de la plus récente à la plus ancienne.

Lister et synchroniser les colis

GET /v1/parcel/list filtre par statut, numéro de suivi, transporteur, destinataire ou expédition, cherche avec q, et accepte limit (50 par défaut, 100 au plus) et offset. La même route synchronise la liste avec updated_since et un cursor.

Modifier ou supprimer un colis

PATCH /v1/parcel/detail/parc_… modifie les champs que le corps nomme et laisse les autres en l’état ; changer le numéro de suivi ou le transporteur enregistre de nouveau le colis, et son statut revient à pending ; un colis archivé ne peut plus être modifié. DELETE sur le même chemin retire le colis de vos listes.

Ajouter une adresse

POST /v1/address/create envoie un rôle, sender ou recipient, avec un numéro de téléphone, la première ligne de l’adresse, le code postal, la ville et un code pays à deux lettres, et répond 201. Le numéro de téléphone, et l’adresse e-mail quand il y en a une, sont vérifiés avant tout enregistrement, et l’entrée conserve leur forme normalisée.

Lister, modifier ou supprimer une adresse

GET /v1/address/list filtre par rôle, statut, pays, entrée par défaut ou q ; PATCH et DELETE sur /v1/address/detail/addr_… modifient les champs que le corps nomme, statut compris, ou retirent l’entrée de votre carnet. Il y a au plus une entrée par défaut par rôle et seule une entrée activée peut l’être : en marquer une retire la marque des autres.

Suivre un colis, ou plusieurs

Le premier exemple est la requête qui ajoute un colis et répond 201 avec le colis. Le second est le corps qui ajoute plusieurs colis en un appel.

Requête de création

curl -X POST https://api.logistic.ultineo.com/v1/parcel/create \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_number": "1Z999AA10123456784",
    "carrier_code": "100002",
    "label": "Order 1042"
  }'

Le transporteur est désigné ici par carrier_code, son code de suivi, et label est votre propre nom pour le colis.

Corps pour plusieurs colis

{
  "items": [
    { "tracking_number": "1Z999AA10123456784", "carrier_code": "100002" },
    { "tracking_number": "LX123456789FR", "carrier_id": "carr_4f1c2a9d8e7b6a5c4d3e" }
  ]
}

Chaque élément désigne son transporteur par carrier_code ou carrier_id, et la réponse liste une entrée par élément, dans l’ordre : created ou existing avec son id, ou le code et le reason de son refus ; le statut n’est 422 que lorsque tous les éléments ont été refusés.

Les points à surveiller

Le suivi arrive ensuite

Un colis commence au statut pending, et l’appel de création ne renvoie rien de ce que le transporteur signale. Relisez le colis, ou synchronisez la liste.

Rien n’est enregistré deux fois

Un numéro de suivi déjà suivi dans votre carnet, ou le même nom de contact au même code postal, n’est pas enregistré une seconde fois : la réponse est 409 et porte l’id du colis ou de l’entrée qui le détient déjà. Dans un appel avec items, un numéro déjà suivi revient comme une entrée marquée existing, avec son id.

Une vérification impossible

Si la vérification du numéro de téléphone ou de l’adresse e-mail d’une entrée ne peut pas être faite, la réponse est 503 et rien n’est enregistré. Renvoyez la demande plus tard.

Les articles derrière cette page

Cette page reprend les articles suivants du centre d’aide. Ils détaillent chaque champ, chaque valeur et chaque réponse.

Centre d’aide Ultineo Logistics

Expéditions

Colis, transporteurs et suivi

Ouvrir la page

Poursuivre dans cette rubrique

API E-commerce

Créer un accès API et échanger les données de votre boutique

Ouvrir la page

Catalogue, commandes et bons de réduction

Ce qu’un programme envoie et relit pour chaque ressource du catalogue, de l’historique des ventes et des bons de réduction.

Ouvrir la page

API Ultineo Reasoning

Lancez vos raisonnements depuis vos logiciels.

Ouvrir la page

API de projet Ultineo SaaS

Examinez le périmètre API d’un projet éligible et distinguez les routes prévues des endpoints déjà construits.

Ouvrir la page

Vue d’ensemble développeurs

Commencez par un colis et son transporteur

Le centre d’aide d’Ultineo Logistics donne chaque champ des routes colis, adresses et transporteurs ; une clé d’API portant leurs droits est créée pour votre projet dans Ultineo Logistics.

Questions

Synchronisez la liste. Appelez une fois GET /v1/parcel/list avec updated_since à un horodatage Unix et conservez le cursor de la réponse, puis appelez la liste avec ce cursor la fois suivante et conservez le nouveau. Tant que next_cursor n’est pas null, d’autres lignes attendent : rappelez aussitôt avec lui. Une synchronisation n’accepte pas offset.

Oui. Ces routes travaillent sur les mêmes données que les écrans d’Ultineo Logistics. Un colis créé par l’API apparaît dans votre liste de colis, et une adresse ajoutée à l’écran se lit par l’API.

Oui. Un PATCH avec tracking à paused arrête le suivi du colis, et active le reprend. Dans Ultineo Logistics, la page du colis a aussi une pause, et les informations déjà collectées restent disponibles. Pour interroger à nouveau le transporteur au prochain passage, envoyez refresh à true.

DELETE retire le colis de vos listes et répond son identifiant avec deleted à true. Dans Ultineo Logistics, un colis supprimé à l’écran quitte vos listes tandis que ses informations et son historique de suivi sont conservés, et aucune demande n’est envoyée au transporteur.