Passer au contenu principal
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.

Champs

string
requis
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.
string
requis
L’UUID du profil auquel appartient ce rendez-vous.
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.
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).
string
requis
Statut actuel du cycle de vie. L’une des valeurs pending, confirmed, blood_drawn ou cancelled. Voir 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 ; 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.
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.
string[]
requis
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.
string
requis
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. Après la prise de sang, c’est la méthode qui a été utilisée.
string
requis
Horodatage ISO 8601 de création du rendez-vous.
string
Horodatage ISO 8601 de la dernière mise à jour. Null si le rendez-vous n’a jamais été mis à jour.
string[]
requis
Codes de laboratoire (codes-barres des tubes) enregistrés lors de Confirmer la prise de sang, 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.
object[]
requis
Panels associés à ce rendez-vous, sous forme d’entrées { panel_id, added_at }. Voir Ajouter des panels.
object[]
requis
Biomarqueurs à la carte associés à ce rendez-vous, sous forme d’entrées { biomarker_id, added_at }. Voir Biomarqueurs individuels.
object[]
requis
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.
object
requis
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 les liste tous.

Cycle de vie

Les rendez-vous exposent quatre états de cycle de vie :
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 — 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 — chaque expédition dispose de son propre status et d’un journal d’événements status_updates.
Chaque changement de statut envoie un webhook appointment.*, par exemple appointment.confirmed. Un nouvel horaire ou un nouveau site envoie appointment.rescheduled.
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 :
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 :
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 et Mettre à jour un rendez-vous 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.
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 :
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.
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 :
Passe un tableau d’UUID de panels dans le champ panel_ids. Les identifiants de panels sont fournis par Aniva pour ton compte partenaire.
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 :
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é.
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) :
Retire des biomarqueurs (idempotent — les biomarqueurs qui ne sont pas associés sont ignorés) :
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 pour trouver les identifiants des biomarqueurs.
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 :
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), 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.
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 :
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

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 — 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 / Obtenir un rendez-vous) 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. Après la création, gère les liens depuis l’envoi avec Associer des rendez-vous à un envoi et Dissocier des rendez-vous d’un envoi ; 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 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 :
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 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