> ## 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 commande de kit à domicile

> Demander un kit d'autotest envoyé à domicile pour un profil

Demande une commande de kit à domicile pour un profil patient. Une commande de kit à domicile envoie un kit de test à faire soi-même par courrier — Aniva expédie le kit à l'adresse de livraison, le patient prélève son échantillon chez lui et le renvoie par courrier. Cela se distingue d'un [rendez-vous](https://docs.anivahealth.com/fr/api/appointments/create-appointment.md), qui consiste en une prise de sang veineuse sur un lieu de test.

**Un seul panel exactement est requis.** Un kit à domicile correspond 1 pour 1 à un kit physique — le panel est le kit — et la commande rejoint la file de préparation dès sa création, donc sa composition doit être définitive dès le départ. Tu peux encore changer de panel via [Mettre à jour une commande de kit à domicile](https://docs.anivahealth.com/fr/api/home-kit-orders/update-home-kit.md) tant que la commande est `pending`.

## Kits de remplacement

Lorsqu'un kit ne peut pas fournir ses résultats — le patient n'a pas pu remplir le tube, l'échantillon est arrivé avec trop peu de matériel, le laboratoire n'a pas pu l'analyser — commande un **remplacement** en envoyant `replaces_home_kit_order_id`.

Un remplacement est une nouvelle commande avec un nouveau code laboratoire, même lorsque le premier kit n'a jamais été activé : le laboratoire a besoin d'une nouvelle demande d'analyse, et deux échantillons portant le même code ne peuvent pas être distingués. La commande que tu remplaces n'est pas modifiée — elle conserve son propre statut, son propre code laboratoire et tous les résultats déjà enregistrés sous cette commande.

Deux choses en découlent :

* **Le panel est hérité.** Ne renseigne pas `panel_id` et le remplacement reprend le panel de la commande qu'il remplace, soit ce que le patient a acheté et l'habillage de la boîte.
* **Tu choisis ce qui est réanalysé.** Envoie `biomarker_ids` avec les marqueurs qui ont échoué et le laboratoire ne réanalyse que ceux-là, pour que le kit n'envoie que les tubes nécessaires. Ne le renseigne pas pour réanalyser tout le panel.

Les marqueurs sont réanalysés par groupes du panel, pas un par un. Indiquer un marqueur d'un groupe réanalyse tout ce groupe, car une commande laboratoire qui renvoie plus que ce qui a été demandé ne peut pas être passée. Un remplacement pour un seul marqueur peut donc arriver avec plusieurs résultats, et son nombre de tubes peut être supérieur à ce que la liste des marqueurs laisse penser.

Un seul remplacement par kit peut être en route à la fois.

> [!NOTE]
>
> Si tu as intégré l'API avant l'existence de ces champs, Aniva lit aussi `metadata.original_kit_id` et
> `metadata.replacement_reason` lors d'une création et traite la commande comme un remplacement. C'est le seul
> endroit où les métadonnées sont interprétées, il existe uniquement pour maintenir cette ancienne intégration, et les champs
> ci-dessus l'emportent toujours. Envoie les champs.

Un `201` signifie que la commande est validée et va être transmise à la logistique — tu n'as rien d'autre à faire pour que le kit soit préparé et expédié.

Requiert le scope `home_kit_orders_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

**profile\_id** `string` *required*

UUID du profil patient pour lequel créer la commande de kit à domicile.

**panel\_id** `string` *required*

UUID du panel du catalogue à commander. Un seul exactement — un kit à domicile correspond 1 pour 1 à un kit physique,
donc le panel est le kit. Les identifiants de panel sont fournis par Aniva pour ton compte partenaire ; voir [Lister
les panels](https://docs.anivahealth.com/fr/api/panels/list-panels.md). Facultatif pour un remplacement, où il reprend par défaut le panel de la
commande que tu remplaces.

**replaces\_home\_kit\_order\_id** `string`

UUID de la commande de kit à domicile que celle-ci remplace. L'envoyer en fait un kit de remplacement — voir
[Kits de remplacement](#kits-de-remplacement) ci-dessus. La commande doit appartenir au même profil et ne doit
pas déjà avoir un remplacement en route.

**replacement\_reason** `string`

Raison du remplacement, en une phrase (par exemple `Zu wenig Material, HbA1c nicht
    auswertbar`). Requis lorsque tu envoies `replaces_home_kit_order_id`, et ignoré sinon. 500 caractères
maximum.

**biomarker\_ids** `integer[]`

Pour un remplacement, les marqueurs que le laboratoire réanalyse — normalement ceux que le premier kit n'a pas pu
fournir. Chacun doit faire partie de ce que demandait la commande que tu remplaces ; vérifie la correspondance avec [Lister
les biomarqueurs](https://docs.anivahealth.com/fr/api/biomarkers/list-biomarkers.md) avec `home_kit=true`. Ne le renseigne pas pour réanalyser tout le panel. Accepté
uniquement avec `replaces_home_kit_order_id`, et jamais avec un `panel_id` différent.
Cela ne nécessite aucun scope supplémentaire : réanalyser des marqueurs que le patient a déjà payés n'est pas une sélection
à la carte.

**metadata** `object`

Tes propres paires clé/valeur, renvoyées telles quelles à chaque lecture et jamais interprétées par Aniva. Utilise
ce champ pour transmettre ta référence de commande et faire le lien sans stocker nos identifiants. 20 clés maximum ;
les clés correspondent à `[A-Za-z0-9_-]` et font 40 caractères maximum ; les valeurs sont des chaînes, des nombres ou des booléens,
avec des chaînes de 500 caractères maximum ; 16 384 octets sérialisés au total. Les clés commençant par `aniva_` sont
réservées. Ne mets jamais de données personnelles ou cliniques dans `metadata` — ce champ n'est pas traité comme des données patient.

**results\_ready\_emails** `string[]`

Jusqu'à 5 adresses qui reçoivent chacune un e-mail dès que tous les résultats de laboratoire sont
définitifs. L'e-mail renvoie vers la page des résultats dans le panneau d'administration Aniva.
Ta clé doit disposer de l'accès `results_view` pour le patient, sinon `403`. Omets ce champ pour
utiliser les adresses par défaut définies pour le groupe du patient. Une liste vide désactive les
e-mails. Voir [E-mails de résultats prêts](https://docs.anivahealth.com/fr/concepts/results.md#e-mails-de-resultats-prets).

**delivery\_address** `object` *required*

L'adresse à laquelle envoyer le kit — sous l'une des deux formes suivantes : soit `{ location_id }` référençant un lieu de test connu, soit les champs d'adresse intégrés (`name`, `street`, `city`, `postal_code`, `country_code` ; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` facultatifs — le même vocabulaire que l'API des lieux). Fournis exactement une des deux options — une référence de lieu ou une adresse intégrée, pas les deux.

**adresse de livraison**

> [tab] Référencer un lieu
>
> **location\_id** `string` *required*
>
> UUID d'un lieu de test connu où expédier le kit. À mettre en correspondance avec [Lister
> les lieux](https://docs.anivahealth.com/fr/api/locations/list-locations.md).

> [tab] Adresse intégrée
>
> **name** `string` *required*
>
> Nom du destinataire, de l'entreprise ou du lieu.
>
> **company\_name** `string`
>
> Entreprise qui réceptionne le colis pour le destinataire — un tiers `c/o` ou un service.
>
> **street** `string` *required*
>
> Nom de la rue, sans le numéro (par ex. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Numéro de rue (par ex. `118` ou `12a`).
>
> **address\_line\_2** `string`
>
> Bâtiment, entrée ou étage.
>
> **city** `string` *required*
>
> **state** `string`
>
> État ou province. Facultatif.
>
> **postal\_code** `string` *required*
>
> Code postal. Une adresse allemande (`country_code` `DE`) doit comporter exactement 5 chiffres, par ex. `10117`.
>
> **country\_code** `string` *required*
>
> Code ISO 3166-1 alpha-2 (deux lettres, par ex. `DE`). Les minuscules sont acceptées et stockées en
> majuscules.
>
> **phone** `string`
>
> Numéro de téléphone du destinataire, avec l'indicatif pays (par ex. `+4791234567`). Le transporteur l'utilise pour
> informer le destinataire au sujet du colis, par exemple qu'il l'attend en point relais. Ne le renseigne
> pas et le transporteur ne reçoit aucun numéro de téléphone.
>
> **email** `string`
>
> E-mail du destinataire. Le transporteur l'utilise comme `phone`. Ne le renseigne pas et le transporteur ne reçoit aucun
> e-mail.

> [!NOTE]
>
> **Packstation ou Postfiliale (Allemagne uniquement) :** définis `street` sur `Packstation` ou `Postfiliale`,
> `house_number` sur le numéro de station à trois chiffres, et `address_line_2` sur le DHL
> Postnummer du destinataire (6 à 10 chiffres, espaces autorisés). Sans le Postnummer, le colis ne peut pas être enregistré.
> Un Postfach n'est pas pris en charge.

## Réponse

En cas de succès, l'API renvoie `201 Created` avec la nouvelle commande de kit à domicile.

**id** `string` *required*

Identifiant unique de la commande de kit à domicile (UUID).

**profile\_id** `string` *required*

UUID du profil auquel appartient cette commande de kit à domicile.

**status** `string` *required*

Statut actuel de la commande de kit à domicile. L'une des valeurs `pending`, `dispatched`, `activated` ou `cancelled`. Une
commande nouvellement créée démarre à `pending`.

**delivery\_address** `object` *required*

L'adresse à laquelle envoyer le kit — deux formats possibles : soit `{ location_id }` faisant référence à un lieu de test connu, soit les champs d'adresse directe (`name`, `street`, `city`, `postal_code`, `country_code` ; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` facultatifs — le même vocabulaire que l'API des lieux). Indique exactement un format — une référence de lieu ou une adresse directe, pas les deux.

**adresse de livraison**

> [tab] Référence de lieu
>
> **location\_id** `string` *required*
>
> UUID du lieu de test auquel le kit est expédié.

> [tab] Adresse directe
>
> **name** `string` *required*
>
> Nom du destinataire, de l'entreprise ou du lieu.
>
> **company\_name** `string`
>
> Entreprise qui réceptionne le colis pour le destinataire — un tiers `c/o` ou un service.
>
> **street** `string` *required*
>
> Nom de la rue, sans le numéro (par ex. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Numéro de rue (par ex. `118` ou `12a`).
>
> **address\_line\_2** `string`
>
> Bâtiment, entrée ou étage.
>
> **city** `string` *required*
>
> **state** `string`
>
> État ou province. Facultatif.
>
> **postal\_code** `string` *required*
>
> **country\_code** `string` *required*
>
> Code ISO 3166-1 alpha-2 (deux lettres, par ex. `DE`).
>
> **phone** `string`
>
> **email** `string`

**metadata** `object` *required*

Les paires clé/valeur que tu as fournies. Toujours présent — `{}` lorsque tu n'en définis aucune.

**replaces\_home\_kit\_order\_id** `string`

La commande de kit à domicile que celle-ci remplace. `null` sur une commande normale.

**replacement\_reason** `string`

La raison que tu as fournie. `null` sur une commande normale.

**results\_ready\_emails** `string[]` *required*

Adresses en minuscules qui reçoivent chacune un e-mail une fois tous les résultats de laboratoire
définitifs. Vide si désactivé. Voir [E-mails de résultats prêts](https://docs.anivahealth.com/fr/concepts/results.md#e-mails-de-resultats-prets).

**lab\_code** `string`

Code d'échantillon de laboratoire sous lequel les résultats sont enregistrés — imprimé sur le kit physique, et que le
patient lit sur la boîte comme code d'activation. `null` tant que le kit n'est pas emballé.
En lecture seule.

**activated\_at** `string` *required*

Horodatage du prélèvement transmis via [Activer](https://docs.anivahealth.com/fr/api/home-kit-orders/activate-home-kit.md). `null` tant que
le kit n'est pas activé.

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

Horodatage ISO 8601 de la création de la commande de kit à domicile.

**updated\_at** `string`

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

**profile** `object` *required*

Le profil patient associé à cette commande de kit à domicile.

**Profil**

**id** `string`

Identifiant unique du profil (UUID).

**handle** `string`

Pseudonyme ou nom d'utilisateur du profil. Peut être `null`.

**first\_name** `string`

Prénom. Peut être `null`.

**last\_name** `string`

Nom de famille. Peut être `null`.

**email** `string`

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

**phone** `string`

Numéro de téléphone au format E.164. Peut être `null`.

**sex** `integer`

Sexe biologique selon la norme ISO/IEC 5218. Peut être `null`.

**date\_of\_birth** `string`

Date de naissance au format `YYYY-MM-DD`. Peut être `null`.

**height** `number`

Taille en centimètres. Peut être `null`.

**weight** `number`

Poids en kilogrammes. Peut être `null`.

**language** `string`

Langue préférée : l'un des 32 codes listés dans [Créer un profil](https://docs.anivahealth.com/fr/api/profiles/create-profile.md).

**transactional\_emails\_enabled** `boolean`

Indique si ce profil reçoit des e-mails transactionnels (automatisés). Peut être `null`.

**created\_at** `string`

Horodatage ISO 8601 de création du profil.

**updated\_at** `string`

Horodatage ISO 8601 de la dernière mise à jour du profil. Peut être `null`.

**panels** `HomeKitOrderPanel[]` *required*

Le panel rattaché à cette commande de kit à domicile — celui que tu as fourni dans `panel_id`, horodaté avec l'heure
de création de la commande. Toujours un seul exactement. Consulte les détails du panel (nom, biomarqueurs) via
[Lister les panels](https://docs.anivahealth.com/fr/api/panels/list-panels.md).

**Champs d'association du panel**

**panel\_id** `string`

UUID du panel — à croiser avec [Lister les panels](https://docs.anivahealth.com/fr/api/panels/list-panels.md).

**added\_at** `string`

Horodatage ISO 8601 de la première association du panel à cette commande de kit à domicile.

**individual\_biomarkers** `HomeKitOrderIndividualBiomarker[]` *required*

Biomarqueurs ajoutés en dehors du panel. Vide lors d'une création normale — les commandes de kit à domicile se font par
panel, et modifier cette liste par la suite nécessite le
scope de capacité `home_kit_orders_individual_biomarker_selection`. Sur un remplacement, ce champ contient les
`biomarker_ids` que tu as envoyés, qui correspondent à ce que le laboratoire réanalyse.

**Champs de biomarqueur individuel**

**biomarker\_id** `integer`

Identifiant du biomarqueur — à croiser avec
[Lister les biomarqueurs](https://docs.anivahealth.com/fr/api/biomarkers/list-biomarkers.md) avec `home_kit=true`.

**added\_at** `string`

Horodatage ISO 8601 de la première association du biomarqueur à cette commande de kit à domicile.

**shipments** `HomeKitOrderShipmentLink[]` *required*

Colis liés à cette commande de kit à domicile, du lien le plus ancien au plus récent. Toujours vide à la création — consulte les
colis complets avec [Lister les expéditions](https://docs.anivahealth.com/fr/api/shipments/list-shipments.md) et `?home_kit_order_id=`.

**Champs de lien d'expédition**

**id** `string`

Référence d'expédition — à croiser avec [Obtenir une expédition](https://docs.anivahealth.com/fr/api/shipments/get-shipment.md).

**added\_at** `string`

Horodatage ISO 8601 du lien entre l'expédition et cette commande de kit à domicile.

## Réponses d'erreur

| Statut | Description |
| - | - |
| `400` | Erreur de validation — par ex. il manque un champ dans `delivery_address` ou son code postal allemand ne comporte pas 5 chiffres, `panel_id` n'est pas un UUID valide, ou `replacement_reason` manque sur un remplacement. |
| `403` | Accès refusé — ta clé API n'a pas accès à cette opération, le profil est en dehors de ton périmètre d'autorisation, ou tu as défini `results_ready_emails` sans accès `results_view` au patient. |
| `404` | Profil, panel ou commande de kit à domicile à remplacer introuvable. |
| `409` | Conflit — la clé `Idempotency-Key` a déjà été utilisée avec un corps différent, sa requête initiale n'est pas terminée, ou le kit que tu remplaces a déjà un remplacement en route. |
| `422` | Le panel ne peut pas être commandé en kit à domicile — aucun kit physique n'est configuré pour lui. Sur un remplacement : la commande que tu remplaces appartient à un autre profil, une entrée de `biomarker_ids` ne fait pas partie de ce qu'elle demandait, ou tu as envoyé des marqueurs avec un `panel_id` différent. |
| `500` | Erreur interne du serveur. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/home-kit-orders \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
    "metadata": { "your_order_ref": "ORD-10482", "priority": true },
    "delivery_address": {
      "name": "Maria Schmidt",
      "company_name": "c/o Weber",
      "street": "Friedrichstraße",
      "house_number": "123",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE",
      "phone": "+4930123456789",
      "email": "maria.schmidt@example.com"
    }
  }'
```

```bash Replacement kit theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/home-kit-orders \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "replaces_home_kit_order_id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
    "replacement_reason": "Too little material, HbA1c could not be analysed",
    "biomarker_ids": [103],
    "metadata": { "your_order_ref": "ORD-10482-R1" },
    "delivery_address": {
      "name": "Maria Schmidt",
      "street": "Friedrichstraße",
      "house_number": "123",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE"
    }
  }'
```

```json 201 theme={null}
{
  "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "status": "pending",
  "delivery_address": {
    "name": "Maria Schmidt",
    "company_name": "c/o Weber",
    "address_line_2": null,
    "street": "Friedrichstraße",
    "house_number": "123",
    "postal_code": "10117",
    "city": "Berlin",
    "country_code": "DE",
    "phone": "+4930123456789",
    "email": "maria.schmidt@example.com"
  },
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": null,
  "profile": {
    "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "handle": null,
    "first_name": "Maria",
    "last_name": "Schmidt",
    "email": "maria.schmidt@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1985-03-22",
    "height": 168,
    "weight": 65,
    "language": "de",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:14:32Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T09:45:00Z"
    }
  ],
  "individual_biomarkers": [],
  "metadata": { "your_order_ref": "ORD-10482", "priority": true },
  "replaces_home_kit_order_id": null,
  "replacement_reason": null,
  "results_ready_emails": [],
  "lab_code": null,
  "activated_at": null,
  "shipments": []
}
```

```json 400 theme={null}
{
  "error": "panel_id: panel_id must be a valid UUID"
}
```

```json 404 theme={null}
{
  "error": "Profile not found"
}
```

```json 409 theme={null}
{
  "error": "Idempotency-Key \"ORD-10482\" was already used with a different request body. Use a new key for a different request, or resend the original body to read back its result."
}
```


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