Colis, adresses et transporteurs

Ces routes forment la partie logistique de l'API E-commerce. Elles permettent à vos propres logiciels d'ajouter les colis à suivre, de tenir votre carnet d'adresses à jour avec vos autres outils et de lire le catalogue des transporteurs. Elles travaillent sur les mêmes données que les écrans Logistique de votre espace : un colis créé par l'API apparaît dans votre liste de colis, et une adresse ajoutée à l'écran se relit ici.

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.

Points d'accès

Méthode	Chemin	Droit
GET	`/v1/carrier/list`	`carrier:read`
GET	`/v1/carrier/detail/carr_…`	`carrier:read`
GET	`/v1/parcel/list`	`parcel:read`
GET	`/v1/parcel/detail/parc_…`	`parcel:read`
POST	`/v1/parcel/create`	`parcel:write`
PATCH	`/v1/parcel/detail/parc_…`	`parcel:write`
DELETE	`/v1/parcel/detail/parc_…`	`parcel:write`
GET	`/v1/address/list`	`address:read`
GET	`/v1/address/detail/addr_…`	`address:read`
POST	`/v1/address/create`	`address:write`
PATCH	`/v1/address/detail/addr_…`	`address:write`
DELETE	`/v1/address/detail/addr_…`	`address:write`

Les listes acceptent limit (50 par défaut, 100 au plus) et offset, et répondent total, limit, offset et data. L'authentification, l'enveloppe de réponse et le format des erreurs sont ceux de Votre premier appel.

Transporteurs

Lisez le catalogue pour trouver le transporteur d'un colis : vous passez son id dans carrier_id à la création du colis.

GET /v1/carrier/list accepte ces filtres :

Paramètre	Description
`q`	Une partie du nom, du code ou du code de suivi du transporteur.
`code`	Le code de suivi du transporteur, en chiffres.
`country`	Un code pays à deux lettres.
`source`	`17track` ou `manual`.

L'objet transporteur

Champ	Type	Description
`id`	chaîne	L'identifiant du transporteur, préfixé par `carr_`.
`object`	chaîne	Toujours `carrier`.
`status`	chaîne	Le statut du transporteur dans le catalogue.
`name`	chaîne	Le nom du transporteur.
`code`	chaîne	Le code court du transporteur.
`tracking_code`	chaîne	Le code de suivi du transporteur ; vous pouvez le passer dans `carrier_code` à la place de `carrier_id`.
`country`	chaîne	Le pays du transporteur, en code à deux lettres minuscules.
`website`	chaîne	Le site du transporteur.
`tracking_url`	chaîne	La page publique de suivi du transporteur.
`logo`	chaîne ou null	L'adresse du logo du transporteur.
`contact`	objet	`email` et `phone`.
`source`	chaîne	`17track` ou `manual`.
`created_at`, `updated_at`	entier	Horodatages Unix.

Colis

Suivre un colis

POST /v1/parcel/create ajoute un colis et répond 201 avec le colis.

Champ	Obligatoire	Description
`tracking_number`	Oui	Le numéro de suivi du transporteur, de 5 à 50 caractères ; les espaces sont retirés.
`carrier_id`	Oui, ou `carrier_code`	L'`id` du transporteur, lu dans la liste des transporteurs.
`carrier_code`	Oui, ou `carrier_id`	Le `tracking_code` du transporteur.
`label`	Non	Votre propre nom pour le colis, 200 caractères au plus.
`recipient_id`	Non	Une adresse de votre carnet, préfixée par `addr_`.
`shipment_id`	Non	Une expédition de votre boutique, préfixée par `ship_`.
`origin`, `destination`	Non	Un nom de lieu, 200 caractères au plus.
`origin_country`, `destination_country`	Non	Des codes pays à deux lettres.
`weight`, `weight_unit`	Non	Le poids et son unité ; `kg` sans unité indiquée.
`content`	Non	Le contenu du colis, 255 caractères au plus.
`note`	Non	Une note libre.
`added_at`	Non	Un horodatage Unix, pour conserver la date d'un colis venu d'un autre outil.

curl

curl -X POST https://api.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": "Commande 1042"
  }'

Un numéro de suivi déjà suivi dans votre carnet n'est pas suivi deux fois : la réponse est 409 et porte l'id du colis qui le détient.

Pour ajouter plusieurs colis en un appel, envoyez-les dans items, 100 au plus :

application/json

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

La réponse liste une entrée par élément, dans l'ordre, avec son tracking_number et soit action (created ou existing) et id, soit code et reason quand l'élément a été refusé. Elle se termine par les compteurs created, existing, refused et total. Le statut est 200 quand au moins un colis a été créé ou existait déjà, et 422 quand tous les éléments ont été refusés. Au-delà de 100 éléments, la réponse est 413.

Comment le suivi complète un colis

Un colis commence au statut pending. Ultineo enregistre ensuite son numéro auprès du transporteur en arrière-plan et écrit le résultat sur le colis : son statut dans les mots du transporteur (par exemple InTransit ou Delivered), sa dernière position, ses dates de livraison estimée et réelle, et un événement par étape. L'appel de création ne renvoie rien de cela : relisez le colis, ou synchronisez la liste.

L'objet colis

