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

# Získat laboratorní výsledky

> Načíst klinické a genetické laboratorní výsledky pro objednávku domácí testovací sady

Načti klinické a genetické laboratorní výsledky pro objednávku domácí testovací sady spolu s odkazy na PDF dokumenty laboratorních zpráv.

V odpovědi se objeví každý biomarker objednaný pro sadu, takže můžeš sledovat celou objednávku, nejen to, co už přišlo. Výsledky se evidují pod `lab_code` objednávky — laboratorní objednávka se zadává při [aktivaci](https://docs.anivahealth.com/cs/api/home-kit-orders/activate-home-kit.md) a laboratoř hlásí jednotlivé markery postupně podle toho, jak je analyzuje, takže částečná odpověď je normální a hlavní `status` zůstává `in_progress` až do závěrečné zprávy. U každého výsledku nejdřív zkontroluj `status`, než použiješ jeho `value`:

* Testy, na které se stále čeká, mají stav `planned`, dokud je objednávka ve stavu `in_progress`. Tento endpoint můžeš zavolat i před aktivací — každý objednaný marker má pak stav `planned`.
* Výsledky, které laboratoř dodala, ale které se **nesmí** klinicky použít, mají stav `fault` nebo `undeliverable` a obsahují `status_reason` s vysvětlením proč. Výsledek se stavem `fault` má stále vyplněnou hodnotu `value` — tato hodnota je chybná. Nikdy ji neuváděj jako nález.
* Výsledky, o kterých má Aniva nebo člen pochybnosti, mají stav `likely_wrong` a `status_reason`. Hodnota není potvrzená. Nezobrazuj ji jako nález bez kontroly.

Ke stažení PDF laboratorních zpráv uvedených v poli `documents` použij [Stáhnout dokument](https://docs.anivahealth.com/cs/api/documents/download-document.md).

Tento endpoint nemusíš opakovaně dotazovat. Přihlas se k odběru [webhooků](https://docs.anivahealth.com/cs/concepts/webhooks.md) `home_kit_order.results.updated` nebo `home_kit_order.results.completed` a zavolej ho, až dorazí událost. Opakované dotazování dál funguje jako záloha.

Vyžaduje rozsah `results_view` — laboratorní výsledky a dokumenty jsou jím vždy chráněné, stejně jako výsledky z termínu a [Stáhnout dokument](https://docs.anivahealth.com/cs/api/documents/download-document.md) — plus rozsah `home_kit_orders_view` nebo `home_kit_orders_manage` pro přístup k samotné objednávce sady.

## Požadavek

### Parametry cesty

**id** `string` *required*

Jedinečný identifikátor (UUID) objednávky domácí testovací sady, pro kterou chceš načíst výsledky.

## Odpověď

Při úspěchu vrátí API `200 OK` s objektem výsledků.

**status** `string` *required*

Celkový stav výsledků. Jedna z hodnot:

* `in_progress` — některé žádanky jsou stále v laboratoři.
* `completed` — všechny žádanky jsou uzavřené a alespoň jedna dodala výsledky.
* `fault` — všechny žádanky skončily bez výsledků. Nic dalšího už nepřijde.

**submissions** `object[]` *required*

Jeden záznam na každou laboratorní žádanku — odběr krve rozdělený do více zkumavek nebo laboratoří jich má
několik. Hlavní `status` je `completed`, jakmile jsou všechny záznamy uzavřené a alespoň jeden dodal výsledky.

**objekt submission**

**lab\_code** `string`

Laboratorní kód (čárový kód zkumavky), pod kterým byla tato žádanka evidována. Může být `null`, když laboratoř žádný
neuvedla.

**status** `string` *required*

`in_progress`, dokud na žádance laboratoř stále pracuje, `completed`, jakmile je její zpráva
konečná, nebo `fault`, když byla žádanka zamítnuta nebo zrušena a nikdy nedodá výsledky —
vzorek se často přesune do jiné laboratoře, která pak založí vlastní záznam.

**clinical\_results** `object[]` *required*

Pole klinických výsledků biomarkerů.

**objekt klinického výsledku**

**id** `string`

Identifikátor řádku laboratorního výsledku (UUID). Když laboratoř tento řádek opraví, zůstane stejný, takže ho použij pro upsert. `null` pro výsledek `planned`.

**status** `string` *required*

Stav výsledku. Jedna z hodnot:

* `planned` — objednáno, laboratoř zatím výsledek nevrátila. `value` je `null`.
* `received` — doručeno z laboratoře.
* `corrected` — doručeno, poté upraveno člověkem. `value` je opravená hodnota.
* `likely_wrong` — automatická kontrola Aniva nebo člen hodnotu zpochybňuje. Nepotvrzeno: bez kontroly ji nezobrazuj jako nález. Viz `status_reason`.
* `fault` — doručeno, ale potvrzeno jako chybné; **nepoužívej klinicky**. `value` obsahuje chybnou hodnotu. Viz `status_reason`.
* `undeliverable` — laboratoř nemohla hodnotu stanovit. `value` je `null`. Viz `status_reason`.

**status\_reason** `string` *required*

Proč je výsledek sporný nebo nepoužitelný. Vyplněno pro `likely_wrong`, `fault` a `undeliverable`, pro všechny ostatní stavy `null`.

Liší se od `comment`, což je vlastní poznámka laboratoře ve zprávě — u většiny chybných výsledků je `comment` prázdné, proto ber `status_reason` jako směrodatné vysvětlení.

**lab\_code** `string`

Laboratorní kód (čárový kód zkumavky), pod kterým byl výsledek zařazen — jeden z laboratorních kódů objednávky. `null` pro výsledek `planned` a pro výsledky, které laboratoř nahlásila bez kódu.

**biomarker\_id** `integer` *required*

Identifikátor biomarkeru.

**biomarker\_name** `string` *required*

Zobrazovaný název biomarkeru.

**category** `string`

Kategorie biomarkeru (např. Hormony, Vitamíny). Může být `null`.

**value** `number`

Platná hodnota výsledku (opravená, pokud je k dispozici, jinak původní). Může být `null`.

**value\_operator** `string`

Porovnávací operátor hodnoty: `eq` (rovná se), `lt` (menší než) nebo `gt` (větší než). Může být `null`.

**unit\_id** `integer`

Identifikátor měrné jednotky. Může být `null`.

**unit** `string`

Zobrazovaný název měrné jednotky. Může být `null`.

**reference\_range\_lab** `object`

Referenční rozmezí nahlášená laboratoří pro **tento** výsledek, převedená na stejnou jednotku jako `value`. `null`, když laboratoř žádné rozmezí nenahlásila.

Mez, kterou laboratoř nechala otevřenou, zůstává `null`, takže jednostranný interval má vyplněný jen svůj konec — horní práh přijde jako `normal_min: null, normal_max: 50`, dolní jako `normal_min: 55, normal_max: null`. Nevykládej si mez `null` jako nulu ani jako výchozí neomezenost; ber ji jako „laboratoř na této straně nestanovila žádný limit“.

Každý výsledek nese rozmezí, vůči kterému byl změřen, takže pacient s výsledky z více odběrů krve nebo laboratoří dostane u každého výsledku správný interval, ne jen ten nejnovější.

**referenční rozmezí**

**normal\_min** `number`

Dolní mez normálního rozmezí. Může být `null`.

**normal\_max** `number`

Horní mez normálního rozmezí. Může být `null`.

**optimal\_min** `number`

Dolní mez optimálního rozmezí. Může být `null`.

**optimal\_max** `number`

Horní mez optimálního rozmezí. Může být `null`.

**reference\_range\_lab\_absent\_reason** `string`

Proč je `reference_range_lab` `null`. `null`, když je `reference_range_lab` přítomno, a u výsledku `planned`.

* `not_provided`: žádné rozmezí neexistuje. Laboratoř žádné neposlala. Zobraz „Nevztahuje se“.
* `lab_text_only`: laboratoř uvedla jen text, například cílovou hodnotu, úroveň rizika nebo rozmezí podle životní fáze. Zobraz `lab_reported.reference_range`.
* `not_measured`: výsledek má stav `undeliverable`, takže není žádná hodnota k porovnání. Zobraz `status_reason`.

**aniva\_range** `object`

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 slouží pouze pro informaci. Nejde o lékařskou radu, diagnózu ani hodnocení výsledku. Aniva podle nich nenastavuje žádný příznak. Jako standard pro výsledek použij `reference_range_lab`. `null`, když tvůj klíč nemá scope `aniva_ranges_view` nebo když Aniva pro tento biomarker nemá hodnoty.

**referenční rozmezí**

**normal\_min** `number`

Dolní mez normálního rozmezí. Může být `null`.

**normal\_max** `number`

Horní mez normálního rozmezí. Může být `null`.

**optimal\_min** `number`

Dolní mez optimálního rozmezí. Může být `null`.

**optimal\_max** `number`

Horní mez užšího rozmezí. Může být `null`.

**sources** `object[]`

Publikované zdroje, které Aniva pro tyto hodnoty zaznamenala. Každá položka má `title` a `url`. `url` může být `null`. Pokud Aniva nezaznamenala žádný zdroj, je seznam prázdný.

**tested\_at** `string`

Datum provedení testu ve formátu `YYYY-MM-DD`. Může být `null`.

**comment** `string`

Volitelný komentář k výsledku. Může být `null`.

**origin** `string`

Kdo doručil dokument, ze kterého tato hodnota pochází, stejně jako `origin` na dokumentu. Hodnota z nahraného dokumentu pochází ze čtení souboru v Aniva, ne z laboratorní zprávy. `null` pro výsledek `planned`.

**lab\_reported** `object`

Vlastní řádek zprávy provádějící laboratoře v původním znění — pro porovnání tohoto payloadu s PDF od laboratoře. Může být `null`, když pro výsledek nemáme původní záznam.

Každé další pole u výsledku je normalizované: `value` a `unit` jsou převedené na výchozí jednotku biomarkeru a `biomarker_name` je náš název analytu, ne název laboratoře. Pole níže normalizovaná nejsou. Ber je jako odkaz na tištěné znění a kanonická pole jako křížovou kontrolu konzistence.

Čísla zde jsou vlastní meze laboratoře na její vlastní škále — `reference_range_min` a `reference_range_max` **nejsou** převedené na jinou jednotku a budou se od `reference_range_lab` lišit všude tam, kde se obě škály liší. Mez, kterou laboratoř nechala otevřenou, zůstává `null`; nic se neodvozuje ani nedoplňuje výchozí hodnotou.

**nahlášeno laboratoří**

**name** `string`

Název analytu tak, jak ho vytiskla laboratoř. Může být `null`.

**code** `string`

Vlastní kód analytu v laboratoři. Může být `null`.

**category** `string`

Nadpis sekce zprávy, např. `Klinische Chemie`. Může být `null`.

**value** `string`

Hodnota tak, jak byla vytištěna. Řetězec, takže nečíselné výsledky zůstanou neporušené (`<0.04`, `negativ`, `1:100`). Může být `null`.

**unit** `string`

Jednotka tak, jak byla vytištěna, např. `U/l`. Může být `null`.

**reference\_range** `string`

Referenční interval tak, jak byl vytištěn, včetně jednostranných prahů: `40 - 129`, `< 50`, `> 55`. Může být `null`.

**reference\_range\_min** `number`

Dolní mez laboratoře, nepřevedená. `null` pro interval, který laboratoř nechala zdola otevřený.

**reference\_range\_max** `number`

Horní mez laboratoře, nepřevedená. `null` pro interval, který laboratoř nechala shora otevřený.

**flag** `string`

Příznak abnormality laboratoře pro tento řádek: `normal`, `high`, `low`, `critical_high`, `critical_low`, `abnormal`. Kód, který nerozpoznáme, projde tak, jak ho laboratoř poslala. Může být `null`.

**result\_status** `string`

Stav výsledku z laboratoře: `final`, `preliminary`, `correction`, `incomplete`, `partial`, `deleted`, `cannot_be_obtained`. Hodnota `preliminary` se může ještě změnit. Pozdější [webhook](https://docs.anivahealth.com/cs/concepts/webhooks.md)`results.updated` ti dá vědět, kdy data načíst znovu. Může být `null`.

**comment** `string`

Vlastní poznámka laboratoře k tomuto řádku. Zarovnávací mezery sloupců jsou sloučeny; znění zůstává beze změny. Může být `null`.

**genetic\_results** `object[]` *required*

Pole genetických výsledků biomarkerů.

**objekt genetického výsledku**

**id** `string`

Identifikátor řádku laboratorního výsledku (UUID). Když laboratoř tento řádek opraví, zůstane stejný, takže ho použij pro upsert. `null` pro výsledek `planned`.

**status** `string` *required*

Stav výsledku. Jedna z hodnot:

* `planned` — objednáno, laboratoř zatím výsledek nevrátila.
* `received` — doručeno z laboratoře.
* `likely_wrong` — automatická kontrola Aniva nebo člen genotyp zpochybňuje. Nepotvrzeno. Viz `status_reason`.
* `fault` — doručeno, ale potvrzeno jako chybné; **nepoužívej klinicky**. Viz `status_reason`.
* `undeliverable` — laboratoř nemohla genotyp stanovit. Viz `status_reason`.

**status\_reason** `string` *required*

Proč je výsledek sporný nebo nepoužitelný. Vyplněno pro `likely_wrong`, `fault` a `undeliverable`, pro všechny ostatní stavy `null`.

**lab\_code** `string`

Laboratorní kód (čárový kód zkumavky), pod kterým byl výsledek zařazen. `null` pro výsledek `planned` a pro výsledky, které laboratoř nahlásila bez kódu.

**biomarker\_id** `integer` *required*

Identifikátor biomarkeru (genu).

**gene** `string` *required*

Symbol genu (např. APOE, MTHFR).

**genotype** `string`

Zobrazení genotypu (např. E3/E4). Může být `null`.

**clinical\_significance** `string`

Celkový klinický význam. Jedna z hodnot `pathogenic`, `likely_pathogenic`, `uncertain`, `likely_benign`, `benign`, `high_risk`, `moderate_risk`, `low_risk`, `protective`, `drug_response`, `poor_metabolizer` nebo `rapid_metabolizer`. Může být `null`.

**risk\_description** `string`

Popis rizika pro tento genotyp. Může být `null`.

**tested\_at** `string`

Datum provedení testu ve formátu `YYYY-MM-DD`. Může být `null`.

**comment** `string`

Volitelný komentář k výsledku. Může být `null`.

**origin** `string`

Kdo doručil dokument, ze kterého tato hodnota pochází, stejně jako `origin` na dokumentu. Hodnota z nahraného dokumentu pochází ze čtení souboru v Aniva, ne z laboratorní zprávy. `null` pro výsledek `planned`.

**variants** `object[]` *required*

Detekované genetické varianty.

**objekt varianty**

**name** `string` *required*

Běžný název varianty (např. APOE E4).

**clinical\_significance** `string`

Klinický význam na úrovni varianty. Může být `null`.

**description** `string`

Popis varianty. Může být `null`.

**hgvs\_c** `string`

HGVS zápis kódující DNA. Může být `null`.

**hgvs\_p** `string`

HGVS zápis proteinu. Může být `null`.

**conditions** `object[]` *required*

Související stavy.

**objekt stavu**

**condition** `string` *required*

Název stavu/onemocnění.

**association\_description** `string`

Popis souvislosti mezi variantou a stavem. Může být `null`.

**badge** `string`

Krátký text štítku pro zobrazení. Může být `null`.

**snvs** `object[]` *required*

Jednonukleotidové varianty definující tuto variantu.

**objekt SNV**

**rs\_id** `string` *required*

Identifikátor dbSNP (např. rs429358).

**allele** `string` *required*

Alela varianty (`A`, `C`, `G`, `T`, `del`, `ins` nebo `undetermined`).

**reference\_allele** `string` *required*

Populační referenční alela.

**hgvs\_c** `string`

HGVS zápis kódující DNA. Může být `null`.

**hgvs\_p** `string`

HGVS zápis proteinu. Může být `null`.

**documents** `object[]` *required*

Dokumenty laboratorních zpráv. Jednotlivé soubory stáhneš pomocí `GET /api/v1/documents/{id}`.

**objekt dokumentu**

**id** `string` *required*

Identifikátor souboru (UUID). Pro stažení souboru ho předej do [Stáhnout dokument](https://docs.anivahealth.com/cs/api/documents/download-document.md).

**file\_name** `string` *required*

Název souboru. [Stáhnout dokument](https://docs.anivahealth.com/cs/api/documents/download-document.md) posílá stejný název v `Content-Disposition`. Obsahuje datum, název dokumentu a laboratorní kód, např. `20260405 - Quade Befund - 7642001234.pdf`. Používej ho jen pro zobrazení. Laboratorní kód čti z `lab_code`, ne z názvu.

**original\_file\_name** `string` *required*

Název souboru přesně tak, jak ho zdroj dodal, např. `7642100312_B0012_FA_V.pdf` z laboratoře nebo vlastní název souboru nahraného členem. Aniva ho nemění.

**origin** `string` *required*

Kdo soubor dodal. Jedna z hodnot `lab` (poslala ho laboratoř), `member_upload` (nahrál ho člen), `staff_upload` (nahrál ho tým Aniva) nebo `partner_upload` (nahrál jsi ho pomocí [Nahrát dokument](https://docs.anivahealth.com/cs/api/documents/upload-document.md)).

**content\_type** `string` *required*

Typ média souboru, např. `application/pdf`, `image/jpeg` nebo `text/csv`. Většina laboratorních zpráv je ve formátu PDF.

**etag** `string`

Verze obsahu souboru. Mění se při každé změně bajtů, takže ji porovnej s uloženou hodnotou a poznáš, jestli soubor stáhnout znovu. [Stáhnout dokument](https://docs.anivahealth.com/cs/api/documents/download-document.md) ji posílá v uvozovkách jako standardní HTTP hlavičku `ETag`. Může být `null`, když uložený soubor chybí.

**size\_bytes** `integer`

Velikost souboru v bajtech. Může být `null`, když uložený soubor chybí.

**lab\_code** `string`

Laboratorní kód (čárový kód zkumavky), ke kterému zpráva patří. Může být `null`, když laboratoř žádný neuvedla.

## Opakovaná volání

Aniva ukládá odpověď tohoto endpointu pro každý API klíč na 60 minut. Opakované volání během
této doby dostane uloženou odpověď, dokud se objednávka domácí testovací sady a její výsledky nezmění. Po změně dostaneš čerstvou
odpověď. Hlavičky `Cache-Status` a `Age` ukazují, že je odpověď
uložená a jak je stará.

Pokud se chceš o změně dozvědět hned, přihlas se k odběru webhook událostí `home_kit_order.results.updated`, `home_kit_order.results.completed` a `home_kit_order.results.fault`.
Viz [Opakované čtení](https://docs.anivahealth.com/cs/concepts/webhooks.md#opakovana-cteni).

## Chybové odpovědi

| Stav | Popis |
| - | - |
| `400` | Neplatný formát ID — zadaná hodnota není platné UUID. |
| `403` | Zakázáno — tvému API klíči chybí rozsah `results_view`, chybí mu oba rozsahy `home_kit_orders_view` i `home_kit_orders_manage`, nebo je objednávka domácí testovací sady mimo tvůj přístupový kontext. |
| `404` | Objednávka domácí testovací sady nebyla nalezena. |
| `500` | Interní chyba serveru. |

```bash cURL theme={null}
curl --request GET \
  --url https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a/results \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
{
  "status": "in_progress",
  "submissions": [
    {
      "lab_code": "7642001234",
      "status": "in_progress"
    }
  ],
  "clinical_results": [
    {
      "id": "e9f1a3c5-6b7d-4c2e-8a4f-1d3b5c7e9f02",
      "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": "1b3d5f7a-9c2e-4a6b-8d0f-2e4a6c8b0d13",
      "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"
    }
  ]
}
```

```json 404 theme={null}
{
  "error": "Home kit order not found"
}
```


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