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

# Výsledky

> Jak v Aniva API fungují laboratorní výsledky a dokumenty: hodnoty biomarkerů, referenční rozmezí, laboratorní zprávy a webhooky pro výsledky.

Jakmile je odběr krve potvrzený a laboratoř zpracuje vzorky, výsledky jsou dostupné u termínu. Výsledky získáš přes `GET /api/v1/appointments/{id}/results` a zahrnují výsledky klinických biomarkerů, výsledky genetických biomarkerů a dokumenty laboratorních zpráv ke stažení.

## Stav výsledků

Pole `status` na nejvyšší úrovni v odpovědi s výsledky udává celkový postup zpracování:

| Stav | Význam |
| - | - |
| `in_progress` | Některé žádanky laboratoř ještě zpracovává. |
| `completed` | Všechny žádanky jsou uzavřené a alespoň jedna dodala výsledky. |
| `fault` | Všechny žádanky selhaly bez výsledků. Žádné další výsledky už nepřijdou. |

Jednotlivé výsledky v odpovědi mají vlastní stav (viz níže), takže můžeš zobrazovat dílčí výsledky, i když je celkový stav stále `in_progress`.

Pokud chceš vědět, kdy se výsledky změní, přihlas se k odběru [webhooků](https://docs.anivahealth.com/cs/concepts/webhooks.md). Událost `appointment.results.updated` se spustí při každé změně obsahu výsledků a `appointment.results.completed` ve chvíli, kdy stav na nejvyšší úrovni přejde do `completed`. Objednávky domácích testovacích sad posílají stejné události s předponou `home_kit_order.`. Každá událost obsahuje URL pro načtení výsledků. Pro synchronizaci můžeš tento endpoint dál dotazovat.

Pole `submissions` rozděluje stav na nejvyšší úrovni podle jednotlivých laboratorních žádanek. Odběr krve, který zahrnuje více zkumavek nebo více laboratoří, má více záznamů — každý se svým kódem `lab_code` (čárovým kódem zkumavky), pod kterým byl zaevidován, a s vlastním stavem `in_progress` / `completed` / `fault`. Záznam se stavem `fault` laboratoř zamítla nebo zrušila a nikdy nedodá výsledky: vzorek byl často přesunut do jiné laboratoře, která si pak založí vlastní záznam. Stav na nejvyšší úrovni je `completed`, když jsou všechny záznamy uzavřené a alespoň jeden dodal výsledky. Každý přijatý výsledek i každý dokument nese stejný `lab_code`, takže poznáš, ze které zkumavky hodnota pochází.

## Klinické výsledky

Klinické výsledky představují standardní měření krevních biomarkerů — například hladinu vitaminu D, cholesterol, hormony štítné žlázy a podobně.

Každý klinický výsledek obsahuje:

* **`id`** — identifikátor řádku laboratorního výsledku. Když laboratoř řádek opraví, zůstává stejný, takže ho použij pro upsert. Pro výsledek se stavem `planned` je `null`.
* **`biomarker_name`** a **`category`** — co se měřilo a do jaké skupiny to patří (např. Vitaminy, Hormony).
* **`lab_code`** — laboratorní kód (čárový kód zkumavky), pod kterým byl výsledek zaevidován; jeden z laboratorních kódů objednávky. Pro výsledek se stavem `planned` a pro výsledky, které laboratoř poslala bez kódu, je `null`.
* **`value`** a **`value_operator`** — výsledná naměřená hodnota. Operátor je `eq` (rovná se) pro přesné hodnoty, nebo `lt`/`gt`, když laboratoř hlásí hodnotu pod nebo nad měřitelným rozsahem.
* **`unit`** — měrná jednotka (např. ng/mL, µIU/mL).
* **`reference_range_lab`** — normální a optimální hranice min/max, jak je pro tento výsledek uvedla laboratoř, převedené na stejnou škálu jako `value`. Hranice, kterou laboratoř nechá otevřenou, má hodnotu `null`, takže jednostranný interval jako `< 50` přijde jako `normal_min: null, normal_max: 50`. Každý výsledek nese interval, vůči kterému se měřil, takže pacient s výsledky z více odběrů krve nebo laboratoří dostane u každého výsledku ten správný.
* **`reference_range_lab_absent_reason`** — důvod, proč je `reference_range_lab` rovno `null`. Když rozmezí existuje a u výsledku se stavem `planned`, má hodnotu `null`. Viz [Když chybí laboratorní rozmezí](#kdyz-chybi-laboratorni-rozmezi).
* **`aniva_range`** — Srovnávací hodnoty, které sestavila Aniva, na stejné škále jako `value`. Liší se podle věku, pohlaví a týdne těhotenství. `normal_*` je obecné rozmezí. `optimal_*` je užší rozmezí. Hodnoty mají pouze informativní charakter. Nejde o lékařskou radu, diagnózu ani zhodnocení výsledku. Aniva podle nich nenastavuje žádné příznaky. Jako standard pro výsledek použij `reference_range_lab`. Pokud tvůj klíč nemá scope `aniva_ranges_view` nebo Aniva pro tento biomarker nemá hodnoty, má hodnotu `null`.
* **`tested_at`** — datum provedení testu.
* **`comment`** — textová poznámka od laboratoře k tomuto konkrétnímu výsledku (např. upřesnění k referenčnímu rozmezí, upozornění ke kvalitě vzorku). Pokud ji laboratoř nepřipojila, má hodnotu `null`.
* **`status_reason`** — důvod, proč je výsledek `likely_wrong` pochybný nebo proč je výsledek `fault` či `undeliverable` nepoužitelný. U všech ostatních stavů má hodnotu `null`. Liší se od pole `comment`, což je vlastní poznámka laboratoře, která u chybných výsledků často chybí.
* **`origin`** — kdo dodal dokument, ze kterého hodnota pochází; používá stejné hodnoty jako pole `origin` u dokumentů níže. Hodnota z nahraného dokumentu (`member_upload`, `staff_upload`, `partner_upload`) pochází z toho, že Aniva soubor načetla, nikoli přímo z laboratorní zprávy: před klinickým použitím ji zkontroluj podle souboru. Pro výsledek se stavem `planned` je `null`.
* **`lab_reported`** — vlastní řádek zprávy provádějící laboratoře, doslovný a nepřevedený. Viz níže.

### Rozmezí Aniva

Pole `aniva_range` obsahuje srovnávací hodnoty, které Aniva sestavila z publikovaných zdrojů a
vlastního výběru. Rozmezí se liší podle věku, pohlaví a týdne těhotenství.
Pole `sources` uvádí publikované zdroje, které Aniva pro tyto hodnoty zaznamenala. Seznam může být prázdný.

> [!WARNING]
>
> Tyto hodnoty slouží jako obecné informace. Nejde o lékařskou radu, diagnózu,
> lékařský nález ani zhodnocení výsledku. Aniva je neposkytuje jako zdravotnický
> prostředek. Aniva s nimi výsledek neporovnává a nenastavuje podle nich žádný příznak.
> Standardem pro výsledek zůstává `reference_range_lab` a posouzení lékařem.

Pravidla pro tvůj produkt:

* Rozmezí Aniva zobrazuj vždy jen jako doplněk k rozmezí z laboratoře, nikdy místo něj.
* Pokud z rozmezí Aniva odvodíš příznak, upozornění nebo doporučení, děláš to vlastním
  jménem a na vlastní odpovědnost.
* Všude, kde zobrazuješ rozmezí Aniva, uveď i upozornění ze své smlouvy se společností Aniva.

Pro získání přístupu podepiš krátkou smlouvu o rozmezích Aniva. Poté k tvému klíči přidáme
scope `aniva_ranges_view`. Hodnoty se mohou bez předchozího upozornění změnit.

### Normalizované hodnoty versus vlastní řádek laboratoře

Pole `value`, `unit` a `reference_range_lab` jsou normalizovaná: každé měření převádíme na kanonickou jednotku biomarkeru a uvádíme ho pod naším vlastním názvem biomarkeru, takže stejný analyt lze porovnávat napříč laboratořemi i v čase. Přesně to potřebuješ pro sledování trendů a srovnání mezi laboratořemi, ale není to totéž, co vidí hodnotící lékař v PDF z laboratoře — alkalická fosfatáza vytištěná jako `48 U/l (40 - 129)` ti dorazí jako `0.8 µkat/L`.

Pole `lab_reported` tento vytištěný řádek nese vedle toho: název a kód analytu podle laboratoře, hodnotu a jednotku tak, jak byly vytištěny, referenční interval jak v textové podobě (`< 50`, `> 55`, `40 - 129`), tak jako vlastní nepřevedené hranice laboratoře, a k tomu její příznak odchylky, stav výsledku a poznámku.

Pole `lab_reported` použij, když někdo porovnává tvá data s laboratorní zprávou, a kanonická pole pro všechny výpočty. Vyplněná jsou jen pole, která laboratoř skutečně poslala; nic v `lab_reported` není odvozené, předvyplněné ani převedené a celý objekt má hodnotu `null`, pokud pro výsledek nemáme původní záznam.

### Když chybí laboratorní rozmezí

Když má `reference_range_lab` hodnotu `null`, pole `reference_range_lab_absent_reason` ti řekne proč:

| Hodnota | Význam | Zobrazit |
| - | - | - |
| `not_provided` | Žádné rozmezí neexistuje. Laboratoř žádné neposlala. | „Neuplatňuje se“ |
| `lab_text_only` | Laboratoř vytiskla jen text, například cílovou hodnotu, úroveň rizika nebo rozmezí podle životního období. | Text v `lab_reported.reference_range` |
| `not_measured` | Výsledek má stav `undeliverable`, takže není žádná hodnota ke srovnání. | Hodnotu `status_reason` |

Některé laboratoře místo referenčního rozmezí vytisknou cílovou hodnotu nebo úroveň rizika, například
`Ziel: <200. >240 hoch` nebo `<5.7 neg >=6.5 pos`. Ty nepatří do `reference_range_lab`, takže jeho
hranice mají hodnotu `null` a důvod je `lab_text_only`. Vytištěný text zobraz doslovně.

Jednostranné rozmezí, například `< 20`, je rozmezí. Přijde v `reference_range_lab` s jednou hranicí
`null` a důvod je `null`. Při zobrazení nech otevřenou stranu otevřenou.

### Stavy klinických výsledků

| Stav | Význam |
| - | - |
| `planned` | Test je objednaný, ale výsledky z laboratoře ještě nedorazily. |
| `received` | Laboratoř vrátila výsledek. |
| `corrected` | Hodnotu nahlášenou laboratoří upravil pracovník při kontrole. |
| `likely_wrong` | Automatická kontrola Aniva nebo člen o hodnotě pochybuje. Nepotvrzeno: nezobrazuj ji jako nález bez kontroly. Viz `status_reason`. |
| `fault` | Laboratoř dodala výsledek, u kterého se potvrdila chyba — **nepoužívej ho klinicky**. Pole `value` stále obsahuje chybnou hodnotu; viz `status_reason`. |
| `undeliverable` | Laboratoř nedokázala hodnotu stanovit. Pole `value` má hodnotu `null`; viz `status_reason`. |

> [!TIP]
>
> Při zobrazování výsledků pacientům použij přímo pole `value` — už obsahuje
> opravenou hodnotu, pokud existuje.

> [!WARNING]
>
> Nikdy neprezentuj výsledek se stavem `fault` jako nález — jeho pole `value` je vyplněné, ale potvrdilo se, že je chybné.

## Genetické výsledky

Genetické výsledky představují nálezy na úrovni genů z analýzy DNA. Každý výsledek odpovídá jednomu genu (např. APOE, MTHFR) a obsahuje:

* **`id`** — identifikátor řádku laboratorního výsledku. Když laboratoř řádek opraví, zůstává stejný, takže ho použij pro upsert. Pro výsledek se stavem `planned` je `null`.
* **`gene`** — symbol genu.
* **`lab_code`** — laboratorní kód (čárový kód zkumavky), pod kterým byl výsledek zaevidován. Pro výsledek se stavem `planned` a pro výsledky, které laboratoř poslala bez kódu, je `null`.
* **`genotype`** — zjištěný genotyp (např. E3/E4).
* **`clinical_significance`** — klasifikace nálezu podle ACMG.
* **`risk_description`** — srozumitelné vysvětlení, co daný genotyp znamená.
* **`comment`** — textová poznámka od laboratoře k tomuto konkrétnímu výsledku. Pokud ji laboratoř nepřipojila, má hodnotu `null`.
* **`status_reason`** — důvod, proč je výsledek `likely_wrong` pochybný nebo proč je výsledek `fault` či `undeliverable` nepoužitelný. U všech ostatních stavů má hodnotu `null`.
* **`origin`** — kdo dodal dokument, ze kterého hodnota pochází, stejně jako u klinických výsledků.
* **`variants`** — konkrétní zjištěné genetické varianty, každá s podrobnostmi na úrovni SNV.

### Hodnoty klinického významu

| Hodnota | Kategorie |
| - | - |
| `pathogenic`, `likely_pathogenic` | Způsobuje nebo pravděpodobně způsobuje onemocnění |
| `uncertain` | Varianta nejasného významu (VUS) |
| `likely_benign`, `benign` | Nezpůsobuje onemocnění |
| `high_risk`, `moderate_risk`, `low_risk` | Klasifikace míry rizika |
| `protective` | Ochranná varianta |
| `drug_response`, `poor_metabolizer`, `rapid_metabolizer` | Farmakogenomické nálezy |

### Stavy genetických výsledků

| Stav | Význam |
| - | - |
| `planned` | Test je objednaný, ale výsledky ještě nedorazily. |
| `received` | Laboratoř vrátila výsledek. |
| `likely_wrong` | Automatická kontrola Aniva nebo člen pochybuje o genotypu. Nepotvrzeno. Viz `status_reason`. |
| `fault` | Laboratoř dodala prokazatelně chybný výsledek — **nepoužívej klinicky**. Viz `status_reason`. |
| `undeliverable` | Laboratoř nedokázala určit genotyp. Viz `status_reason`. |

### Struktura varianty

Každý genetický výsledek obsahuje pole `variants`. Každá varianta zahrnuje:

* **`name`** — běžný název (např. APOE E4).
* **`clinical_significance`** — význam na úrovni varianty (může se lišit od významu na úrovni genu).
* **`conditions`** — související onemocnění/stavy s popisy.
* **`snvs`** — základní jednonukleotidové varianty, každá s `rs_id`, `allele`, `reference_allele` a volitelným zápisem HGVS.

## Dokumenty

Pole `documents` v odpovědi s výsledky obsahuje odkazy na soubory laboratorních zpráv ke stažení. Každý dokument má:

* **`id`** — UUID souboru. Předej ho do `GET /api/v1/documents/{id}` pro stažení souboru.
* **`file_name`** — název souboru, stejný jako při stažení (např. `20260405 - Quade Befund - 7642001234.pdf`).
* **`original_file_name`** — název souboru přesně tak, jak ho dodala laboratoř nebo nahrávající (např. `7642001234_B0012_FA_E.pdf`).
* **`origin`** — kdo soubor dodal: `lab`, `member_upload`, `staff_upload` nebo `partner_upload` (když ho nahraješ přes [Nahrát dokument](https://docs.anivahealth.com/cs/api/documents/upload-document.md)).
* **`content_type`** — typ média souboru (např. `application/pdf`). Většina zpráv je ve formátu PDF. Nahrané skeny mohou být obrázky nebo soubory CSV.
* **`etag`** — verze obsahu souboru; mění se vždy, když se změní bajty. Ulož si ho a stahuj znovu jen při změně. Jde o standardní HTTP entity tag, jaký používá S3 nebo Google Cloud Storage.
* **`size_bytes`** — velikost souboru v bajtech.
* **`lab_code`** — laboratorní kód (čárový kód zkumavky), ke kterému zpráva patří; `null`, pokud laboratoř žádný neuvedla.

> [!NOTE]
>
> Přístup k dokumentům se ověřuje vůči profilu, který dokument vlastní.

## Odeslání výsledků zákazníkovi e-mailem

Zákazníkovi můžeš dát e-mailem vědět, že má výsledky připravené. Zavolej
[Odeslat výsledky e-mailem](https://docs.anivahealth.com/cs/api/appointments/email-results.md) pro termín nebo
[Odeslat výsledky e-mailem](https://docs.anivahealth.com/cs/api/home-kit-orders/email-results.md) pro objednávku domácí testovací sady. Každé volání odešle jeden e-mail.
Volání se nededuplikují.

* E-mail se posílá na `email` profilu. Zástupná adresa `@aniva.email` je odmítnuta.
* E-mail zobrazuje název a logo primární profilové skupiny profilu.
* E-mail je v jazyce `language` profilu, výchozí je angličtina.
* Nastav `with_reports` na `true`, pokud chceš přiložit laboratorní zprávy.
* Přidej `note`, pokud chceš v e-mailu zobrazit osobní poznámku, nejvýše 1 000 znaků.

Pokud má profil vypnuté transakční e-maily, volání vrátí `409` s důvodem
`unsubscribed`. Pro jejich opětovné zapnutí nastav `transactional_emails_enabled` na `true` přes
[Aktualizovat profil](https://docs.anivahealth.com/cs/api/profiles/update-profile.md).

## E-maily o připravených výsledcích

Když jsou výsledky rezervace připravené, můžeš dostat e-mail. Nastav `results_ready_emails` až na 5
adres při volání [Vytvořit termín](https://docs.anivahealth.com/cs/api/appointments/create-appointment.md) nebo
[Vytvořit objednávku domácí testovací sady](https://docs.anivahealth.com/cs/api/home-kit-orders/create-home-kit.md). Seznam můžeš později změnit přes
[Aktualizovat termín](https://docs.anivahealth.com/cs/api/appointments/update-appointment.md) nebo
[Aktualizovat objednávku domácí testovací sady](https://docs.anivahealth.com/cs/api/home-kit-orders/update-home-kit.md); `[]` e-maily vypne.

* Požádej nás o nastavení výchozích e-mailových adres pro tvou skupinu profilů. Rezervace vytvořená bez
  `results_ready_emails` je dostane. Vlastní seznam je pro danou rezervaci nahradí, takže pokud chceš
  zachovat výchozí e-mailovou adresu, uveď ji v něm také. `[]` neodešle žádný e-mail.
* Každá adresa dostane jeden e-mail, jakmile jsou všechny laboratorní výsledky rezervace finální.
* Adresa přidaná až poté, co jsou výsledky finální, dostane e-mail okamžitě.
* E-mail odkazuje na stránku s výsledky v administračním panelu Aniva. Zákazník ho nedostane.
* Tvůj klíč potřebuje přístup `results_view` k pacientovi. Bez něj požadavek vrátí `403`.

## Zobrazení výsledků ve tvé aplikaci

[Vytvořit embed relaci](https://docs.anivahealth.com/cs/api/profiles/create-embed-session.md) vrátí jednorázovou URL adresu pro stránku
s výsledky jen pro čtení. Otevři ji ve WebView tvé aplikace, aby pacient viděl výsledky bez přihlášení.

* Tvůj klíč potřebuje oprávnění `embed` a `results_view` pro daného pacienta. O oprávnění `embed`
  požádej Aniva.
* Volej ho ze svého serveru pokaždé, když pacient otevře výsledky. URL adresa funguje jednou a po dobu
  5 minut a stránka pak drží 60minutovou relaci.
* `route` otevře jednu ze stránek, které zpřístupňujeme: seznam biomarkerů, jeden biomarker nebo 3D Twin.
* `appearance` nastavuje motiv, barvu tlačítek a odkazů a to, jestli se zobrazí tvé logo.
* `report` omezí stránku na jeden termín, jednu objednávku domácí testovací sady nebo jednu laboratorní zprávu,
  kterou nahraješ přes `POST /api/v1/documents`. Pacient pak uvidí jen výsledky z této zprávy.
* Stránka zobrazuje jen laboratorní výsledky, stejně jako toto API. Nezobrazuje žádné soubory, chat ani nastavení.

## Příklad odpovědi s výsledky

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