Passer au contenu principal
Une fois une prise de sang confirmée et les échantillons traités par le laboratoire, les résultats deviennent disponibles sur le rendez-vous. Les résultats sont récupérés via GET /api/v1/appointments/{id}/results et incluent les résultats de biomarqueurs cliniques, les résultats de biomarqueurs génétiques et les rapports de laboratoire téléchargeables.

Statut des résultats

Le champ status de premier niveau dans la réponse des résultats indique l’avancement global du traitement : Chaque résultat dans la réponse dispose de son propre statut (voir ci-dessous), tu peux donc afficher des résultats partiels alors que le statut global est encore in_progress. Pour savoir quand les résultats changent, abonne-toi aux webhooks. appointment.results.updated se déclenche à chaque modification du corps des résultats, et appointment.results.completed se déclenche quand le statut de premier niveau passe à completed. Les commandes de kit à domicile envoient les mêmes événements avec le préfixe home_kit_order.. Chaque événement contient l’URL des résultats à récupérer. Tu peux toujours interroger ce point de terminaison pour faire le rapprochement. Le tableau submissions détaille le statut de premier niveau par demande de laboratoire. Une prise de sang qui couvre plusieurs tubes ou plusieurs laboratoires compte plusieurs entrées, chacune avec le lab_code (code-barres du tube) sous lequel elle a été enregistrée et son propre statut in_progress / completed / fault. Une entrée fault a été rejetée ou abandonnée au laboratoire et ne renverra jamais de résultats : l’échantillon a souvent été transféré vers un autre laboratoire, qui enregistre alors sa propre entrée. Le statut de premier niveau est completed lorsque toutes les entrées sont clôturées et qu’au moins une a renvoyé des résultats. Chaque résultat reçu et chaque document porte le même lab_code, ce qui te permet de savoir de quel tube provient une valeur.

Résultats cliniques

Les résultats cliniques représentent des mesures standard de biomarqueurs sanguins — comme le taux de vitamine D, le cholestérol, les hormones thyroïdiennes, etc. Chaque résultat clinique inclut :
  • id — l’identifiant de la ligne de résultat du laboratoire. Il reste identique lorsque le laboratoire corrige cette ligne, utilise-le donc pour faire un upsert. null pour un résultat planned.
  • biomarker_name et category — ce qui a été mesuré et son groupe (par ex., Vitamines, Hormones).
  • lab_code — le code laboratoire (code-barres du tube) sous lequel le résultat a été enregistré, l’un des codes laboratoire de la commande. null pour un résultat planned et pour les résultats transmis sans code par le laboratoire.
  • value et value_operator — la mesure effective. L’opérateur est eq (égal) pour les valeurs exactes, ou lt/gt lorsque le laboratoire indique une valeur inférieure ou supérieure à la plage mesurable.
  • unit — l’unité de mesure (par ex., ng/mL, µIU/mL).
  • reference_range_lab — les bornes min/max normales et optimales telles que transmises par le laboratoire pour ce résultat, converties à la même échelle que value. Une borne laissée ouverte par le laboratoire vaut null, ainsi un intervalle unilatéral comme < 50 arrive sous la forme normal_min: null, normal_max: 50. Chaque résultat porte l’intervalle par rapport auquel il a été mesuré, de sorte qu’un patient ayant des résultats issus de plusieurs prises de sang ou laboratoires obtient le bon pour chaque résultat.
  • reference_range_lab_absent_reason — pourquoi reference_range_lab est null. null lorsque l’intervalle est présent, et sur un résultat planned. Voir Quand il n’y a pas d’intervalle de laboratoire.
  • aniva_range — Des valeurs de comparaison compilées par Aniva, à la même échelle que value. Elles varient selon l’âge, le sexe et la semaine de grossesse. normal_* correspond à l’intervalle général. optimal_* correspond à un intervalle plus étroit. Ces valeurs sont fournies à titre informatif uniquement. Elles ne constituent ni un avis médical, ni un diagnostic, ni une évaluation du résultat. Aniva ne définit aucun indicateur par rapport à elles. Utilise reference_range_lab comme référence pour le résultat. null lorsque ta clé ne dispose pas du scope aniva_ranges_view, ou lorsqu’Aniva ne dispose d’aucune valeur pour ce biomarqueur.
  • tested_at — la date à laquelle l’analyse a été effectuée.
  • comment — annotation en texte libre du laboratoire sur ce résultat précis (par ex., précisions sur l’intervalle de référence, avertissements sur la qualité de l’échantillon). null lorsque le laboratoire n’en a pas joint.
  • status_reason — pourquoi un résultat likely_wrong est douteux, ou pourquoi un résultat fault ou undeliverable est inutilisable. null pour tout autre statut. Distinct de comment, qui est la note propre du laboratoire et reste souvent vide sur les résultats en erreur.
  • origin — qui a fourni le document d’où provient la valeur, avec les mêmes valeurs que le champ origin du document ci-dessous. Une valeur issue d’un document importé (member_upload, staff_upload, partner_upload) provient de la lecture du fichier par Aniva, et non d’un rapport de laboratoire : vérifie-la par rapport au fichier avant toute utilisation clinique. null pour un résultat planned.
  • lab_reported — la ligne de rapport propre au laboratoire exécutant, textuelle et non convertie. Voir ci-dessous.

