Passer au contenu principal
Un envoi correspond à un colis physique : une collecte par coursier transportant des échantillons sanguins d’un lieu de prélèvement vers un laboratoire, le kit envoyé à un patient avec kit à domicile, ou l’échantillon que ce patient renvoie par la poste. L’API Shipments te permet de créer, suivre, modifier et annuler des commandes d’envoi, et liste tous les colis au même endroit, peu importe qui les a réservés.

Une seule liste, filtrée

GET /api/v1/shipments est l’unique collection. Un envoi est autonome — il entretient une relation plusieurs-à-plusieurs avec les rendez-vous et peut appartenir à une commande de kit à domicile — il n’y a donc pas de liste imbriquée sous un parent. Filtre cette même liste avec ?appointment_id= ou ?home_kit_order_id=, pagine-la avec limit / offset, et suis le tableau shipments intégré au parent ({ id, added_at } sur les rendez-vous comme sur les commandes de kit à domicile) vers Récupérer un envoi lorsque tu disposes d’un identifiant.

Contenu, et qui l’a réservé

Chaque envoi comporte deux informations qui ne ressortent pas de ses adresses :
  • contents — texte libre décrivant le contenu du colis, défini à la création ("Medizinisch freigestellte Probe", "Home test kit") et affiché au coursier. À titre informatif uniquement. Le sens n’est pas un champ : pour savoir si un colis part vers un laboratoire, il faut regarder destination.
  • booked_by — qui a imprimé l’étiquette : aniva ou external. Seuls les envois aniva acceptent Mettre à jour et Annuler ; un colis external est suivi dans la même liste, mais renvoie 501 dans les deux cas.
Un colis contenant une étiquette de retour et le colis renvoyé grâce à cette étiquette pointent l’un vers l’autre via paired_with.

Accès

  • Tu peux consulter un colis dès qu’au moins un rendez-vous ou une commande de kit à domicile associé fait partie de ton contexte d’accès, ou qu’il est parti d’un lieu de ton contexte d’accès.
  • appointments et home_kit_orders ne listent que les rendez-vous et commandes de ton contexte d’accès.
  • Mettre à jour, Annuler, Associer des rendez-vous et Dissocier des rendez-vous exigent que chaque commande de kit à domicile associée soit dans ton contexte d’accès. Sinon, l’appel renvoie 403 et seule Aniva peut modifier le colis.

Les lectures n’appellent jamais le transporteur

Chaque lecture est servie depuis notre base de données. Une synchronisation en arrière-plan rapproche chaque envoi de son transporteur (toutes les 10 minutes pour GO!, toutes les heures pour DHL) et horodate synced_at, qui indique l’ancienneté de la réponse. Il n’y a pas d’actualisation forcée — DHL n’autorise qu’un appel de suivi toutes les cinq secondes, si bien qu’une lecture effectuant l’aller-retour vers le transporteur ne pourrait pas être proposée.

Créer un envoi

Lors de la création d’un envoi, tu indiques le location_id d’origine — le lieu de prélèvement où le coursier doit passer. Tu précises également le laboratoire de destination avec destination_lab. L’envoi est acheminé à l’adresse de livraison enregistrée de ce laboratoire. Le lieu doit faire partie du contexte d’accès de ta clé API. Utilise Lister les lieux pour trouver les identifiants de lieux disponibles. Tu peux éventuellement passer appointment_id pour associer l’envoi à un rendez-vous précis au moment de la création. Le lien apparaît directement des deux côtés :
  • sur l’envoi, sous forme d’un tableau appointments d’entrées { id, added_at } ;
  • sur le rendez-vous, sous forme d’un tableau shipments d’entrées { id, added_at }.
