Passer au contenu principal
Une commande de kit à domicile envoie par courrier un kit de test à faire soi-même à un patient. Aniva expédie le kit, le patient prélève lui-même un échantillon chez lui et le renvoie par courrier. Cela se distingue d’un rendez-vous, qui est une prise de sang veineuse réalisée dans un lieu de test physique par un professionnel de santé.
Les endpoints des commandes de kit à domicile nécessitent le scope home_kit_orders_view (lecture) ou home_kit_orders_manage (écriture). Activer accepte aussi le scope plus restreint home_kit_orders_activate. Récupérer les résultats et Envoyer les résultats par e-mail nécessitent en plus results_view — les résultats de laboratoire et les documents sont toujours protégés par ce scope.

Champs

string
requis
UUID généré automatiquement par Aniva. Utilise-le pour mettre à jour la commande, changer son panel, l’activer, l’annuler et récupérer les résultats.
string
requis
L’UUID du profil auquel appartient cette commande de kit à domicile.
string
requis
Statut actuel du cycle de vie. L’une des valeurs pending, dispatched, activated ou cancelled. Voir Cycle de vie ci-dessous. Le détail d’avancement des résultats de laboratoire (in_progress ou completed) provient de Récupérer les résultats.
object
requis
L’adresse à laquelle envoyer le kit — deux formats possibles : soit {location_id} qui 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 — même vocabulaire que l’API des lieux). Fournis exactement l’un des deux — une référence de lieu ou une adresse directe, pas les deux.
Packstation ou Postfiliale (Allemagne uniquement) : définis street sur Packstation ou Postfiliale, house_number sur le numéro à trois chiffres de la station 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 réservé. Les boîtes postales (Postfach) ne sont pas prises en charge.
string
requis
Horodatage ISO 8601 de la création de la commande de kit à domicile.
string
Horodatage ISO 8601 de la dernière mise à jour. Null si la commande de kit à domicile n’a jamais été mise à jour.
object
L’objet profil complet du patient, inclus dans chaque réponse de commande de kit à domicile.
object[]
Le panel associé à la commande de kit à domicile — toujours exactement une entrée { panel_id, added_at }, car un kit à domicile correspond 1 pour 1 à un kit physique. Fais correspondre le panel_id avec Lister les panels.
object[]
Biomarqueurs associés à la commande de kit à domicile en dehors de son panel. Chaque entrée a la forme { biomarker_id, added_at }. Fais correspondre chaque biomarker_id avec Lister les biomarqueurs en filtrant avec home_kit=true. Sur une commande normale, ce sont des analyses à la carte en plus du panel ; sur un kit de remplacement, ce sont celles que le laboratoire réanalyse.
string
La commande de kit à domicile que celle-ci remplace, lorsqu’il s’agit d’un kit de remplacement. null sur une commande normale.
string
Raison de l’envoi du remplacement, en une phrase. null sur une commande normale.
string[]
Adresses qui reçoivent chacune un e-mail dès que tous les résultats de laboratoire sont définitifs, en minuscules. Toujours présent — vide si désactivé. Définis ce champ lors de Créer ou Mettre à jour. Voir E-mails de résultats disponibles.
object
Tes propres paires clé/valeur, renvoyées telles quelles et jamais interprétées par Aniva. Toujours présent en lecture — {} si tu n’en définis aucune. Au maximum 20 clés ; les clés respectent [A-Za-z0-9_-] et comptent au maximum 40 caractères ; les valeurs sont des chaînes, des nombres ou des booléens, avec 500 caractères maximum pour les chaînes ; 16 384 octets sérialisés au total. Les clés commençant par aniva_ sont réservées. Lors de Mettre à jour, les métadonnées sont fusionnées : les clés que tu omets sont conservées, une clé envoyée à null est supprimée et {} efface tout. La validation fonctionne en tout ou rien. Ne mets jamais de données personnelles ou cliniques dans metadata — ce champ n’est pas traité comme des données patient.
string
Le code d’échantillon du laboratoire. Un seul code, trois rôles : celui sous lequel les résultats de laboratoire sont reportés, celui imprimé sur le kit physique et celui que le patient lit sur la boîte comme code d’activation. Attribué lorsque le kit est emballé — null tant que la commande est pending, sauf après qu’Aniva réexpédie un kit (voir Cycle de vie). Toujours en lecture seule. Retrouve la commande correspondant à un kit en main avec GET /api/v1/home-kit-orders?lab_code=….
string
L’horodatage du prélèvement transmis via Activer — le moment où le patient a effectivement prélevé son échantillon, au format UTC. null tant que le kit n’est pas activé. C’est l’heure de prélèvement qui figure sur le rapport de laboratoire.
object[]
Les colis liés à cette commande, du plus ancien au plus récent, chacun au format { id, added_at } — le kit en route vers le patient et, pour les kits dont le retour est suivi, l’échantillon renvoyé au laboratoire, qui apparaissent dès l’impression des étiquettes. Vide tant que la commande est pending, sauf après qu’Aniva réexpédie un kit. Récupère tous les détails des colis en un seul appel avec GET /api/v1/shipments?home_kit_order_id={id} — voir Expéditions.

