Přejít na hlavní obsah
Objednávka domácí testovací sady pošle pacientovi poštou testovací sadu pro domácí samoodběr. Aniva sadu odešle, pacient si doma sám odebere vzorek a pošle ho poštou zpět. Tím se liší od termínu, což je žilní odběr krve prováděný zdravotníkem na fyzickém odběrovém místě.
Endpointy pro objednávky domácích testovacích sad vyžadují scope home_kit_orders_view (čtení) nebo home_kit_orders_manage (zápis). Aktivovat přijímá i užší scope home_kit_orders_activate. Načíst výsledky a Odeslat výsledky e-mailem navíc vyžadují results_view — laboratorní výsledky a dokumenty jsou jím vždy podmíněné.

Pole

string
povinné
UUID, které Aniva automaticky vygeneruje. Použij ho k aktualizaci objednávky, změně panelu, aktivaci, zrušení i k načtení výsledků.
string
povinné
UUID profilu, ke kterému tato objednávka domácí testovací sady patří.
string
povinné
Aktuální stav životního cyklu. Jedna z hodnot pending, dispatched, activated nebo cancelled. Viz Životní cyklus níže. Podrobnější stav dokončení laboratorních výsledků (in_progress vs. completed) zjistíš z endpointu Načíst výsledky.
object
povinné
Adresa pro doručení sady — v jednom ze dvou tvarů: buď {location_id} s odkazem na známé odběrové místo, nebo pole přímé adresy (name, street, city, postal_code, country_code; company_name / house_number / address_line_2 / state / phone / email jsou volitelná — stejná pole jako v API pro místa). Uveď přesně jednu variantu — odkaz na místo, nebo přímou adresu, ne obojí.
Packstation nebo Postfiliale (pouze Německo): do street zadej Packstation nebo Postfiliale, do house_number trojmístné číslo stanice nebo pobočky a do address_line_2 číslo DHL Postnummer příjemce (6–10 číslic, mezery jsou povolené). Bez čísla Postnummer nelze zásilku objednat. Postfach není podporován.
string
povinné
Časové razítko ve formátu ISO 8601, kdy byla objednávka domácí testovací sady vytvořena.
string
Časové razítko poslední aktualizace ve formátu ISO 8601. Hodnota null, pokud objednávka domácí testovací sady ještě nebyla aktualizována.
object
Úplný objekt profilu pacienta, vložený v každé odpovědi objednávky domácí testovací sady.
object[]
Panel připojený k objednávce domácí testovací sady — vždy přesně jedna položka { panel_id, added_at }, protože domácí testovací sada odpovídá fyzickému produktu v poměru 1:1. Hodnotu panel_id porovnej s endpointem Vypsat panely.
object[]
Biomarkery přidané k objednávce domácí testovací sady mimo její panel. Každá položka má tvar { biomarker_id, added_at }. Každé biomarker_id porovnej s endpointem Vypsat biomarkery s parametrem home_kit=true. U běžné objednávky jde o jednotlivé testy nad rámec panelu; u náhradní sady jde o testy, které laboratoř opakuje.
string
Objednávka domácí testovací sady, kterou tato nahrazuje, pokud jde o náhradní sadu. U běžné objednávky má hodnotu null.
string
Důvod odeslání náhradní sady v jedné větě. U běžné objednávky má hodnotu null.
string[]
Adresy malými písmeny, na které přijde po jednom e-mailu, jakmile jsou všechny laboratorní výsledky konečné. Pole je vždy přítomné — když je vypnuté, je prázdné. Nastavíš ho přes Vytvořit nebo Aktualizovat. Viz E-maily o připravených výsledcích.
object
Tvé vlastní páry klíč/hodnota, které se vracejí beze změny a Aniva je nijak neinterpretuje. Při čtení je pole vždy přítomné — pokud nic nenastavíš, obsahuje {}. Maximálně 20 klíčů; klíče odpovídají [A-Za-z0-9_-] a mají nejvýše 40 znaků; hodnoty jsou řetězec, číslo nebo boolean, přičemž řetězce mohou mít nejvýše 500 znaků; celkem 16 384 bajtů po serializaci. Klíče začínající na aniva_ jsou vyhrazené. Při volání Aktualizovat se metadata slučují: vynechané klíče zůstávají, klíč poslaný s hodnotou null se smaže a {} vymaže vše. Validace probíhá stylem vše, nebo nic. Nikdy do metadata nevkládej osobní ani klinické údaje — nezpracovávají se jako data pacienta.
string
Laboratorní kód vzorku. Jeden kód, tři role: pod tímto kódem se hlásí laboratorní výsledky, je vytištěný na fyzické sadě a pacient ho opíše z krabičky jako aktivační kód. Přidělí se při balení sady — dokud je objednávka ve stavu pending, má hodnotu null, s výjimkou situace, kdy Aniva sadu odešle znovu (viz Životní cyklus). Vždy jen pro čtení. Objednávku k fyzické sadě dohledáš pomocí GET /api/v1/home-kit-orders?lab_code=….
string
Časové razítko odběru nahlášené přes Aktivovat — tedy okamžik v UTC, kdy si pacient vzorek skutečně odebral. Dokud není sada aktivovaná, má hodnotu null. Tento čas odběru se uvádí v laboratorní zprávě.
object[]
Zásilky navázané na tuto objednávku, seřazené od nejstarší vazby, každá ve tvaru { id, added_at } — sada na cestě k pacientovi a u sad se sledovanou zpětnou cestou také vzorek na cestě zpět do laboratoře, přičemž se objeví v okamžiku vytištění štítků. Dokud je objednávka ve stavu pending, je pole prázdné, kromě případu, kdy Aniva sadu odešle znovu. Úplné údaje o zásilkách načteš jedním voláním GET /api/v1/shipments?home_kit_order_id={id} — viz Zásilky.