Champ	Type	Description
`id`	chaîne	L'identifiant du colis, préfixé par `parc_`.
`object`	chaîne	Toujours `parcel`.
`label`	chaîne	Votre propre nom pour le colis.
`status`, `substatus`	chaîne	`pending` au départ, puis le statut du transporteur.
`tracking`	objet	`number`, `carrier_code`, `registration` (l'état de l'enregistrement auprès du transporteur), `state` (`active` ou `paused`), `attempts` et `synced_at`.
`carrier`	objet ou null	`id`, `name` et `logo`.
`recipient`	objet ou null	L'`id` de l'adresse.
`shipment`	objet ou null	L'`id` de l'expédition.
`origin`, `destination`	objet	`place` et `country`.
`weight`	objet	`value` et `unit`.
`content`, `note`	chaîne	Tels que vous les avez envoyés.
`progress`	objet	`last_status_code`, `last_location`, `last_lat`, `last_lng`, `last_event_at`, `estimated_delivery_at` et `delivered_at`.
`created_at`, `updated_at`	entier	Horodatages Unix.

GET /v1/parcel/detail/parc_… renvoie aussi events, les étapes du colis, de la plus récente à la plus ancienne. Chaque événement porte id, type, description, location, lat, lng et occurred_at.

Lister et synchroniser les colis

GET /v1/parcel/list accepte ces filtres : status, tracking_number, carrier (un identifiant carr_…), recipient (un identifiant addr_…), shipment (un identifiant ship_…) et q, qui cherche dans le nom, le numéro, le transporteur, la destination et les noms du destinataire.

Pour suivre les changements sans tout relire, synchronisez la liste :

Appelez une fois GET /v1/parcel/list?updated_since=<horodatage Unix>.
Conservez le cursor de la réponse.
Appelez GET /v1/parcel/list?cursor=<cursor> la fois suivante, et conservez le nouveau cursor.

Tant que next_cursor n'est pas null, d'autres lignes attendent : rappelez aussitôt avec lui. Une synchronisation n'accepte pas offset.

Modifier ou supprimer un colis

PATCH /v1/parcel/detail/parc_… modifie les champs que le corps nomme et laisse les autres en l'état. Deux champs lui sont propres :

Champ	Description
`refresh`	`true` interroge de nouveau le transporteur au prochain passage.
`tracking`	`paused` arrête de suivre le colis, `active` reprend.

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 /v1/parcel/detail/parc_… retire le colis de vos listes et répond { "id": "parc_…", "object": "parcel", "deleted": true }.

Adresses

Ajouter une adresse

POST /v1/address/create ajoute une entrée à votre carnet d'adresses et répond 201.

Champ	Obligatoire	Description
`role`	Oui	`sender` ou `recipient`.
`phone`	Oui	Le numéro de téléphone du contact.
`line1`	Oui	La première ligne de l'adresse.
`postal_code`	Oui	Le code postal.
`city`	Oui	La ville.
`country`	Oui	Un code pays à deux lettres.
`type`	Non	`individual` (par défaut) ou `company`.
`company`	Non	Le nom de l'entreprise, conservé pour une entrée `company` seulement.
`first_name`, `last_name`	Non	Le nom du contact.
`email`	Non	L'adresse e-mail du contact.
`phone_country`	Non	Le pays dans lequel lire le numéro de téléphone ; celui de l'adresse par défaut.
`line2`	Non	La seconde ligne de l'adresse.
`state`	Non	L'État ou la région, conservé seulement pour un pays qui en utilise un.
`label`	Non	Votre propre nom pour l'entrée.
`is_default`	Non	`true` en fait l'entrée par défaut de son rôle.
`note`	Non	Une note libre.

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. Une valeur invalide répond 422. Si la vérification ne peut pas être faite, la réponse est 503 et rien n'est enregistré : renvoyez la demande plus tard.

Le même nom de contact au même code postal n'est pas enregistré deux fois : la réponse est 409 et porte l'id de l'entrée qui le détient déjà.

L'objet adresse

Champ	Type	Description
`id`	chaîne	L'identifiant de l'entrée, préfixé par `addr_`.
`object`	chaîne	Toujours `address`.
`status`	chaîne	`activated`, `suspended` ou `archived`.
`role`	chaîne	`sender` ou `recipient`.
`type`	chaîne	`individual` ou `company`.
`label`, `company`	chaîne	Tels que vous les avez envoyés.
`contact`	objet	`name`, `first_name`, `last_name`, `email` et `phone`.
`location`	objet	`line1`, `line2`, `postal_code`, `city`, `state` et `country`.
`is_default`	booléen	Indique si c'est l'entrée par défaut de son rôle.
`note`	chaîne	Votre note.
`created_at`, `updated_at`	entier	Horodatages Unix.

Lister, modifier ou supprimer une adresse

GET /v1/address/list accepte ces filtres : role, status, country, default=true et q.

PATCH /v1/address/detail/addr_… modifie les champs que le corps nomme. Il accepte aussi status, activated ou suspended. 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, et suspendre l'entrée par défaut lui retire la sienne. Une entrée archivée doit être réactivée avant d'être modifiée.

DELETE /v1/address/detail/addr_… retire l'entrée de votre carnet et répond { "id": "addr_…", "object": "address", "deleted": true }.

Envoyer des commentaires

Contacter le support

Conditions d'utilisation Confidentialité Cookies