Les deux tableaux sont triés du lien le plus ancien au plus récent. Chaque id renvoie vers l’endpoint de détail canonique (Récupérer un rendez-vous / Récupérer un envoi) pour obtenir les données complètes — les partenaires qui souhaitent suivre l’avancement du coursier par rendez-vous suivent chaque entrée du tableau shipments du rendez-vous vers l’endpoint de détail de l’envoi. Un envoi peut être associé à plusieurs rendez-vous, et un rendez-vous peut être associé à plusieurs envois. Après la création, gère les associations avec Associer des rendez-vous à un envoi / Dissocier des rendez-vous d’un envoi. Chaque modification renvoie la liste des rendez-vous de l’envoi après modification. La règle de modification est la suivante : les liens peuvent être créés ou supprimés lorsque SOIT la prise de sang du rendez-vous a déjà eu lieu (blood_drawn), soit l’envoi a été créé il y a moins de 24 heures. En dehors de cette fenêtre, le lien est verrouillé afin que l’historique reste stable.

Cycle de vie

Les expéditions passent par les statuts suivants :
Chaque changement de statut envoie un webhook shipment.*, par exemple shipment.delivered. shipment.updated se déclenche à chaque changement que tu peux lire, comme un nouveau scan.

Règles d’horaire de collecte

Les règles suivantes s’appliquent lors de la création ou de la mise à jour de l’horaire de collecte d’une expédition. pickup_date (YYYY-MM-DD) et pickup_time_from / pickup_time_till (HH:MM, format 24 h) sont des valeurs d’heure locale interprétées dans le fuseau horaire IANA du lieu d’origine — tu n’envoies pas de fuseau horaire avec.

Modifier des expéditions

Tu peux mettre à jour l’horaire de collecte, le nombre de colis, le poids et les notes d’une expédition avec PATCH /api/v1/shipments/{id}. Si un champ lié à la logistique change (date de collecte, horaire, nombre de colis ou poids), la commande logistique existante est automatiquement annulée et une nouvelle est créée. Les champs que tu omets dans le corps de la requête sont conservés depuis l’expédition existante — par exemple, mettre à jour uniquement weight recrée la commande avec le même horaire de collecte. Les champs d’horaire mis à jour sont validés selon les mêmes règles d’horaire de collecte.
Les expéditions ne peuvent plus être modifiées une fois que le coursier a récupéré le colis. Toute tentative de mise à jour d’une expédition au statut in_transit, delivered ou fault renvoie 409 Conflict.
Si le prestataire logistique rejette l’annulation ou la recréation lors d’une mise à jour, l’API renvoie 502 Bad Gateway avec le message d’erreur du prestataire.

Annuler des expéditions

Annule une expédition avec DELETE /api/v1/shipments/{id}. Cela appelle l’API du prestataire logistique pour annuler la commande et passe le statut à cancelled.
Les expéditions ne peuvent plus être annulées après la collecte. Toute tentative d’annulation d’une expédition déjà au statut in_transit, delivered ou fault renvoie 409 Conflict. Annuler une expédition déjà cancelled est sans effet et renvoie 200 avec l’expédition — voir Idempotence.
Le prestataire logistique peut aussi rejeter l’annulation pour ses propres raisons (par exemple, le délai d’annulation est dépassé). Dans ce cas, l’API renvoie 502 Bad Gateway avec le message d’erreur et le code d’erreur du prestataire.

Étiquettes de retour

Une étiquette de retour DHL fait partie de sa commande aller. DHL ne peut pas annuler l’étiquette séparément, donc annuler la ligne qui suit une étiquette de retour renvoie 409 Conflict. Annule plutôt le colis aller tant qu’il est pending. Cela annule aussi l’étiquette : chaque ligne de trajet retour en statut pending liée au colis aller passe à cancelled et reçoit une entrée RETURN_LEG_CANCELLED dans son status_updates. Un colis retour que le patient a déjà posté continue son acheminement. Une fois le colis aller expédié, l’étiquette reste valide et Aniva clôture la ligne de trajet retour manuellement.

Identifiants de référence des expéditions

Chaque envoi a un ID de référence de 11 caractères : une lettre, la date et quatre caractères, {letter}YYMMDDXXXX (par exemple P2611194821). La lettre indique à quoi appartient l’envoi, jamais son sens : Un envoi du 20 au 22 novembre 2026 garde son ID précédé d’un mot : API, MAN, AUTO ou KIT (par exemple AUTO261121UWKX). Les deux formats restent valides. Ne vérifie pas la longueur ni la première lettre d’un ID. Utilise l’ID pour récupérer, mettre à jour ou annuler l’envoi.

