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

# Lister les expéditions

> Récupérer les expéditions, filtrées par rendez-vous, commande de kit à domicile ou statut

Récupère les envois accessibles à ta clé API, du plus récent au plus ancien. Chaque colis figure dans cette seule liste :
une collecte par coursier depuis un cabinet, le kit en route vers un patient avec kit à domicile, et l'échantillon sur
le chemin du retour. Filtre sur un seul parent avec `appointment_id` ou `home_kit_order_id`.

Nécessite le scope `shipments_view` ou `shipments_manage`.

La réponse provient de notre base de données et n'appelle jamais le transporteur. Une synchronisation en arrière-plan actualise chaque
envoi (toutes les 10 minutes pour GO!, toutes les heures pour DHL) et `synced_at` sur chaque ligne t'indique quand le
transporteur a été interrogé pour la dernière fois.

## Requête

### Paramètres de requête

**appointment\_id** `string`

Uniquement les envois liés à ce rendez-vous (UUID). `404` quand le rendez-vous n'existe pas, `403`
quand il est en dehors de ton contexte d'accès.

**home\_kit\_order\_id** `string`

Uniquement les envois liés à cette commande de kit à domicile (UUID). En principe, deux lignes sont renvoyées — le kit en
route vers le patient et l'échantillon de retour au laboratoire (sa `destination` est le laboratoire). Mêmes
règles `404` / `403` que pour `appointment_id`.

**status** `string`

Uniquement les envois dans ce statut. Une valeur parmi `pending`, `in_transit`, `delivered`, `fault`, `cancelled`.

**limit** `integer`

Nombre maximal d'envois à renvoyer. Par défaut 100, maximum 500.

**offset** `integer`

Nombre d'envois à ignorer. Par défaut 0. Le tri est stable (`created_at` décroissant, puis
référence), de sorte que les pages ne se chevauchent pas.

## Réponse

En cas de succès, l'API renvoie `200 OK` avec un tableau d'objets envoi.

**id** `string` *required*

Identifiant de référence de l'envoi.

**status** `string` *required*

Statut du cycle de vie de l'envoi. Valeur parmi `pending`, `in_transit`, `delivered`, `fault` ou `cancelled`.

**logistics\_provider** `string` *required*

Prestataire logistique. L'une des valeurs `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` ou `dhl_express`. Un colis de kit à domicile utilise `dhl_parcel`, ou `dhl_warenpost` lorsqu'il part à l'étranger
en Warenpost International.

**tracking\_number** `string`

Numéro de suivi externe du prestataire logistique. Peut être `null`.

**contents** `string`

Description libre du contenu du colis, telle qu'indiquée à la création (par ex. `"Medizinisch
    freigestellte Probe"`, `"Home test kit"`). À titre informatif uniquement — pour savoir si un colis est destiné à un
laboratoire, consulte `destination`, et pour son pendant, consulte `paired_with`. Peut être `null`.

**booked\_by** `string` *required*

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 mais renvoie `501` pour les deux.

**paired\_with** `string`

Référence de l'autre colis d'une expédition de deux colis — le colis qui contenait une étiquette de
retour et le colis que cette étiquette renvoie. Défini sur les deux. `null` pour un colis aller simple.

**origin** `object`

Adresse d'enlèvement. Peut être `null`.

**objet adresse**

**name** `string` *required*

Nom du destinataire, de l'entreprise ou du lieu.

**company\_name** `string`

Ligne entreprise / chez (c/o). Peut être `null`.

**street** `string` *required*

Nom de la rue, sans le numéro.

**house\_number** `string`

Numéro de rue. Peut être `null`.

**address\_line\_2** `string`

Bâtiment, entrée ou étage. Peut être `null`.

**city** `string` *required*

Ville.

**state** `string`

État ou province. Peut être `null`.

**postal\_code** `string` *required*

Code postal.

**country\_code** `string` *required*

Code pays ISO 3166-1 alpha-2.

**phone** `string`

Numéro de téléphone de contact. Peut être `null`.

**email** `string`

Adresse e-mail de contact. Peut être `null`.

**destination** `object`

Adresse de livraison. Même structure que `origin`. Peut être `null`.

**pickup** `object`

Créneau de collecte programmé. Peut être `null`.

**Objet pickup**

**from** `string` *required*

Début du créneau de collecte en temps UTC (ISO 8601 avec suffixe `Z`).

**till** `string` *required*

Fin du créneau de collecte en temps UTC (ISO 8601 avec suffixe `Z`).

**timezone** `string` *required*

Fuseau horaire IANA du lieu de collecte (par ex. `Europe/Berlin`). Permet d'afficher `from` / `till` à l'heure locale du lieu de collecte.

**notes** `string`

Notes facultatives. Peut être `null`.

**status\_updates** `object[]` *required*

Événements chronologiques du cycle de vie fournis par le prestataire logistique (du plus ancien au plus récent). Tableau vide si le
prestataire n'a encore signalé aucun événement. Utilise ce champ pour l'affichage par événement, l'audit et les signaux fins du
transporteur ; appuie-toi sur `status` pour l'état actuel de référence.

**champs de mise à jour du statut**

**state** `string | null` *required*

