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
UUID, které Aniva automaticky vygeneruje. Použij ho k aktualizaci objednávky, změně panelu,
aktivaci, zrušení i k načtení výsledků.
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.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.Časové razítko ve formátu ISO 8601, kdy byla objednávka domácí testovací sady vytvořena.
Časové razítko poslední aktualizace ve formátu ISO 8601. Hodnota null, pokud objednávka domácí
testovací sady ještě nebyla aktualizována.
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.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.Objednávka domácí testovací sady, kterou tato nahrazuje, pokud jde o
náhradní sadu. U běžné objednávky má hodnotu
null.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.
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.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=….Č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ě.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ů
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.
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íč:?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: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: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ů.
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: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: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 ukazujepending.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.
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: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 poleindividual_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):
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: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}.