Adresses des expéditions

Les champs origin et destination de la réponse d’expédition contiennent des objets d’adresse résolus avec la structure suivante :
Pour un colis de cabinet, l’adresse origin est résolue à partir du lieu de test que tu as indiqué à la création et destination correspond au laboratoire que tu as renseigné dans destination_lab. Pour un colis de kit à domicile, l’adresse de livraison du patient est la destination du kit et l’origin du retour d’échantillon ; le site qui prépare le kit est son origin. L’adresse ne contient pas de location_id — relie un colis de cabinet au rendez-vous auquel il est associé.

Créneau de collecte

Le champ pickup de la réponse d’expédition contient le créneau de collecte prévu par le coursier. Il inclut les horodatages from et till sous forme d’instants UTC (ISO 8601 avec le suffixe Z, par ex. 2026-04-15T07:00:00Z) et une chaîne timezone (fuseau horaire IANA du lieu de collecte). Les valeurs d’heure locale pickup_date / pickup_time_* que tu as envoyées à la création ou à la mise à jour sont converties en ces instants absolus avec ce fuseau horaire — utilise timezone pour réafficher from / till à l’heure locale du lieu de collecte. Le champ vaut null quand aucun créneau de collecte n’a été planifié.

Journal des mises à jour de statut

Chaque expédition contient un tableau status_updates — tous les événements de cycle de vie signalés par le prestataire logistique, du plus ancien au plus récent. Chaque entrée contient :
  • state — l’événement dans le vocabulaire de statut des expéditions (pending, in_transit, delivered, fault), pour que tu puisses lire une chronologie sans connaître les codes du transporteur. null quand l’événement ne porte aucun état (création d’étiquette, scan sans information du transporteur, entrées enregistrées avant l’existence du champ). Jamais cancelled — une annulation vient de nous, pas du transporteur.
  • code — le code de statut propre au transporteur (GO10, GO90, GOY001 chez GO! ; VA, ZF, LA, ZU chez DHL). null quand le transporteur n’en fournit pas. Stable quelle que soit la langue de status.
  • detail_code — le code plus précis du transporteur lorsqu’il en existe un : statusDetailed chez DHL, par ex. CNRFC_NRQRD_ZF (redirigé vers un bureau de poste), HLDCC_SERPT_LA (prêt à être retiré sur place), DLVRD_SERPT_ZU (retiré). null sinon.
  • status — le libellé lisible du transporteur (par ex. "Shipment picked up", "Die Sendung wurde abgeholt.").
  • description — une explication du code, ou la phrase plus longue du transporteur. null quand aucune des deux n’existe.
  • location — le lieu du scan tel que nommé par le transporteur : un dépôt GO!, une ville DHL. Texte libre, pas des coordonnées.
  • time — horodatage ISO 8601 de l’événement tel que transmis par le transporteur (avec son décalage horaire).
Quand le transporteur renvoie le colis à l’expéditeur, la chronologie reçoit une entrée avec le code RETURNED_TO_SENDER. Son champ status contient le motif du transporteur. L’expédition reste alors fault, même après que le transporteur nous a retourné le colis. La liste peut être vide si le transporteur n’a encore signalé aucun événement. Utilise le champ status de premier niveau pour connaître l’état actuel canonique. Il évolue dans un seul sens — de pending à in_transit puis delivered — avec fault superposé tant que le dernier événement en signale un ; les transporteurs ne classent pas leurs événements par importance (DHL ajoute un avis de redirection codé pre-transit après le scan de remise), donc la dernière entrée seule ne suffit pas à savoir où en est un colis.

Exemple d’expédition

Exemple de colis de kit à domicile

GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-… renvoie ensemble le kit en route vers le patient et l’échantillon sur le chemin du retour :
La ligne de trajet retour existe dès l’impression de l’étiquette de retour et reste pending jusqu’à ce que le patient poste l’échantillon — c’est l’état réel, pas une anomalie.