Intervalles Aniva

aniva_range contient des valeurs de comparaison qu’Aniva a compilées à partir de sources publiées et de sa propre sélection. Les intervalles varient selon l’âge, le sexe et la semaine de grossesse. sources liste les sources publiées qu’Aniva a enregistrées pour ces valeurs. La liste peut être vide.
Ces valeurs constituent des informations générales. Elles ne sont ni un avis médical, ni un diagnostic, ni un constat médical, ni une évaluation d’un résultat. Aniva ne les fournit pas en tant que dispositif médical. Aniva ne compare aucun résultat avec elles et ne définit aucun indicateur par rapport à elles. reference_range_lab et l’évaluation par un médecin restent la référence pour un résultat.
Règles pour ton produit :
  • Affiche l’intervalle Aniva uniquement en complément de l’intervalle du laboratoire, jamais à sa place.
  • Si tu déduis un indicateur, un avertissement ou une recommandation à partir de l’intervalle Aniva, tu le fais en ton propre nom et sous ta propre responsabilité.
  • Affiche la mention prévue dans ton accord avec Aniva partout où tu affiches l’intervalle Aniva.
Pour y accéder, signe le court accord sur les intervalles Aniva. Nous ajoutons ensuite le scope aniva_ranges_view à ta clé. Les valeurs peuvent changer sans préavis.

Valeurs normalisées face à la ligne propre au laboratoire

value, unit et reference_range_lab sont normalisés : nous convertissons chaque mesure dans l’unité canonique du biomarqueur et la transmettons sous notre propre nom de biomarqueur, afin que le même analyte soit comparable entre laboratoires et dans le temps. C’est ce qu’il te faut pour suivre les tendances et comparer les laboratoires, et ce n’est pas ce qu’un médecin qui examine le dossier voit sur le PDF du laboratoire — la phosphatase alcaline imprimée sous la forme 48 U/l (40 - 129) te parvient en 0.8 µkat/L. lab_reported fournit cette ligne imprimée en parallèle : le nom et le code de l’analyte du laboratoire, la valeur et l’unité telles qu’imprimées, l’intervalle de référence à la fois sous forme de texte (< 50, > 55, 40 - 129) et sous forme de bornes non converties propres au laboratoire, ainsi que son indicateur d’anomalie, son statut de résultat et sa note. Utilise lab_reported lorsqu’une personne rapproche tes données du rapport du laboratoire, et les champs canoniques pour tout ce qui est calculé. Seuls les champs effectivement envoyés par le laboratoire sont renseignés ; rien dans lab_reported n’est déduit, rempli par défaut ou converti, et l’objet entier vaut null lorsque nous ne disposons d’aucun enregistrement brut pour un résultat.

Quand il n’y a pas d’intervalle de laboratoire

Lorsque reference_range_lab est null, reference_range_lab_absent_reason t’indique pourquoi : Certains laboratoires impriment une cible ou un niveau de risque à la place d’un intervalle de référence, par exemple Ziel: <200. >240 hoch ou <5.7 neg >=6.5 pos. Ces éléments ne vont pas dans reference_range_lab, ses bornes valent donc null et la raison est lab_text_only. Affiche le texte imprimé tel quel. Un intervalle unilatéral comme < 20 est bien un intervalle. Il arrive dans reference_range_lab avec une borne à null, et la raison est null. Laisse le côté ouvert tel quel lorsque tu l’affiches.

Statuts des résultats cliniques

Lorsque tu affiches les résultats aux patients, utilise directement le champ value — il reflète déjà la valeur corrigée lorsqu’il en existe une.
Ne présente jamais un résultat fault comme un constat — son champ value est renseigné mais confirmé erroné.

Résultats génétiques

Les résultats génétiques représentent des constats au niveau des gènes issus d’une analyse ADN. Chaque résultat correspond à un gène (par ex., APOE, MTHFR) et inclut :
  • id — l’identifiant de la ligne de résultat du laboratoire. Il reste identique lorsque le laboratoire corrige cette ligne, utilise-le donc pour faire un upsert. null pour un résultat planned.
  • gene — le symbole du gène.
  • lab_code — le code laboratoire (code-barres du tube) sous lequel le résultat a été enregistré. null pour un résultat planned et pour les résultats transmis sans code par le laboratoire.
  • genotype — le génotype détecté (par ex., E3/E4).
  • clinical_significance — une classification du constat fondée sur l’ACMG.
  • risk_description — une explication lisible de ce que signifie le génotype.
  • comment — annotation en texte libre du laboratoire sur ce résultat précis. null lorsque le laboratoire n’en a pas joint.
  • status_reason — pourquoi un résultat likely_wrong est douteux, ou pourquoi un résultat fault ou undeliverable est inutilisable. null pour tout autre statut.
  • origin — qui a fourni le document d’où provient la valeur, comme pour les résultats cliniques.
  • variants — les variants génétiques spécifiques détectés, chacun avec un niveau de détail SNV.