Cycle de vie

Les commandes de kit à domicile présentent quatre états de cycle de vie :
Quand Aniva réexpédie un kit perdu, la commande repasse à pending, mais garde son lab_code et ses colis précédents dans shipments. Le nouveau kit porte le même code. Une étiquette de retour inutilisée est placée dans le nouveau colis. Seule Aniva effectue ces deux transitions ; l’API ne les propose pas. Chaque transition envoie un webhook home_kit_order.pending ou home_kit_order.cancelled.
Les statuts d’une commande de kit à domicile restent volontairement globaux. Le suivi de livraison vers et depuis le patient se fait sur les envois de la commande — dispatched signifie que le kit a une étiquette et un code laboratoire, pas qu’il a bougé ; c’est le status de l’envoi aller qui l’indique. Le traitement des résultats du laboratoire se passe sur les soumissions. L’avancement des résultats (in_progress ou completed) est exposé via Obtenir les résultats — le champ status de premier niveau reste à in_progress jusqu’à la clôture de chaque soumission, puis passe à completed — ou à fault quand toutes les soumissions ont échoué sans renvoyer de résultats.

Suivre les colis

Ce qui est renvoyé dépend du kit. Un kit sanguin correspond à deux envois une fois emballé par Aniva : le colis d’Aniva vers le patient, et celui du patient vers le laboratoire (sa destination est le laboratoire), associés via paired_with. Le colis retour reste à pending — avec son numéro de suivi déjà connu — jusqu’à ce que le patient le poste. Un kit de microbiome intestinal correspond à un seul envoi : le kit vers le patient. Son enveloppe retour est prépayée et sans suivi, donc rien n’est réservé pour le retour. booked_by indique qui a réservé l’étiquette : "aniva" ou "external". Seul un colis "aniva" peut être modifié ici, et uniquement ses notes une fois l’étiquette imprimée. Chaque colis contient l’ensemble des status_updates du transporteur, y compris le detail_code de DHL en cas de redirection vers un bureau de poste. Sur l’envoi, home_kit_orders ne liste que les commandes de ton contexte d’accès. Voir Accès.
La composition d’une commande de kit à domicile ne peut être modifiée que tant qu’elle est pending. Une fois la commande dispatched (ou au-delà — activated/cancelled), les changements de panel et les endpoints /biomarkers renvoient 409 Conflict : le kit physique est emballé selon le panel choisi, donc son contenu est figé dès son départ vers le patient. Si tu dois modifier les analyses d’une commande déjà verrouillée, contacte directement Aniva — c’est généralement encore possible, et nous ferons le changement pour toi afin de garder le contenu du kit cohérent. Si le kit a déjà été utilisé et n’a pas pu fournir ses résultats, commande plutôt un kit de remplacement.

Lister les commandes de kit à domicile

Récupère toutes les commandes de kit à domicile accessibles avec ta clé API :
Passe éventuellement ?profile_id={uuid} pour filtrer sur un profil précis, ou ?lab_code={code} pour retrouver la commande associée à un kit physique — la première étape naturelle d’un parcours d’activation.

Créer une commande de kit à domicile

