> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anivahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Expéditions

> Fonctionnement de la logistique dans l'API Aniva : expéditions d'échantillons vers le laboratoire et colis de kits de test à domicile, avec suivi et statut.

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](https://docs.anivahealth.com/fr/api/shipments/get-shipment.md) 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](https://docs.anivahealth.com/fr/api/shipments/update-shipment.md) et [Annuler](https://docs.anivahealth.com/fr/api/shipments/cancel-shipment.md) ; 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](https://docs.anivahealth.com/fr/api/shipments/update-shipment.md), [Annuler](https://docs.anivahealth.com/fr/api/shipments/cancel-shipment.md), [Associer des rendez-vous](https://docs.anivahealth.com/fr/api/shipments/attach-appointments-to-shipment.md) et [Dissocier des rendez-vous](https://docs.anivahealth.com/fr/api/shipments/detach-appointments-from-shipment.md) 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](https://docs.anivahealth.com/fr/api/locations/list-locations.md) 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](https://docs.anivahealth.com/fr/api/appointments/get-appointment.md) /
[Récupérer un envoi](https://docs.anivahealth.com/fr/api/shipments/get-shipment.md)) 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](https://docs.anivahealth.com/fr/api/shipments/attach-appointments-to-shipment.md) /
[Dissocier des rendez-vous d'un envoi](https://docs.anivahealth.com/fr/api/shipments/detach-appointments-from-shipment.md). 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 :

```text theme={null}
pending → in_transit → delivered
              ↓
            fault
    ↓
 cancelled
```

| Statut | Signification |
| - | - |
| `pending` | La commande coursier a été passée et est en attente de collecte. |
| `in_transit` | Le coursier a récupéré le colis et il est en transit. |
| `delivered` | Le colis a été livré. |
| `fault` | Un problème est survenu pendant le transit, ou le transporteur a renvoyé le colis à l'expéditeur. |
| `cancelled` | L'expédition a été annulée. |

Chaque changement de statut envoie un [webhook](https://docs.anivahealth.com/fr/concepts/webhooks.md) `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.

| Règle | Détail |
| - | - |
| **Jours ouvrés uniquement** | `pickup_date` doit tomber entre lundi et vendredi. |
| **Aujourd'hui ou futur** | `pickup_date` ne peut pas être dans le passé. |
| **Heure limite le jour même** | Les collectes le jour même sont refusées après 16:00 Europe/Berlin. |
| **Plage horaire** | `pickup_time_from` et `pickup_time_till` doivent se situer entre 09:00 et 19:00. |
| **Créneau minimal de 2 h** | Le créneau de collecte doit durer au moins 2 heures. |

## 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](#regles-d-horaire-de-collecte).

> [!WARNING]
>
> 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`.

> [!WARNING]
>
> 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](https://docs.anivahealth.com/fr/concepts/idempotency.md).

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 :

| Lettre | Envoi |
| - | - |
| `P` | Un envoi que tu crées via cette API. |
| `M` | Un envoi créé par l'équipe Aniva. |
| `C` | Un envoi de l'expédition quotidienne d'Aniva. |
| `K` | Un colis de kit à domicile. |
| `F`, `S` | Les propres colis de stock d'Aniva. |

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 :

```json theme={null}
{
  "name": "Aniva Berlin Mitte",
  "company_name": null,
  "street": "Unter den Linden",
  "house_number": "42",
  "address_line_2": null,
  "postal_code": "10117",
  "city": "Berlin",
  "state": null,
  "country_code": "DE",
  "phone": "+4930987654321",
  "email": "berlin-mitte@anivahealth.com"
}
```

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

```json theme={null}
{
  "id": "P2611194821",
  "status": "pending",
  "logistics_provider": "go",
  "tracking_number": null,
  "contents": null,
  "booked_by": "aniva",
  "paired_with": null,
  "origin": {
    "name": "Aniva Berlin Mitte",
    "company_name": null,
    "street": "Unter den Linden",
    "house_number": "42",
    "address_line_2": null,
    "postal_code": "10117",
    "city": "Berlin",
    "state": null,
    "country_code": "DE",
    "phone": "+4930987654321",
    "email": "berlin-mitte@anivahealth.com"
  },
  "destination": {
    "name": "LabClinic GmbH",
    "company_name": null,
    "street": "Laborstraße",
    "house_number": "10",
    "address_line_2": null,
    "postal_code": "80331",
    "city": "München",
    "state": null,
    "country_code": "DE",
    "phone": null,
    "email": null
  },
  "pickup": {
    "from": "2026-04-15T07:00:00Z",
    "till": "2026-04-15T10:00:00Z",
    "timezone": "Europe/Berlin"
  },
  "notes": "Handle with care — temperature-sensitive samples",
  "status_updates": [],
  "appointments": [
    {
      "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
      "added_at": "2026-04-03T14:30:00Z"
    }
  ],
  "home_kit_orders": [],
  "synced_at": null,
  "created_at": "2026-04-03T14:30:00Z",
  "updated_at": null
}
```

## 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 :

```json theme={null}
[
  {
    "id": "K2609041FQ7",
    "status": "in_transit",
    "logistics_provider": "dhl_parcel",
    "tracking_number": "00340434779457841299",
    "contents": "Home test kit",
    "booked_by": "aniva",
    "paired_with": "K260904P3XD",
    "origin": { "name": "Aniva Health", "street": "Wilhelmstraße", "house_number": "118", "postal_code": "10963", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "destination": { "name": "Jane Doe", "street": "Friedrichstraße", "house_number": "123", "postal_code": "10117", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "pickup": null,
    "notes": null,
    "status_updates": [
      {
        "state": "pending",
        "code": "VA",
        "detail_code": "PARCV_NRQRD_VA",
        "status": "Die Auftragsdaten zu dieser Sendung wurden vom Absender elektronisch an DHL übermittelt.",
        "description": "Electronic advice from DHL — not a parcel scan",
        "location": null,
        "time": "2026-09-02T18:17:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "ES",
        "detail_code": "SHRCU_SERPT_ES",
        "status": "Die Sendung wurde in der Filiale eingeliefert.",
        "description": "Shipment in transit",
        "location": "Berlin",
        "time": "2026-09-04T18:13:00+02:00"
      }
    ],
    "appointments": [],
    "home_kit_orders": [{ "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "added_at": "2026-09-02T18:20:00Z" }],
    "synced_at": "2026-09-05T10:00:00Z",
    "created_at": "2026-09-02T18:20:00Z",
    "updated_at": "2026-09-05T10:00:00Z"
  },
  {
    "id": "K260904P3XD",
    "status": "pending",
    "logistics_provider": "dhl_parcel",
    "tracking_number": "00340434850359000004",
    "contents": "Sample return to lab",
    "booked_by": "aniva",
    "paired_with": "K2609041FQ7",
    "origin": { "name": "Jane Doe", "street": "Friedrichstraße", "house_number": "123", "postal_code": "10117", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "destination": { "name": "Labor Quade", "street": "Laborstraße", "house_number": "10", "postal_code": "50667", "city": "Köln", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "pickup": null,
    "notes": null,
    "status_updates": [],
    "appointments": [],
    "home_kit_orders": [{ "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "added_at": "2026-09-02T18:20:00Z" }],
    "synced_at": "2026-09-05T10:00:00Z",
    "created_at": "2026-09-02T18:20:00Z",
    "updated_at": null
  }
]
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.