Životní cyklus

Objednávky domácích testovacích sad mají čtyři stavy životního cyklu:
Když Aniva znovu posílá ztracenou sadu, objednávka se vrátí do stavu pending, ale zachová si svůj lab_code i dřívější balíčky v shipments. Nová sada má stejný kód. Do nového balíčku se vloží nepoužitý zpětný štítek. Tyto dva přechody provádí pouze Aniva; API je nenabízí. Každý přechod odešle webhook home_kit_order.pending nebo home_kit_order.cancelled.
Stavy objednávky domácí testovací sady jsou záměrně obecné. Průběh doručení k pacientovi a zpět se sleduje na zásilkách objednávky — dispatched znamená, že sada má štítek a laboratorní kód, ne že už vyrazila; to ukazuje status odchozí zásilky. Zpracování laboratorních výsledků probíhá na podáních. Dokončení výsledků (in_progress vs. completed) najdeš přes Získat výsledky — pole status na nejvyšší úrovni je in_progress, dokud se neuzavřou všechna podání, potom completed — nebo fault, když všechna podání selhala bez výsledku.

Sledování balíčků

Co se vrátí, závisí na sadě. Jakmile Aniva zabalí krevní sadu, vzniknou dvě zásilky: balíček od Aniva k pacientovi a balíček od pacienta do laboratoře (jeho destination je laboratoř), spárované přes paired_with. Zpětný balíček zůstává ve stavu pending — už se známým sledovacím číslem — dokud ho pacient neodešle. Sada pro střevní mikrobiom má jen jednu zásilku: sadu k pacientovi. Její zpětná obálka je předplacená a nesledovaná, takže se pro cestu zpět nic neobjednává. Pole booked_by říká, kdo objednal štítek: "aniva" nebo "external". Tady lze měnit jen balíček "aniva", a jakmile je štítek vytištěný, tak pouze jeho notes. Každý balíček nese kompletní status_updates dopravce, včetně DHL kódu detail_code pro přesměrování na poštu. Pole home_kit_orders na zásilce vypisuje jen objednávky v rámci tvého přístupu. Viz Přístup.
Složení objednávky domácí testovací sady můžeš měnit jen ve stavu pending. Jakmile je objednávka dispatched (nebo dál — activated/cancelled), výměna panelu i endpointy /biomarkers vrátí 409 Conflict: fyzická sada je zabalená podle zvoleného panelu, takže její obsah je uzamčený ve chvíli, kdy míří k pacientovi. Pokud potřebuješ změnit testy u už uzamčené objednávky, kontaktuj přímo Aniva — většinou to ještě jde a změnu uděláme za tebe, aby obsah sady zůstal v souladu. Pokud už byla sada použitá a nemohla dodat výsledky, objednej místo toho náhradní sadu.

Výpis objednávek domácích testovacích sad

Načti všechny objednávky domácích testovacích sad dostupné pro tvůj API klíč:
Volitelně předej ?profile_id={uuid} pro filtrování podle konkrétního profilu, nebo ?lab_code={code} pro dohledání objednávky podle fyzické sady v ruce — přirozený první krok při aktivaci.