Demande une commande de kit à domicile pour un profil patient :
Passe le profile_id, une delivery_address et un seul panel_id. La commande est créée avec le statut pending. Passe un en-tête Idempotency-Key optionnel pour qu’une nouvelle tentative ne commande pas un second kit — voir Idempotence. Un seul panel exactement, car un kit à domicile correspond 1 pour 1 à un kit physique — le panel est le kit. Seuls les panels configurés par Aniva comme kits à domicile peuvent être commandés ; tout autre panel est rejeté avec 422. Il est requis dès la création, car la commande rejoint aussitôt la file d’emballage et la préparation peut commencer immédiatement. Tant que la commande est pending, tu peux changer le panel via Mettre à jour. Pour envoyer un second kit à la place d’un kit qui n’a pas pu fournir ses résultats, passe replaces_home_kit_order_id au lieu de choisir un panel — voir Kits de remplacement.

Kits de remplacement

Parfois, un kit ne peut pas fournir ses résultats : le patient n’a pas réussi à remplir le tube, l’échantillon est arrivé avec trop peu de matière, le laboratoire n’a pas pu en analyser une partie. Commande un remplacement :
Un remplacement est une nouvelle commande avec un nouveau code laboratoire, même si 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. Les deux commandes restent consultables, liées via replaces_home_kit_order_id. La commande remplacée n’est pas modifiée. Elle garde son statut, son code laboratoire et les résultats déjà enregistrés, afin qu’un patient qui poste quand même le premier kit reçoive tout ce que le laboratoire parvient à lire. Le panel est hérité. Omets panel_id et le remplacement reprend le panel de la commande remplacée — c’est ce que le patient a acheté et l’habillage de la boîte. Envoie un autre panel uniquement pour un remplacement complet ; un panel accompagné d’un sous-ensemble de marqueurs est rejeté avec 422, car un sous-ensemble n’a de sens que dans le panel dont il est issu. Le panel d’un remplacement ne peut pas non plus être changé par la suite. Tu choisis ce qui est réanalysé. Envoie biomarker_ids avec les marqueurs en échec et le laboratoire ne réanalyse que ceux-là, si bien que le kit ne contient que les tubes nécessaires. Omets ce champ pour réanalyser tout le panel — le bon choix quand rien n’a été analysé du tout. Aucun scope supplémentaire n’est requis : réanalyser des marqueurs déjà payés par le patient n’est pas une sélection à la carte. Ces marqueurs ne peuvent pas être retirés ensuite, car ils constituent toute la demande d’analyse.
Les marqueurs sont réanalysés par groupes du panel, pas un par un. Indiquer un seul marqueur d’un groupe relance tout ce groupe, car une commande au laboratoire ne peut pas être passée si elle renvoie plus que ce qui a été demandé. Un remplacement pour un seul marqueur peut donc revenir avec plusieurs résultats, et contenir plus de tubes que la liste des marqueurs ne le laisse penser.
Un seul remplacement par kit peut être en cours à la fois — tant qu’un remplacement est pending ou dispatched, une seconde création pour la même commande renvoie 409 en le mentionnant. Les résultats arrivent sous le propre lab_code du remplacement, via son propre endpoint Obtenir les résultats. Un remplacement ne sert pas à gérer un colis qui n’est jamais arrivé. Préviens plutôt Aniva : il s’agit d’une réexpédition de la même commande sous le même code laboratoire, pas d’une nouvelle commande.

Mettre à jour une commande de kit à domicile

Modifie l’adresse de livraison, change le panel, mets à jour tes métadonnées ou remplace les e-mails de notification des résultats :
N’inclus que les champs que tu souhaites modifier. panel_id remplace le panel associé — comme il y a exactement un panel par kit, un remplacement est la seule opération pertinente sur le panel, c’est pourquoi il n’existe pas d’endpoints d’ajout ou de suppression de panel. L’adresse et le panel ne sont modifiables que tant que la commande est pending ; metadata reste modifiable pendant toute la durée de vie de la commande. results_ready_emails reste modifiable jusqu’à ce que la commande passe à cancelled.

Annuler une commande de kit à domicile

