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 regarderdestination.booked_by— qui a imprimé l’étiquette :anivaouexternal. Seuls les envoisanivaacceptent Mettre à jour et Annuler ; un colisexternalest suivi dans la même liste, mais renvoie501dans les deux cas.
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.
appointmentsethome_kit_ordersne 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
403et 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 horodatesynced_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 lelocation_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
appointmentsd’entrées{ id, added_at }; - sur le rendez-vous, sous forme d’un tableau
shipmentsd’entrées{ id, added_at }.
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 avecPATCH /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.
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 avecDELETE /api/v1/shipments/{id}. Cela appelle l’API du prestataire logistique pour annuler la commande et passe le statut à cancelled.
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 renvoie409 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 champsorigin et destination de la réponse d’expédition contiennent des objets d’adresse résolus avec la structure suivante :
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 champpickup 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 tableaustatus_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.nullquand 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). Jamaiscancelled— une annulation vient de nous, pas du transporteur.code— le code de statut propre au transporteur (GO10,GO90,GOY001chez GO! ;VA,ZF,LA,ZUchez DHL).nullquand le transporteur n’en fournit pas. Stable quelle que soit la langue destatus.detail_code— le code plus précis du transporteur lorsqu’il en existe un :statusDetailedchez 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é).nullsinon.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.nullquand 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).
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 :
pending jusqu’à ce que le patient poste l’échantillon — c’est l’état réel, pas une anomalie.