Vytvoření objednávky domácí testovací sady

Zadej objednávku domácí testovací sady pro profil pacienta:
Předej profile_id, delivery_address a jedno panel_id. Objednávka se vytvoří ve stavu pending. Předej volitelnou hlavičku Idempotency-Key, aby opakovaný požadavek neobjednal druhou sadu — viz Idempotence. Přesně jeden panel, protože domácí testovací sada odpovídá 1:1 fyzickému produktu — panel je samotná sada. Objednat lze jen panely, které Aniva nastavila jako domácí testovací sady; jakýkoli jiný panel vrátí 422. Při vytvoření je povinný, protože objednávka jde hned do balicí fronty a balení může začít okamžitě. Dokud je objednávka ve stavu pending, můžeš panel vyměnit přes Upravit. Pokud posíláš druhou sadu za tu, ze které nešlo získat výsledky, předej místo výběru panelu replaces_home_kit_order_id — viz Náhradní sady.

Náhradní sady

Někdy ze sady nelze získat výsledky: pacient nedokázal naplnit zkumavku, vzorek dorazil s příliš malým množstvím materiálu, nebo laboratoř nemohla část z něj analyzovat. Objednej za ni náhradu:
Náhrada je nová objednávka s novým laboratorním kódem, i když první sada nikdy nebyla aktivovaná: laboratoř potřebuje novou žádanku a dva vzorky pod jedním kódem od sebe nelze rozlišit. Obě objednávky zůstávají čitelné a jsou propojené přes replaces_home_kit_order_id. Nahrazovaná objednávka zůstává nedotčená. Zachová si svůj stav, laboratorní kód i všechny výsledky už k ní přiřazené, takže pacient, který první sadu přece jen odešle, dostane vše, co z ní laboratoř dokáže vyčíst. Panel se dědí. Vynech panel_id a náhrada převezme panel nahrazované objednávky — to je to, co si pacient koupil a jak je označená krabička. Jiný panel pošli jen při náhradě celého panelu; kombinace panelu a podmnožiny markerů se zamítne s 422, protože podmnožina dává smysl jen v rámci panelu, ze kterého byla vybrána. Panel náhradní objednávky pak už nelze ani později vyměnit. Vybereš si, co se zopakuje. Pošli biomarker_ids s markery, které selhaly, a laboratoř zopakuje jen ty, takže sada dorazí jen se zkumavkami, které jsou pro ně potřeba. Když pole vynecháš, zopakuje se celý panel — správná volba, když se nepodařilo analyzovat vůbec nic. Nevyžaduje to žádný extra scope: opakování markerů, za které pacient už zaplatil, není výběr à la carte. Tyto markery pak už nejde odebrat, protože tvoří celou žádanku.
Markery se opakují po skupinách panelu, ne po jednom. Uvedením jednoho markeru ze skupiny se zopakuje celá skupina, protože nelze zadat laboratorní objednávku, která vrátí víc, než bylo objednáno. Náhrada pro jediný marker se proto může vrátit s více než jedním výsledkem a počet zkumavek může být vyšší, než naznačuje seznam markerů.
Pro jednu sadu může být na cestě vždy jen jedna náhrada — dokud je náhrada ve stavu pending nebo dispatched, druhé vytvoření pro stejnou objednávku vrátí 409 s jejím uvedením. Výsledky dorazí pod vlastním lab_code náhrady, přes její vlastní Získat výsledky. Náhrada není řešení pro balíček, který nikdy nedorazil. Místo toho kontaktuj Aniva: jde o opětovné odeslání stejné objednávky pod stejným laboratorním kódem, ne o novou.

Úprava objednávky domácí testovací sady

Změň doručovací adresu, vyměň panel, uprav svá metadata nebo nahraď e-maily pro oznámení o výsledcích:
Uveď jen pole, která chceš změnit. Pole panel_id nahradí připojený panel — při přesně jednom panelu na sadu je výměna jediná smysluplná operace s panelem, proto neexistují endpointy pro přidání nebo odebrání panelu. Adresu a panel lze měnit jen ve stavu pending; pole metadata zůstává zapisovatelné po celou dobu života objednávky. Pole results_ready_emails zůstává zapisovatelné, dokud není objednávka ve stavu cancelled.

Zrušení objednávky domácí testovací sady