Annule une commande de kit à domicile qui n’est plus nécessaire :
Cela fait passer le statut de la commande de kit à domicile à cancelled. La commande de kit à domicile annulée est renvoyée dans la réponse. Seule une commande pending peut être annulée. À partir de dispatched, le kit est emballé et étiqueté — il n’y a pas de rappel automatique — et l’appel renvoie 409. Si un kit déjà expédié doit être bloqué, contacte directement Aniva. Annuler une commande pending dont le kit a déjà été commandé auprès de la logistique l’y annule aussi, et l’appel ne réussit que si la logistique accepte :
  • 409 — le kit était déjà emballé et étiqueté, il ne peut donc plus être rappelé, même si la commande affiche encore pending.
  • 502 — la logistique a refusé l’annulation (l’erreur contient le motif), ou n’a pas pu être jointe. Rien n’a été modifié — la commande est toujours active et peut être annulée à nouveau.
Une annulation qui renvoie une erreur laisse la commande exactement telle qu’elle était, donc un 200 est la seule confirmation qu’aucun kit ne sera envoyé. Annuler une commande déjà cancelled renvoie le même 200, quel que soit le statut depuis lequel elle a été annulée.

Activer une commande de kit à domicile

Quand le patient a prélevé son échantillon, signale-le :
Passe activated_at — le moment précis où le patient a prélevé l’échantillon, en UTC. C’est l’heure de prélèvement qui figurera sur le compte rendu du laboratoire, donc envoie le vrai moment du prélèvement, pas ton heure de traitement. L’activation est définitive : la commande passe à activated et ne peut plus être annulée ni modifiée. Équivalent kit à domicile de Confirmer la prise de sang, sans code-barres — le code du kit est apposé à l’emballage, tu n’as donc jamais besoin de le connaître. La commande doit déjà avoir son lab_code à ce stade ; une commande qui n’en a pas renvoie 409. C’est aussi l’activation qui passe la commande au laboratoire : le panel du kit est commandé au laboratoire sous son lab_code, afin que l’échantillon retourné soit attendu et que les résultats s’y rattachent dès que le laboratoire les transmet. Cela s’exécute après la réponse, et un problème côté laboratoire est géré par Aniva plutôt que remonté sur ta requête.

Biomarqueurs individuels

Tu peux rattacher des biomarqueurs individuels à une commande de kit à domicile comme analyses à la carte, en dehors du panel. C’est utile quand tu veux une sélection sur mesure en plus du kit. Les biomarqueurs rattachés apparaissent dans la réponse de la commande de kit à domicile sous forme d’un tableau individual_biomarkers (au même niveau que panels). Les deux endpoints de biomarqueurs nécessitent le scope de capacité home_kit_orders_individual_biomarker_selection en plus de home_kit_orders_manage — les kits à domicile se commandent par panel, les marqueurs à la carte sont donc activés par partenaire. Demande à Aniva si ton intégration en a besoin. Ajoute des biomarqueurs (idempotent — les biomarqueurs déjà associés sont conservés) :
Supprimer des biomarqueurs (idempotent — un ID non rattaché est ignoré) :
Les deux endpoints prennent un tableau biomarker_ids. Utilise Lister les biomarqueurs avec home_kit=true pour trouver les ID de biomarqueurs. Les biomarqueurs ne peuvent être modifiés que lorsque le kit est pending (voir Cycle de vie).

Récupérer les résultats de laboratoire

Une fois que le laboratoire a traité l’échantillon retourné, récupère les résultats cliniques et génétiques :
La réponse inclut les analyses prévues (statut planned) aux côtés des résultats reçus, pour que tu puisses suivre ce qui est encore en attente. Les résultats sont classés sous le lab_code de la commande et arrivent marqueur par marqueur au fur et à mesure des analyses du laboratoire, des payloads partiels sont donc normaux. Le champ status de premier niveau est in_progress jusqu’au rapport final, puis completed (ou fault si toutes les commandes de laboratoire ont échoué sans rapport) — utilise-le pour savoir si les analyses de la commande de kit à domicile sont terminées. Un webhook home_kit_order.results.completed t’avertit quand c’est le cas, tu n’as donc pas besoin de faire du polling. Les PDF des rapports de laboratoire sont référencés dans le tableau documents — utilise GET /api/v1/documents/{id} pour les télécharger.

Exemple de commande de kit à domicile