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

# Créer une expédition

> Créer une commande d'expédition logistique avec l'origine et la destination indiquées

Crée une commande d'envoi depuis le site d'origine indiqué. Tu indiques le laboratoire de destination avec `destination_lab`. L'envoi est expédié à l'adresse de livraison enregistrée pour ce laboratoire.

Nécessite le scope `shipments_manage`.

Envoie un en-tête facultatif `Idempotency-Key` pour pouvoir relancer cette création sans risque — répéter la même clé renvoie la réponse d'origine au lieu d'en créer un second. Voir [Idempotence](https://docs.anivahealth.com/fr/concepts/idempotency.md).

## Requête

### Paramètres du corps

**location\_id** `string` *required*

UUID du site de test d'origine. Le site doit être actif et faire partie du contexte d'accès de ta clé API.
Utilise [Lister les sites](https://docs.anivahealth.com/fr/api/locations/list-locations.md) pour trouver les ID de site disponibles.

**destination\_lab** `string` *required*

Laboratoire de destination. Valeur parmi `zotzklimas`, `labclinic`, `nordicgroup`, `biomes`, `imd` ou
`quade`. L'envoi est expédié à l'adresse de livraison enregistrée pour ce laboratoire. Un laboratoire
sans adresse de livraison enregistrée renvoie `400`.

**appointment\_id** `string`

UUID facultatif d'un rendez-vous auquel associer cet envoi dès sa création. Le rendez-vous doit
faire partie du contexte d'accès de ta clé API. Le lien apparaît directement comme une entrée dans le
tableau `appointments` de l'envoi, et inversement comme une entrée dans le tableau `shipments` du rendez-vous. Pour associer
d'autres rendez-vous après la création, ou retirer le lien initial, utilise [Associer des rendez-vous à
un envoi](https://docs.anivahealth.com/fr/api/shipments/attach-appointments-to-shipment.md) et [Dissocier des rendez-vous d'un
envoi](https://docs.anivahealth.com/fr/api/shipments/detach-appointments-from-shipment.md).

**pickup\_date** `string` *required*

Date de collecte au format `YYYY-MM-DD` (par ex. `2026-04-15`), interprétée dans le fuseau horaire du site
d'origine. Doit être un jour ouvré (lundi–vendredi), aujourd'hui ou dans le futur. Les collectes le jour même ne sont plus
disponibles après 16:00 Europe/Berlin.

**pickup\_time\_from** `string` *required*

Heure de collecte au plus tôt au format `HH:MM` (par ex. `09:00`), interprétée comme l'heure locale dans le
fuseau horaire du site d'origine. Doit être comprise entre `09:00` et `19:00`.

**pickup\_time\_till** `string` *required*

Heure de collecte au plus tard au format `HH:MM` (par ex. `12:00`), interprétée comme l'heure locale dans le fuseau
horaire du site d'origine. Doit être comprise entre `09:00` et `19:00`. Le créneau (`pickup_time_till -
    pickup_time_from`) doit durer au moins 2 heures.

**package\_count** `integer` (default: 1)

Nombre de colis. Valeur par défaut : `1`.

**weight** `number` (default: 0.5)

Poids en kg. Valeur par défaut : `0.5`.

**pickup\_remarks** `string`

Instructions pour le coursier lors de la collecte (remarques de l'expéditeur). En cas d'omission, les remarques
enregistrées sur l'adresse de collecte sont utilisées (ou aucune si l'adresse n'en comporte pas). 128 caractères maximum.

**contents** `string`

Description libre du contenu du colis, affichée au coursier et renvoyée dans
`contents`. 40 caractères maximum (par ex. `Medizinisch freigestellte Probe`).

**notes** `string`

Notes internes facultatives. 128 caractères maximum.

## Réponse

En cas de succès, l'API renvoie `201 Created` avec le nouvel envoi.

**id** `string` *required*

Identifiant de référence de l'envoi (par ex. `P2604151234`).

**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 que fournie à la création. Peut être `null`.

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

Qui a imprimé l'étiquette : `aniva` ou `external`. Un envoi que tu crées a la valeur `aniva`.

**paired\_with** `string`

Référence de l'autre colis d'un envoi en deux colis. `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 provenant du prestataire logistique (du plus ancien au plus récent). Chaque entrée contient
`state`, `code`, `detail_code`, `status`, `description`, `location` et `time`. Voir [Récupérer
un envoi](https://docs.anivahealth.com/fr/api/shipments/get-shipment.md) pour chaque champ. Tableau vide immédiatement après la création.
La synchronisation en arrière-plan ajoute les événements à mesure que le prestataire les signale.

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

Rendez-vous associé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 [Récupérer un rendez-vous](https://docs.anivahealth.com/fr/api/appointments/get-appointment.md).
Contient le rendez-vous transmis via `appointment_id` (le cas échéant) immédiatement après la création.

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

Commandes de kit à domicile associées à cet envoi, au même format `{ id, added_at }`. Tableau vide pour un
envoi que tu crées.

**synced\_at** `string`

Date et heure de la dernière synchronisation de l'envoi avec son transporteur, en temps UTC. `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`.

## Réponses d'erreur

| Statut | Description |
| - | - |
| `400` | Erreur de validation — par ex. format de date invalide, date un week-end, créneau de collecte trop court ou heure limite du jour même dépassée. Également renvoyée lorsque `destination_lab` ou le site d'origine n'a pas d'adresse enregistrée. |
| `403` | Accès refusé — ta clé API n'a pas accès à cette opération ou le site est hors de ton contexte d'accès. |
| `404` | Site introuvable ou inactif, ou `appointment_id` a été fourni mais le rendez-vous n'existe pas. |
| `409` | La clé `Idempotency-Key` a déjà été utilisée avec un autre corps de requête, ou sa requête d'origine n'est pas encore terminée. |
| `500` | Erreur interne du serveur. |
| `502` | Le prestataire logistique a rejeté la requête. Inclut le message d'erreur du prestataire. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/shipments \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "destination_lab": "labclinic",
    "appointment_id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "pickup_date": "2026-04-15",
    "pickup_time_from": "09:00",
    "pickup_time_till": "12:00",
    "notes": "Handle with care — temperature-sensitive samples"
  }'
```

```json 201 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-15T07:00:00Z"
    }
  ],
  "home_kit_orders": [],
  "synced_at": null,
  "created_at": "2026-04-15T07:00:00Z",
  "updated_at": null
}
```

```json 400 theme={null}
{
  "error": "pickup_date must be a weekday (Monday–Friday)"
}
```

```json 404 theme={null}
{
  "error": "Location not found or inactive"
}
```

```json 502 theme={null}
{
  "error": "Logistics provider error: Pickup on weekend/holiday not possible",
  "logistics_error_code": 2001
}
```


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