Zruš objednávku domácí testovací sady, která už není potřeba:
Tím se nastaví stav objednávky domácí testovací sady na cancelled. V odpovědi se vrátí zrušená objednávka domácí testovací sady. Zrušit lze jen objednávku ve stavu pending. Od stavu dispatched dál je sada zabalená a má štítek — automatické stažení neexistuje — a volání vrátí 409. Pokud potřebuješ zastavit už odeslanou sadu, kontaktuj přímo Aniva. Zrušení objednávky ve stavu pending, jejíž sada už byla objednána u expedice, ji zruší i tam a volání uspěje jen tehdy, když to expedice přijme:
  • 409 — sada už byla zabalená a opatřená štítkem, takže ji nelze stáhnout zpět, i když objednávka stále ukazuje pending.
  • 502 — expedice zrušení odmítla (chyba obsahuje její důvod) nebo nebyla dostupná. Nic se nezměnilo — objednávka stále platí a můžeš ji zkusit zrušit znovu.
Zrušení, které vrátí chybu, nechá objednávku přesně tak, jak byla, takže 200 je jediné potvrzení, že žádná sada nepřijde. Zrušení objednávky, která už je ve stavu cancelled, vrátí stejnou odpověď 200, bez ohledu na to, z jakého stavu byla zrušena.

Aktivace objednávky domácí testovací sady

Jakmile pacient odebere vzorek, nahlas to:
Předej activated_at — okamžik, kdy pacient vzorek skutečně odebral, jako časový údaj v UTC. Tento čas odběru bude uvedený v laboratorní zprávě, proto pošli skutečný okamžik odběru, ne čas svého zpracování. Aktivace je nevratná: objednávka přejde do stavu activated a už ji nelze zrušit ani změnit. Jde o obdobu Potvrdit odběr krve pro domácí testovací sady, ale bez čárového kódu — kód sady se přikládá při balení, takže ho nikdy nepotřebuješ znát. Objednávka v tu chvíli už musí mít svůj lab_code; bez něj vrátí 409. Aktivace zároveň zadá laboratorní objednávku: panel sady se objedná v laboratoři pod jejím lab_code, takže laboratoř vrácený vzorek očekává a výsledky se k němu přiřadí, jakmile je nahlásí. Probíhá to až po odeslání odpovědi a případný problém na straně laboratoře řeší Aniva, nepropisuje se do tvého požadavku.

Jednotlivé biomarkery

K objednávce domácí testovací sady můžeš přidat jednotlivé biomarkery jako testy à la carte mimo panel. Hodí se to, když chceš k sadě výběr na míru. Přidané biomarkery se v odpovědi objednávky domácí testovací sady zobrazí jako pole individual_biomarkers (na stejné úrovni jako panels). Oba endpointy pro biomarkery vyžadují kromě home_kit_orders_manage i scope home_kit_orders_individual_biomarker_selection — domácí testovací sady se objednávají po panelech, takže jednotlivé markery se povolují pro každého partnera zvlášť. Pokud to tvoje integrace potřebuje, obrať se na Aniva. Přidej biomarkery (idempotentní – už připojené biomarkery zůstanou):
Odeber biomarkery (idempotentní — nepřiřazené ID se ignoruje):
Oba endpointy přijímají pole biomarker_ids. ID biomarkerů zjistíš přes Vypsat biomarkery s home_kit=true. Biomarkery můžeš měnit jen dokud je sada ve stavu pending (viz Životní cyklus).

Načtení laboratorních výsledků

Jakmile laboratoř zpracuje vrácený vzorek, načti klinické a genetické výsledky:
Odpověď obsahuje plánované testy (stav planned) spolu s již doručenými výsledky, takže můžeš sledovat, na co se ještě čeká. Výsledky se přiřazují pod lab_code objednávky a chodí marker po markeru, jak je laboratoř postupně analyzuje, takže částečné payloady jsou normální. Pole status na nejvyšší úrovni má až do konečné zprávy hodnotu in_progress, potom completed (nebo fault, pokud všechny laboratorní objednávky selhaly bez výsledků) — podle něj poznáš, jestli je laboratorní zpracování objednávky domácí testovací sady hotové. Když k tomu dojde, upozorní tě webhook home_kit_order.results.completed, takže se nemusíš pravidelně dotazovat. Odkazy na PDF s laboratorními zprávami najdeš v poli documents — stáhneš je pomocí GET /api/v1/documents/{id}.

Příklad objednávky domácí testovací sady