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.
Poursuivre dans cette rubrique
- API E-commerce
Créer un accès API et échanger les données de votre boutique
- 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.
- API Ultineo Reasoning
Lancez vos raisonnements depuis vos logiciels.
- 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.
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.