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

# Rendez-vous

> Fonctionnement des rendez-vous de prise de sang dans l'API d'analyses en laboratoire Aniva : réservation, panels, biomarqueurs, changements de statut et annulation.

Un rendez-vous est une prise de sang planifiée pour un profil patient sur un site de prélèvement physique, réalisée par un professionnel de santé. Les kits envoyés par courrier à un patient ne sont pas des rendez-vous — voir [Commandes de kits à domicile](https://docs.anivahealth.com/fr/concepts/home-kit-orders.md).

## Champs

**id** `string` *required*

UUID généré automatiquement par Aniva. Utilise-le pour ajouter des panels, confirmer la prise de sang et récupérer les résultats.

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

L'UUID du profil auquel appartient ce rendez-vous.

**location\_id** `string`

L'UUID du site de prélèvement où la prise de sang aura lieu. Les kits à domicile ne sont pas des rendez-vous — voir
[Commandes de kits à domicile](https://docs.anivahealth.com/fr/concepts/home-kit-orders.md).

**scheduled\_at** `string`

Date et heure prévues de la prise de sang au format ISO 8601. Toujours renvoyées en UTC avec le suffixe
`Z` (par ex. `2026-04-15T08:30:00Z`). À la création ou à la mise à jour, la valeur **doit inclure un indicateur
de fuseau horaire** (`Z` ou un décalage explicite comme `+02:00`) — les dates sans fuseau sont rejetées. Elle doit
être dans le futur, et au moins 12 heures à l'avance sur les sites gérés par Aniva ([délai
minimum](https://docs.anivahealth.com/fr/api/appointments/create-appointment.md#delai-minimum)).

**status** `string` *required*

Statut actuel du cycle de vie. L'une des valeurs `pending`, `confirmed`, `blood_drawn` ou `cancelled`. Voir
[Cycle de vie](#cycle-de-vie) ci-dessous. L'avancement détaillé des résultats de laboratoire (`in_progress` ou `completed`) provient
de [Récupérer les résultats](https://docs.anivahealth.com/fr/api/appointments/get-results.md) ; le suivi plus fin d'une expédition (en
transit, livrée, etc.) s'obtient en suivant chaque entrée du tableau intégré `shipments` vers
[Récupérer une expédition](https://docs.anivahealth.com/fr/api/shipments/get-shipment.md).

**cancellation\_reason** `string`

Motif en texte libre saisi lors de l'annulation du rendez-vous (par ex. absence, annulation tardive,
« Échec. À refaire »). `null` sauf si `status` vaut `cancelled`.

**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).

**draw\_method** `string` *required*

Méthode de prise de sang : `capillary` (au bout du doigt ou sur le haut du bras, dans des microtubes) ou `venous` (dans la veine,
dans des tubes). C'est la méthode définie par le rendez-vous, sinon le `default_draw_method` de son
[lieu](https://docs.anivahealth.com/fr/concepts/locations.md). Après la prise de sang, c'est la méthode qui a été utilisée.

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

Horodatage ISO 8601 de création du rendez-vous.

**updated\_at** `string`

Horodatage ISO 8601 de la dernière mise à jour. Null si le rendez-vous n'a jamais été mis à jour.

**lab\_codes** `string[]` *required*

Codes de laboratoire (codes-barres des tubes) enregistrés lors de [Confirmer la prise de sang](https://docs.anivahealth.com/fr/api/appointments/confirm-blood-draw.md),
dans l'ordre de scan. Vide jusqu'à confirmation de la prise de sang. Une prise de sang veineuse a un code imprimé sur chaque
tube ; une prise de sang capillaire a un code par microtainer. Les résultats et documents y font référence via
`lab_code`.

**panels** `object[]` *required*

Panels associés à ce rendez-vous, sous forme d'entrées `{ panel_id, added_at }`. Voir
[Ajouter des panels](#ajouter-des-panels).

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

Biomarqueurs à la carte associés à ce rendez-vous, sous forme d'entrées `{ biomarker_id, added_at }`. Voir
[Biomarqueurs individuels](#biomarqueurs-individuels).

**shipments** `object[]` *required*

Expéditions liées à ce rendez-vous, sous forme d'entrées `{ id, added_at }`, lien le plus ancien en premier. Voir
[Associer des expéditions](#lier-des-envois).

**profile** `object` *required*

L'objet profil complet du patient, intégré dans chaque réponse de rendez-vous. Les champs ci-dessous
en sont un sous-ensemble. [Récupérer un rendez-vous](https://docs.anivahealth.com/fr/api/appointments/get-appointment.md) les liste tous.

**propriétés**

**id** `string`

UUID du profil associé.

**first\_name** `string`

Prénom du patient.

**last\_name** `string`

Nom du patient.

**email** `string`

Adresse e-mail du patient.

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

Date de naissance au format `YYYY-MM-DD`.

**sex** `integer`

Sexe biologique selon la norme ISO/IEC 5218.

## Cycle de vie

Les rendez-vous exposent quatre états de cycle de vie :

```
pending → confirmed → blood_drawn
   │          │             │
   └──────────┴─────────────┴──→ cancelled
```

| Statut | Signification |
| - | - |
| `pending` | Le rendez-vous est planifié et en attente de confirmation. Peut être [mis à jour](https://docs.anivahealth.com/fr/api/appointments/update-appointment.md) ou [annulé](https://docs.anivahealth.com/fr/api/appointments/cancel-appointment.md). |
| `confirmed` | Le rendez-vous a été confirmé (par ex. par le cabinet), mais la prise de sang n'a pas encore eu lieu. Peut encore être mis à jour ou annulé. |
| `blood_drawn` | Les codes de laboratoire ont été envoyés via [Confirmer la prise de sang](https://docs.anivahealth.com/fr/api/appointments/confirm-blood-draw.md) et le pipeline de commande de laboratoire a été déclenché. Les panels sont figés et le rendez-vous ne peut plus être replanifié ni annulé. |
| `cancelled` | Le rendez-vous a été annulé. État final — aucune autre transition. |

> [!NOTE]
>
> Le statut du rendez-vous reste volontairement global — un suivi plus fin est exposé
> via des endpoints dédiés :
>
> * **Avancement des résultats de laboratoire** →
>   [Récupérer les résultats](https://docs.anivahealth.com/fr/api/appointments/get-results.md) — le champ `status` de premier niveau vaut `in_progress` ou
>   `completed`.
> * **Progression des expéditions** (en transit, livrées, etc.) → suis chaque entrée du tableau intégré
>   `shipments` du rendez-vous vers [Récupérer une expédition](https://docs.anivahealth.com/fr/api/shipments/get-shipment.md) — chaque
>   expédition dispose de son propre `status` et d'un journal d'événements `status_updates`.
>
> Chaque changement de statut envoie un [webhook](https://docs.anivahealth.com/fr/concepts/webhooks.md) `appointment.*`, par exemple
> `appointment.confirmed`. Un nouvel horaire ou un nouveau site envoie `appointment.rescheduled`.

> [!WARNING]
>
> Confirmer un rendez-vous (le faire passer à `blood_drawn`) est **irréversible**. Une fois que tu as envoyé le ou les
> codes de laboratoire, le pipeline de commande de laboratoire est déclenché et ne peut pas être annulé. Les mises à jour et annulations
> ne sont autorisées que lorsque le rendez-vous a le statut `pending` ou `confirmed`.

## Lister les rendez-vous

Récupère tous les rendez-vous accessibles avec ta clé API :

```
GET /api/v1/appointments
```

Tu peux passer `?profile_id={uuid}` pour filtrer sur un profil précis. Sans ce paramètre, une fenêtre temporelle par défaut (2 derniers mois à 1 mois à venir) s'applique.

## Mettre à jour un rendez-vous

Avant que la prise de sang soit confirmée, tu peux replanifier le rendez-vous ou changer le site de prélèvement :

```
PATCH /api/v1/appointments/{id}
```

Passe n'importe quelle combinaison de `scheduled_at`, `location_id`, `draw_method` et `results_ready_emails` pour la mise à jour. N'inclus que les champs que tu veux modifier.

## Méthode de prélèvement

Chaque rendez-vous a une `draw_method` : `capillary` (au bout du doigt ou en haut du bras, dans des microtainers) ou
`venous` (dans une veine, dans des tubes). Elle ne s'applique qu'à la prise de sang. Les échantillons d'urine, par écouvillon et les autres
échantillons non sanguins sont prélevés de la même manière quelle que soit la méthode.

Par défaut, il s'agit de la `default_draw_method` du site. Définis `draw_method` à la création ou à la mise à jour pour
utiliser une autre méthode, ou définis-la à `null` pour revenir à la valeur par défaut du site. Le site doit lister
la méthode dans `draw_methods` et les analyses réservées doivent être compatibles avec elle, sinon la requête
renvoie `400`. Tu ne peux plus la modifier après la prise de sang. Après la prise de sang, `draw_method` correspond à la
méthode qui a été utilisée.

## Un rendez-vous par profil, site et horaire

Un profil a au maximum un rendez-vous non annulé par paire `(location_id, scheduled_at)` — une
même personne ne peut pas faire deux prises de sang au même endroit au même moment, quel que soit le nombre de réservations simultanées que le
site accepte.

[Créer un rendez-vous](https://docs.anivahealth.com/fr/api/appointments/create-appointment.md) et
[Mettre à jour un rendez-vous](https://docs.anivahealth.com/fr/api/appointments/update-appointment.md) appliquent tous deux cette règle et renvoient `409` avec un
`appointment_id` pointant vers le rendez-vous déjà existant. Considère cette réponse comme une réservation déjà
existante plutôt que comme une erreur à réessayer : récupère, replanifie ou annule le rendez-vous indiqué.

En pratique, les créations répétées sont sûres. Une création que tu renvoies après un timeout réseau,
ou qu'un utilisateur déclenche deux fois, aboutit à un seul rendez-vous au lieu de deux — ce qui signifie aussi que tu
n'as jamais à réconcilier des réservations en double pour le même patient après coup.

> [!NOTE]
>
> Les modifications ne sont autorisées qu'avant la prise de sang — c'est-à-dire tant que le rendez-vous a le statut `pending` ou
> `confirmed`. Une fois le rendez-vous passé à `blood_drawn` ou `cancelled`, il ne peut plus
> être modifié. La seule exception est `results_ready_emails` : tu peux encore le modifier seul après la
> prise de sang.

## Annuler un rendez-vous

Annule un rendez-vous qui n'est plus nécessaire :

```
DELETE /api/v1/appointments/{id}
```

Cela passe le statut du rendez-vous à `cancelled`. Le rendez-vous annulé est renvoyé dans la réponse.

En option, envoie un `cancellation_reason` (jusqu'à 500 caractères) dans le corps de la requête pour enregistrer le motif. Il est
stocké sur le rendez-vous et renvoyé en tant que `cancellation_reason` lors des lectures ultérieures.

> [!NOTE]
>
> L'annulation n'est autorisée qu'avant la prise de sang — c'est-à-dire tant que le rendez-vous a le statut `pending` ou
> `confirmed`. Les rendez-vous déjà passés à `blood_drawn` ne peuvent pas être annulés.

## Ajouter des panels

Avant de confirmer la prise de sang, ajoute les panels de bilan sanguin que tu veux réaliser en appelant :

```
POST /api/v1/appointments/{id}/panels
```

Passe un tableau d'UUID de panels dans le champ `panel_ids`. Les identifiants de panels sont fournis par Aniva pour ton compte partenaire.

> [!NOTE]
>
> Les panels doivent être ajoutés avant la prise de sang — c'est-à-dire tant que le rendez-vous a le statut `pending` ou
> `confirmed`. Tu ne peux plus ajouter ni modifier de panels une fois que le rendez-vous est passé à
> `blood_drawn`.

## Retirer des panels

Si tu dois retirer des panels avant la prise de sang, appelle :

```
DELETE /api/v1/appointments/{id}/panels
```

Passe un tableau d'UUID de panels dans le champ `panel_ids`. Le retrait est idempotent : un panel qui n'est pas associé est ignoré.

> [!NOTE]
>
> Comme pour l'ajout de panels, le retrait n'est autorisé qu'avant la prise de sang — c'est-à-dire tant que le rendez-vous
> a le statut `pending` ou `confirmed`. Les panels ne peuvent plus être retirés une fois le rendez-vous passé à
> `blood_drawn`.

## Biomarqueurs individuels

Tu peux associer des biomarqueurs individuels à un rendez-vous comme analyses à la carte, en dehors de tout panel préétabli. C'est utile lorsqu'un praticien souhaite une sélection sur mesure plutôt qu'un ensemble prédéfini. Les biomarqueurs associés apparaissent dans la réponse du rendez-vous sous forme d'un tableau `individual_biomarkers` (au même niveau que `panels`). Les décisions de routage sont prises en aval par le pipeline logistique des commandes selon les correspondances par laboratoire de chaque biomarqueur.

Ajoute des biomarqueurs (idempotent — les biomarqueurs déjà associés sont conservés) :

```
PATCH /api/v1/appointments/{id}/biomarkers
```

Retire des biomarqueurs (idempotent — les biomarqueurs qui ne sont pas associés sont ignorés) :

```
DELETE /api/v1/appointments/{id}/biomarkers
```

Les deux endpoints prennent un tableau `biomarker_ids` et valident l'ensemble résultant par rapport aux règles de complétude de chaque laboratoire — une commande qui ne peut pas être passée proprement (par ex. un ratio CRP/HDL sans CRP ni HDL) renvoie `400` avec les biomarqueurs à ajouter et n'enregistre rien. Utilise [Lister les biomarqueurs](https://docs.anivahealth.com/fr/api/biomarkers/list-biomarkers.md) pour trouver les identifiants des biomarqueurs.

> [!NOTE]
>
> Comme pour la modification des panels, les biomarqueurs individuels ne peuvent être ajoutés ou retirés qu'avant la prise de sang
> — c'est-à-dire tant que le rendez-vous a le statut `pending` ou `confirmed`. Une fois le rendez-vous passé à
> `blood_drawn`, l'instantané personnalisé est figé.

## Prévisualiser les contenants requis

Après avoir ajouté des panels ou des biomarqueurs individuels, prévisualise les contenants physiques de prélèvement qui seront nécessaires à la collecte des échantillons :

```
GET /api/v1/appointments/{id}/preview
```

Le tableau `containers` de la réponse inclut le type, le nom, la couleur du bouchon, le volume, la référence fabricant et la quantité pour chaque contenant requis. Cela aide les praticiens à préparer le bon matériel avant la prise de sang. La réponse contient aussi un objet `pricing` — la facture globale du rendez-vous (les postes déclenchés, les panels associés et une ligne par biomarqueur livré, tarifés selon ta grille avec le prix public à côté ; voir [Tarification](https://docs.anivahealth.com/fr/concepts/pricing.md)), renseigné lorsque le rendez-vous comporte des analyses associées et que ta clé dispose du scope `prices_view`, sinon `null`. `routing` n'est volontairement jamais exposé et vaut toujours `null`.

> [!NOTE]
>
> L'aperçu reflète les panels et biomarqueurs actuellement associés. Si tu ajoutes ou retires des panels
> après la prévisualisation, appelle à nouveau l'endpoint de prévisualisation pour obtenir les contenants requis à jour.

## Confirmer la prise de sang

Après la prise de sang, envoie les codes laboratoire (codes-barres des tubes) pour déclencher le pipeline de commande au laboratoire :

```
POST /api/v1/appointments/{id}/confirm
```

Envoie `lab_code` lorsqu'un même code est imprimé sur chaque tube (prise de sang veineuse), ou `lab_codes` avec une entrée
par code — chacune indiquant les `panel_ids` qu'il couvre — lorsque chaque panel est prélevé dans ses propres tubes avec
son propre code (prise de sang capillaire). Chaque panel constitue alors sa propre demande de laboratoire sous son code. Les
codes sont renvoyés dans `lab_codes` sur le rendez-vous.

Lors d'une prise de sang capillaire, le prélèvement est réparti dans des microtainers. Les panels passent en premier, dans l'ordre de réservation. Les biomarqueurs
individuels remplissent ensuite l'espace libre des microtainers des panels. Quand ils ont besoin de plus d'espace, ils ouvrent
de nouveaux microtainers. Nous les répartissons équitablement. Chaque microtainer contient au maximum 150 µl de biomarqueurs
individuels. Les appels qui modifient les panels ou les biomarqueurs renvoient `400` lorsque l'ensemble résultant enfreint
cette règle.

Cela passe le statut du rendez-vous à `blood_drawn` et lance le traitement en laboratoire. Cette action est irréversible.

## Enlèvement d'un envoi

> [!WARNING]
>
> `POST /api/v1/appointments/pickup` a été **supprimé**, ainsi que le statut de rendez-vous
> `shipment_picked_up`. Il renvoie désormais `405 Method Not Allowed`, car le chemin bascule vers la
> route de rendez-vous par ID. Dans sa dernière phase, l'endpoint était un no-op qui acceptait l'appel sans
> rien faire ; sa suppression ne modifie donc aucun comportement sur lequel tu comptais.

Pour suivre la progression après la prise de sang, consulte chaque entrée du tableau `shipments` intégré au rendez-vous
via [Obtenir un envoi](https://docs.anivahealth.com/fr/api/shipments/get-shipment.md) — chaque envoi dispose de son propre `status`
et d'un historique `status_updates`.

## Lier des envois

Un rendez-vous peut être lié à un ou plusieurs envois (et inversement — la relation est
plusieurs-à-plusieurs). L'ensemble des liens actuels apparaît directement des deux côtés :

* sur le rendez-vous, sous forme d'un tableau `shipments` composé d'entrées `{ id, added_at }` ;
* sur l'envoi, sous forme d'un tableau `appointments` composé 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
([Obtenir un envoi](https://docs.anivahealth.com/fr/api/shipments/get-shipment.md) /
[Obtenir un rendez-vous](https://docs.anivahealth.com/fr/api/appointments/get-appointment.md)) pour la charge utile complète.

Les envois sont liés dès leur création via le champ `appointment_id` sur
[Créer un envoi](https://docs.anivahealth.com/fr/api/shipments/create-shipment.md). Après la création, gère les liens depuis l'envoi
avec [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) ; chacun renvoie
la liste des rendez-vous de cet envoi après modification. Pour lire en entier les colis d'un rendez-vous,
utilise [Lister les envois](https://docs.anivahealth.com/fr/api/shipments/list-shipments.md) avec `?appointment_id=`.

La règle de modification est la suivante : des liens peuvent être créés ou supprimés lorsque SOIT

* le rendez-vous a dépassé la prise de sang (`blood_drawn`), soit quand
* l'envoi a été créé il y a moins de 24 heures.

En dehors de cette fenêtre, le lien est verrouillé afin que les enregistrements historiques restent stables.

## Récupérer les résultats de laboratoire

Une fois que le laboratoire a traité les échantillons sanguins, récupère les résultats cliniques et génétiques :

```
GET /api/v1/appointments/{id}/results
```

La réponse inclut les analyses prévues (statut `planned`) en plus des résultats reçus, afin que tu puisses
suivre ce qui est encore en attente. Le champ `status` de premier niveau reste à `in_progress` jusqu'à la clôture
de chaque soumission, puis passe à `completed` (ou `fault` lorsqu'aucune n'a remonté de résultat) — utilise-le pour savoir si les
analyses du rendez-vous sont terminées. Un [webhook](https://docs.anivahealth.com/fr/concepts/webhooks.md) `appointment.results.completed`
te prévient quand cela arrive, tu n'as donc pas besoin d'interroger l'API régulièrement. Le tableau
`submissions` détaille cela par demande de laboratoire, chacune avec son `lab_code`. Chaque
résultat reçu et chaque document porte le `lab_code` sous lequel il a été enregistré. Les rapports de laboratoire au format PDF sont
référencés dans le tableau `documents` — utilise `GET /api/v1/documents/{id}` pour les télécharger.

## Exemple de rendez-vous

```json theme={null}
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "profile_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "location_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "scheduled_at": "2026-04-15T08:30:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": null,
  "profile": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "handle": null,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1990-06-15",
    "height": 170,
    "weight": 62,
    "language": "en",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:55:00Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T10:05:00Z"
    }
  ],
  "individual_biomarkers": [
    {
      "biomarker_id": 42,
      "added_at": "2026-04-01T10:07:00Z"
    }
  ],
  "shipments": [
    {
      "id": "P2611194821",
      "added_at": "2026-04-15T07:00:00Z"
    }
  ],
  "lab_codes": []
}
```


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