Valeurs de signification clinique

Statuts des résultats génétiques

Structure des variants

Chaque résultat génétique contient un tableau variants. Chaque variant inclut :
  • name — nom courant (par ex. APOE E4).
  • clinical_significance — signification au niveau du variant (peut différer de celle au niveau du gène).
  • conditions — maladies ou affections associées avec leurs descriptions.
  • snvs — les variants mononucléotidiques sous-jacents, chacun avec rs_id, allele, reference_allele et une notation HGVS facultative.

Documents

Le tableau documents dans la réponse des résultats contient les références aux rapports de laboratoire téléchargeables. Chaque document comporte :
  • id — un UUID de fichier. Passe-le à GET /api/v1/documents/{id} pour télécharger le fichier.
  • file_name — le nom du fichier, identique à celui renvoyé lors du téléchargement (par ex. 20260405 - Quade Befund - 7642001234.pdf).
  • original_file_name — le nom du fichier exactement tel que fourni par le laboratoire ou l’utilisateur qui l’a téléversé (par ex. 7642001234_B0012_FA_E.pdf).
  • origin — l’origine du fichier : lab, member_upload, staff_upload ou partner_upload (tu l’as téléversé avec Téléverser un document).
  • content_type — le type de média du fichier (par ex. application/pdf). La plupart des rapports sont des PDF. Les documents numérisés téléversés peuvent être des images ou des fichiers CSV.
  • etag — la version du contenu du fichier ; elle change dès que les octets changent. Stocke-la et ne télécharge à nouveau le fichier que lorsqu’elle change. C’est l’ETag HTTP standard, comme sur S3 ou Google Cloud Storage.
  • size_bytes — la taille du fichier en octets.
  • lab_code — le code laboratoire (code-barres du tube) auquel le rapport correspond ; null si le laboratoire n’en a pas fourni.
L’accès aux documents est vérifié par rapport au profil propriétaire du document.

Envoyer les résultats au client par e-mail

Tu peux informer le client par e-mail que ses résultats sont prêts. Appelle Envoyer les résultats par e-mail pour un rendez-vous, ou Envoyer les résultats par e-mail pour une commande de kit à domicile. Chaque appel envoie un e-mail. Les appels ne sont pas dédupliqués.
  • L’e-mail est envoyé à l’email du profil. Une adresse @aniva.email fictive est refusée.
  • L’e-mail affiche le nom et le logo du groupe de profils principal du profil.
  • L’e-mail est dans la language du profil, en anglais par défaut.
  • Définis with_reports sur true pour joindre les rapports de laboratoire.
  • Ajoute note pour afficher une note personnelle dans l’e-mail, 1 000 caractères maximum.
Si le profil a désactivé les e-mails transactionnels, l’appel renvoie 409 avec la raison unsubscribed. Pour les réactiver, définis transactional_emails_enabled sur true avec Mettre à jour le profil.

E-mails de résultats prêts

Tu peux recevoir un e-mail lorsque les résultats d’une réservation sont prêts. Définis results_ready_emails avec jusqu’à 5 adresses lors de Créer un rendez-vous ou Créer une commande de kit à domicile. Modifie la liste plus tard avec Mettre à jour un rendez-vous ou Mettre à jour une commande de kit à domicile ; [] désactive les e-mails.
  • Demande-nous de définir des adresses e-mail par défaut pour ton groupe de profils. Une réservation créée sans results_ready_emails les reprend automatiquement. Une liste les remplace pour cette réservation, alors inclus ton adresse e-mail par défaut pour la conserver. [] n’envoie aucun e-mail.
  • Chaque adresse reçoit un seul e-mail, dès que tous les résultats de laboratoire de la réservation sont définitifs.
  • Une adresse ajoutée après que les résultats sont définitifs reçoit l’e-mail immédiatement.
  • L’e-mail renvoie vers la page des résultats dans le panneau d’administration Aniva. Le client ne le reçoit pas.
  • Ta clé doit disposer de l’accès results_view pour le patient. Sans lui, la requête renvoie 403.

Afficher les résultats dans ton application

Créer une session intégrée renvoie une URL à usage unique vers une page de résultats en lecture seule. Ouvre-la dans une WebView de ton application pour que le patient voie ses résultats sans se connecter.
  • Ta clé a besoin des scopes embed et results_view pour le patient. Demande le scope embed à Aniva.
  • Appelle-le depuis ton serveur chaque fois que le patient ouvre les résultats. L’URL fonctionne une seule fois et pendant 5 minutes, puis la page maintient une session de 60 minutes.
  • route ouvre l’une des pages que nous proposons : la liste des biomarqueurs, un biomarqueur ou le Twin 3D.
  • appearance définit le thème, la couleur des boutons et des liens, ainsi que l’affichage de ton logo.
  • report limite la page à un rendez-vous, une commande de kit à domicile ou un rapport de laboratoire que tu as téléversé avec POST /api/v1/documents. Le patient ne voit alors que les résultats de ce rapport.
  • La page affiche uniquement les résultats de laboratoire, comme cette API. Elle n’affiche aucun fichier, aucun chat et aucun paramètre.

Exemple de réponse des résultats