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

# Résultats

> Fonctionnement des résultats de laboratoire et des documents dans l'API Aniva : valeurs de biomarqueurs, intervalles de référence, comptes rendus de laboratoire et webhooks de résultats.

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 :

| Statut | Signification |
| - | - |
| `in_progress` | Certaines soumissions sont encore en cours de traitement par le laboratoire. |
| `completed` | Toutes les soumissions sont clôturées et au moins une a renvoyé des résultats. |
| `fault` | Toutes les soumissions ont échoué sans renvoyer de résultats. Aucun résultat n'est attendu. |

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](https://docs.anivahealth.com/fr/concepts/webhooks.md). `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](#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.

> [!WARNING]
>
> 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 :

| Valeur | Signification | Afficher |
| - | - | - |
| `not_provided` | Aucun intervalle n'existe. Le laboratoire n'en a envoyé aucun. | « Non applicable » |
| `lab_text_only` | Le laboratoire a imprimé uniquement du texte, comme une cible, un niveau de risque ou un intervalle selon l'étape de vie. | Le texte dans `lab_reported.reference_range` |
| `not_measured` | Le résultat est `undeliverable`, il n'y a donc aucune valeur à comparer. | Le champ `status_reason` |

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

| Statut | Signification |
| - | - |
| `planned` | L'analyse est commandée mais les résultats du laboratoire ne sont pas encore arrivés. |
| `received` | Le laboratoire a renvoyé un résultat. |
| `corrected` | Un vérificateur humain a révisé la valeur transmise par le laboratoire. |
| `likely_wrong` | Le contrôle automatique d'Aniva ou le membre doute de la valeur. Non confirmé : ne l'affiche pas comme un constat sans vérification. Voir `status_reason`. |
| `fault` | Le laboratoire a fourni un résultat confirmé erroné — **ne pas utiliser à des fins cliniques**. `value` contient toujours le chiffre erroné ; voir `status_reason`. |
| `undeliverable` | Le laboratoire n'a pas pu produire de valeur. `value` vaut `null` ; voir `status_reason`. |

> [!TIP]
>
> 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.

> [!WARNING]
>
> 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

| Valeur | Catégorie |
| - | - |
| `pathogenic`, `likely_pathogenic` | Responsable ou probablement responsable d'une maladie |
| `uncertain` | Variant de signification incertaine (VSI) |
| `likely_benign`, `benign` | Non responsable d'une maladie |
| `high_risk`, `moderate_risk`, `low_risk` | Classification du niveau de risque |
| `protective` | Variant protecteur |
| `drug_response`, `poor_metabolizer`, `rapid_metabolizer` | Résultats pharmacogénomiques |

### Statuts des résultats génétiques

| Statut | Signification |
| - | - |
| `planned` | Le test est commandé, mais les résultats ne sont pas encore arrivés. |
| `received` | Le laboratoire a renvoyé un résultat. |
| `likely_wrong` | La vérification automatique d'Aniva ou le membre doute du génotype. Non confirmé. Voir `status_reason`. |
| `fault` | Le laboratoire a fourni un résultat confirmé erroné — **à ne pas utiliser cliniquement**. Voir `status_reason`. |
| `undeliverable` | Le laboratoire n'a pas pu produire de génotype. Voir `status_reason`. |

### 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](https://docs.anivahealth.com/fr/api/documents/upload-document.md)).
* **`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.

> [!NOTE]
>
> 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](https://docs.anivahealth.com/fr/api/appointments/email-results.md) pour un rendez-vous, ou
[Envoyer les résultats par e-mail](https://docs.anivahealth.com/fr/api/home-kit-orders/email-results.md) 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](https://docs.anivahealth.com/fr/api/profiles/update-profile.md).

## 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](https://docs.anivahealth.com/fr/api/appointments/create-appointment.md) ou
[Créer une commande de kit à domicile](https://docs.anivahealth.com/fr/api/home-kit-orders/create-home-kit.md). Modifie la liste plus tard avec
[Mettre à jour un rendez-vous](https://docs.anivahealth.com/fr/api/appointments/update-appointment.md) ou
[Mettre à jour une commande de kit à domicile](https://docs.anivahealth.com/fr/api/home-kit-orders/update-home-kit.md) ; `[]` 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](https://docs.anivahealth.com/fr/api/profiles/create-embed-session.md) 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

```json theme={null}
{
  "status": "in_progress",
  "submissions": [
    {
      "lab_code": "7642001234",
      "status": "in_progress"
    }
  ],
  "clinical_results": [
    {
      "id": "3f2b8c1e-5d4a-4e7b-9a6c-2d1f0e8b7a54",
      "status": "received",
      "status_reason": null,
      "lab_code": "7642001234",
      "biomarker_id": 104,
      "biomarker_name": "Vitamin D",
      "category": "Vitamins",
      "value": 38.5,
      "value_operator": "eq",
      "unit_id": 1,
      "unit": "ng/mL",
      "reference_range_lab": {
        "normal_min": 30,
        "normal_max": 100,
        "optimal_min": null,
        "optimal_max": null
      },
      "reference_range_lab_absent_reason": null,
      "aniva_range": {
        "normal_min": 30,
        "normal_max": 100,
        "optimal_min": 30,
        "optimal_max": 60,
        "sources": [
          {
            "title": "Example source title",
            "url": "https://example.com/source"
          }
        ]
      },
      "tested_at": "2026-04-05",
      "comment": null,
      "origin": "lab",
      "lab_reported": {
        "name": "Vitamin D (25-OH)",
        "code": "vitd",
        "category": "Endokrinologie",
        "value": "38.5",
        "unit": "ng/ml",
        "reference_range": "30 - 100",
        "reference_range_min": 30,
        "reference_range_max": 100,
        "flag": "normal",
        "result_status": "final",
        "comment": null
      }
    },
    {
      "id": null,
      "status": "planned",
      "status_reason": null,
      "lab_code": null,
      "biomarker_id": 79,
      "biomarker_name": "Thyroid-Stimulating Hormone (TSH)",
      "category": "Hormones",
      "value": null,
      "value_operator": null,
      "unit_id": null,
      "unit": null,
      "reference_range_lab": null,
      "reference_range_lab_absent_reason": null,
      "aniva_range": null,
      "tested_at": null,
      "comment": null,
      "origin": null,
      "lab_reported": null
    }
  ],
  "genetic_results": [
    {
      "id": "b7e41d09-2c6f-4a83-8f15-6e9d3a0c4b21",
      "status": "received",
      "status_reason": null,
      "lab_code": "7642001234",
      "biomarker_id": 348,
      "gene": "APOE",
      "genotype": "E3/E4",
      "clinical_significance": "moderate_risk",
      "risk_description": "Carriers of one APOE E4 allele have a moderately increased risk of Alzheimer's disease.",
      "tested_at": "2026-04-05",
      "comment": null,
      "origin": "lab",
      "variants": [
        {
          "name": "APOE E4",
          "clinical_significance": "moderate_risk",
          "description": "The E4 allele is associated with increased Alzheimer's risk.",
          "hgvs_c": "c.388T>C",
          "hgvs_p": "p.Cys130Arg",
          "conditions": [
            {
              "condition": "Alzheimer's disease",
              "association_description": "Increased risk with one E4 allele",
              "badge": "Moderate Risk"
            }
          ],
          "snvs": [
            {
              "rs_id": "rs429358",
              "allele": "C",
              "reference_allele": "T",
              "hgvs_c": "c.388T>C",
              "hgvs_p": "p.Cys130Arg"
            }
          ]
        }
      ]
    }
  ],
  "documents": [
    {
      "id": "f8a1b2c3-d4e5-4f6a-7b8c-9d0e1f2a3b4c",
      "file_name": "20260405 - Quade Befund - 7642001234.pdf",
      "original_file_name": "7642001234_B0012_FA_E.pdf",
      "origin": "lab",
      "content_type": "application/pdf",
      "etag": "56104b36f860cfd5b41efc716fdf7b6f",
      "size_bytes": 258341,
      "lab_code": "7642001234"
    }
  ]
}
```


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