Přejít na hlavní obsah
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í: 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ů. 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í.
  • 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ý.
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č: 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ů

Při zobrazování výsledků pacientům použij přímo pole value — už obsahuje opravenou hodnotu, pokud existuje.
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

Stavy genetických výsledků

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).
  • 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.
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 pro termín nebo Odeslat výsledky e-mailem 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.

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 nebo Vytvořit objednávku domácí testovací sady. Seznam můžeš později změnit přes Aktualizovat termín nebo Aktualizovat objednávku domácí testovací sady; [] 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 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