L'événement dans le vocabulaire des statuts d'envoi — `pending`, `in_transit`, `delivered` ou
`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 de ce champ). Jamais `cancelled`.

**code** `string | null` *required*

Le code de statut propre au transporteur : `GO10` / `GO90` / `GOY001` pour GO!, `VA` / `ZF` / `LA`
/ `ZU` pour DHL. `null` quand le transporteur n'en a fourni aucun. Stable quelles que soient les traductions de
`status`.

**detail\_code** `string | null` *required*

Le code plus précis du transporteur lorsqu'il existe — le champ `statusDetailed` de DHL, par ex. `CNRFC_NRQRD_ZF`
(redirigé vers un bureau de poste), `HLDCC_SERPT_LA` (prêt à y être retiré), `DLVRD_SERPT_ZU`
(retiré). `null` pour les transporteurs qui n'en ont pas.

**status** `string` *required*

Libellé de statut fourni par le prestataire (texte libre, par ex. `"Shipment picked up"`,
`"Die Sendung wurde abgeholt."`).

**description** `string | null` *required*

Une explication du code, ou la phrase plus longue du transporteur. `null` quand aucun des deux n'existe.

**location** `string | null` *required*

L'endroit où le scan a eu lieu, tel que le transporteur le nomme — un dépôt GO! (`"HUB Niederaula"`) ou une
ville DHL. Texte libre, pas une coordonnée. `null` quand le transporteur n'en a signalé aucun.

**time** `string` *required*

Heure à laquelle l'événement a été observé (ISO 8601, avec le décalage horaire indiqué par le transporteur).

**appointments** `ShipmentAppointmentLink[]` *required*

Rendez-vous liés à cet envoi, du lien le plus ancien au plus récent. Chaque entrée a la forme `{ id, added_at }` ;
recoupe chaque `id` avec [Obtenir un rendez-vous](https://docs.anivahealth.com/fr/api/appointments/get-appointment.md) pour obtenir
l'objet complet du rendez-vous. Tableau vide lorsqu'aucun rendez-vous n'est lié.
Seuls les rendez-vous de ton contexte d'accès sont listés.

**home\_kit\_orders** `ShipmentHomeKitOrderLink[]` *required*

Commandes de kit à domicile liées à cet envoi, du lien le plus ancien au plus récent, au même format `{ id, added_at }`.
Recoupe chaque `id` avec [Obtenir une commande de kit à domicile](https://docs.anivahealth.com/fr/api/home-kit-orders/get-home-kit.md). Tableau
vide pour les colis de cabinet. Seules les commandes de ton contexte d'accès sont listées. Voir
[Accès](https://docs.anivahealth.com/fr/concepts/shipments.md#acces).

**synced\_at** `string`

Moment de la dernière synchronisation de l'envoi avec son transporteur, en UTC. Les lectures n'appellent jamais le
transporteur — une synchronisation en arrière-plan garde les envois à jour — ce champ indique donc l'ancienneté de la réponse. `null` jusqu'à
la première synchronisation.

**created\_at** `string` *required*

Horodatage de création (ISO 8601).

**updated\_at** `string`

Horodatage de dernière mise à jour (ISO 8601). Peut être `null`.

## Appels répétés

Aniva conserve la réponse de ce point de terminaison pendant 5 minutes pour chaque clé API. Un appel répété pendant
ce délai reçoit la réponse conservée. Les en-têtes `Cache-Status` et `Age` indiquent que la réponse est
conservée et depuis combien de temps.

Pour être informé d'un changement immédiatement, abonne-toi aux événements webhook `shipment.created` et `shipment.updated`.
Voir [Lectures répétées](https://docs.anivahealth.com/fr/concepts/webhooks.md#lectures-repetees).

## Réponses d'erreur

| Statut | Description |
| - | - |
| `400` | Paramètre de requête invalide. |
| `403` | Interdit — scope manquant, ou le rendez-vous / la commande de kit à domicile filtré est en dehors de ton périmètre. |
| `404` | Le rendez-vous ou la commande de kit à domicile filtré est introuvable. |
| `500` | Erreur interne du serveur. |

```bash cURL (all shipments, first page) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?limit=100&offset=0' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (one home-kit order) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?home_kit_order_id=d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (one appointment, in transit) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?appointment_id=c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a&status=in_transit' \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
[
  {
    "id": "P2611194821",
    "status": "in_transit",
    "logistics_provider": "go",
    "tracking_number": "GO1234567890",
    "contents": "Medizinisch freigestellte Probe",
    "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": null,
    "status_updates": [
      {
        "state": "in_transit",
        "code": "GO10",
        "detail_code": null,
        "status": "Shipment picked up",
        "description": "Picked up at the consignor",
        "location": "Berlin",
        "time": "2026-04-15T09:22:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "GO50",
        "detail_code": null,
        "status": "Receiving station",
        "description": null,
        "location": "HUB Niederaula",
        "time": "2026-04-15T11:18:00+02:00"
      }
    ],
    "appointments": [
      {
        "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
        "added_at": "2026-04-15T08:30:00Z"
      }
    ],
    "home_kit_orders": [],
    "synced_at": "2026-04-15T11:20:00Z",
    "created_at": "2026-04-14T16:00:00Z",
    "updated_at": "2026-04-15T11:20:00Z"
  }
]
```


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