Přejít na hlavní obsah
Termín je naplánovaný odběr krve pro profil pacienta na fyzickém odběrovém místě, který provádí zdravotnický pracovník. Sady zasílané pacientovi poštou nejsou termíny — viz Objednávky domácích testovacích sad.

Pole

string
povinné
UUID automaticky vygenerované systémem Aniva. Použij ho k přidání panelů, potvrzení odběru krve a získání výsledků.
string
povinné
UUID profilu, ke kterému tento termín patří.
string
UUID odběrového místa, kde odběr krve proběhne. Domácí testovací sady nejsou termíny — viz Objednávky domácích testovacích sad.
string
Datum a čas plánovaného odběru krve ve formátu ISO 8601. Vždy se vrací v UTC s příponou Z (např. 2026-04-15T08:30:00Z). Při vytvoření / úpravě musí hodnota obsahovat označení časového pásma (buď Z, nebo explicitní posun jako +02:00) — hodnoty bez časového pásma jsou zamítnuty. Musí být v budoucnosti a na odběrových místech provozovaných společností Aniva alespoň 12 hodin předem (minimální předstih).
string
povinné
Aktuální stav životního cyklu. Jedna z hodnot pending, confirmed, blood_drawn nebo cancelled. Viz Životní cyklus níže. Podrobnější stav dokončení laboratorních výsledků (in_progress vs. completed) zjistíš přes Získat výsledky; detailnější průběh zásilky (na cestě, doručeno atd.) zjistíš přes jednotlivé položky v poli shipments pomocí Získat zásilku.
string
Volný text s důvodem zaznamenaným při zrušení termínu (např. nedostavení se, pozdní zrušení, „Nezdařilo se. Nutné opakování“). null, pokud status není cancelled.
string[]
povinné
Adresy malými písmeny, z nichž každá dostane jeden e-mail, jakmile jsou všechny laboratorní výsledky konečné. Prázdné, když je vypnuto. Viz E-maily o připravených výsledcích.
string
povinné
Způsob odběru krve: capillary (z konečku prstu nebo horní části paže do mikrozkumavek) nebo venous (ze žíly do zkumavek). Jde o metodu nastavenou u termínu, jinak default_draw_method jeho místa. Po odběru krve uvádí metodu, která byla použita.
string
povinné
Časové razítko ISO 8601 vytvoření termínu.
string
Časové razítko poslední úpravy ve formátu ISO 8601. Null, pokud termín nebyl nikdy upraven.
string[]
povinné
Laboratorní kódy (čárové kódy zkumavek) zaznamenané přes Potvrdit odběr krve, v pořadí skenování. Prázdné, dokud není odběr krve potvrzen. Žilní odběr má jeden kód vytištěný na každé zkumavce; kapilární odběr má jeden kód na každou mikrozkumavku. Výsledky a dokumenty na ně odkazují přes lab_code.
object[]
povinné
Panely připojené k tomuto termínu jako položky { panel_id, added_at }. Viz Přidání panelů.
object[]
povinné
Samostatné biomarkery připojené k tomuto termínu jako položky { biomarker_id, added_at }. Viz Jednotlivé biomarkery.
object[]
povinné
Zásilky propojené s tímto termínem jako položky { id, added_at }, od nejstaršího propojení. Viz Propojení zásilek.
object
povinné
Celý objekt profilu pacienta vložený do každé odpovědi termínu. Pole níže tvoří jen podmnožinu. Získat termín uvádí všechna.

Životní cyklus

Termíny mají čtyři stavy životního cyklu:
Stav termínu je záměrně obecný — podrobnější průběh poskytují samostatné endpointy:
  • Dokončení laboratorních výsledků → Získat výsledky — pole status na nejvyšší úrovni má hodnotu in_progress nebo completed.
  • Průběh zásilky (na cestě, doručeno atd.) → projdi každou položku v poli shipments u termínu přes Získat zásilku — každá zásilka má vlastní status a záznam událostí status_updates.
Každá změna stavu odešle webhook appointment.*, například appointment.confirmed. Nový čas nebo odběrové místo odešle appointment.rescheduled.
Potvrzení termínu (přechod do stavu blood_drawn) je nevratné. Jakmile odešleš laboratorní kód(y), spustí se zpracování laboratorní objednávky a nelze ho vrátit zpět. Úpravy a zrušení jsou možné jen tehdy, když je termín ve stavu pending nebo confirmed.

Výpis termínů

Načti všechny termíny dostupné pro tvůj API klíč:
Volitelně předej ?profile_id={uuid} pro filtrování podle konkrétního profilu. Bez tohoto parametru se použije výchozí časové okno (poslední 2 měsíce až příští 1 měsíc).

Úprava termínu

Před potvrzením odběru krve můžeš změnit čas nebo odběrové místo:
Pro úpravu předej libovolnou kombinaci polí scheduled_at, location_id, draw_method a results_ready_emails. Uveď jen pole, která chceš změnit.

Metoda odběru krve

Každý termín má draw_method: capillary (ze špičky prstu nebo paže do mikrozkumavek) nebo venous (ze žíly do zkumavek). Týká se jen odběru krve. Moč, stěry a další nekrevní vzorky se u obou metod odebírají stejně. Ve výchozím nastavení se použije default_draw_method daného místa. Pokud chceš použít jinou metodu, nastav draw_method při vytvoření nebo úpravě, případně nastav null pro návrat k výchozí hodnotě místa. Místo musí tuto metodu uvádět ve svém draw_methods a rezervované testy s ní musí jít provést, jinak požadavek vrátí 400. Po odběru krve ji nemůžeš změnit. Po odběru krve obsahuje draw_method metodu, která byla použita.

Jeden termín na profil, místo a čas

Profil může mít nejvýše jeden nezrušený termín pro každou dvojici (location_id, scheduled_at) — jednomu člověku nelze odebrat krev dvakrát na jednom místě ve stejný okamžik, bez ohledu na to, kolik souběžných rezervací místo přijímá. Oba endpointy Vytvořit termín i Upravit termín toto pravidlo vynucují a vrací 409 s polem appointment_id odkazujícím na již existující termín. Ber tuto odpověď jako už rezervovaný termín, nikoli jako chybu k opakování: načti, přeobjednej nebo zruš uvedený termín. V praxi to znamená, že opakované vytváření je bezpečné. Požadavek na vytvoření, který po síťovém timeoutu odešleš znovu, nebo který uživatel spustí dvakrát, vyústí v jeden termín místo dvou – což také znamená, že nikdy nemusíš zpětně řešit duplicitní rezervace pro stejného pacienta.
Úpravy jsou povolené jen před odběrem krve – tedy dokud je termín ve stavu pending nebo confirmed. Jakmile termín přejde do stavu blood_drawn nebo je ve stavu cancelled, už ho nelze upravit. Jedinou výjimkou je results_ready_emails: můžeš ho samostatně změnit i po odběru krve.

Zrušení termínu

Zruš termín, který už není potřeba:
Tím se stav termínu nastaví na cancelled. Zrušený termín se vrátí v odpovědi. Volitelně pošli v těle požadavku cancellation_reason (až 500 znaků), aby se zaznamenal důvod. Uloží se k termínu a při pozdějším čtení se vrátí jako cancellation_reason.
Zrušení je povolené jen před odběrem krve – tedy dokud je termín ve stavu pending nebo confirmed. Termíny, které už přešly do stavu blood_drawn, nelze zrušit.

Přidání panelů

Před potvrzením odběru krve přidej panely krevních testů, které chceš provést, zavoláním:
V poli panel_ids předej pole UUID panelů. ID panelů ti Aniva poskytne pro tvůj partnerský účet.
Panely je nutné přidat před odběrem krve – tedy dokud je termín ve stavu pending nebo confirmed. Jakmile termín přejde do stavu blood_drawn, nemůžeš už panely přidávat ani měnit.

Odebrání panelů

Pokud potřebuješ panely před odběrem krve odebrat, zavolej:
V poli panel_ids předej pole UUID panelů. Odebrání je idempotentní: panel, který není připojený, se ignoruje.
Stejně jako přidávání panelů je i odebrání povolené jen před odběrem krve – tedy dokud je termín ve stavu pending nebo confirmed. Jakmile termín přejde do stavu blood_drawn, panely už odebrat nelze.

Jednotlivé biomarkery

K termínu můžeš připojit jednotlivé biomarkery jako testy à la carte, mimo jakýkoli předpřipravený panel. Hodí se to, když zdravotník chce výběr na míru místo předem definovaného balíčku. Připojené biomarkery se v odpovědi pro termín zobrazí jako pole individual_biomarkers (na stejné úrovni jako panels). O směrování rozhoduje v dalším kroku pipeline pro logistiku objednávek podle mapování jednotlivých biomarkerů na laboratoře. Přidej biomarkery (idempotentní – už připojené biomarkery zůstanou):
Odeber biomarkery (idempotentní – biomarkery, které nejsou připojené, se ignorují):
Oba endpointy přijímají pole biomarker_ids a kontrolují výslednou sadu podle pravidel úplnosti jednotlivých laboratoří – objednávka, kterou nelze čistě zadat (např. poměr CRP/HDL bez CRP a HDL), vrátí 400 s biomarkery, které je potřeba přidat, a nic neuloží. ID biomarkerů zjistíš přes Vypsat biomarkery.
Stejně jako úpravy panelů lze jednotlivé biomarkery přidávat nebo odebírat jen před odběrem krve – tedy dokud je termín ve stavu pending nebo confirmed. Jakmile termín přejde do stavu blood_drawn, vlastní výběr se uzamkne.

Náhled požadavků na odběrové nádobky

Po přidání panelů nebo jednotlivých biomarkerů si zobraz náhled fyzických odběrových nádobek, které budou potřeba pro odběr vzorků:
Pole containers v odpovědi obsahuje typ, název, barvu víčka, objem, katalogové číslo výrobce a počet pro každou potřebnou nádobku. Zdravotníkům to pomůže připravit správný materiál před odběrem krve. Odpověď také obsahuje objekt pricing – celkové vyúčtování termínu (uplatněné položky, připojené panely a jeden řádek na každý dodaný biomarker, oceněné podle tvého ceníku s maloobchodní cenou vedle; viz Ceny), který je vyplněný, když má termín připojené testy a tvůj klíč má scope prices_view, jinak je null. routing se záměrně nikdy nezpřístupňuje a je vždy null.
Náhled odpovídá aktuálně připojeným panelům a biomarkerům. Pokud po zobrazení náhledu panely přidáš nebo odebereš, zavolej endpoint náhledu znovu a získáš aktualizované požadavky na odběrové nádobky.

Potvrzení odběru krve

Po odběru krve odešli laboratorní kódy (čárové kódy zkumavek), čímž spustíš pipeline laboratorních objednávek:
Pošli lab_code, když je na všech zkumavkách vytištěný jeden kód (žilní odběr), nebo lab_codes s jednou položkou na kód – u každé s panel_ids, které pokrývá – když se každý panel odebírá do vlastních zkumavek s vlastním kódem (kapilární odběr). Každý panel je pak samostatnou laboratorní žádankou pod svým kódem. Kódy se u termínu vrátí jako lab_codes. Při kapilárním odběru se odběr rozděluje do mikrozkumavek. Nejdřív jdou panely v pořadí rezervace. Jednotlivé biomarkery pak zaplní volné místo v mikrozkumavkách panelů. Když potřebují víc místa, otevřou se nové mikrozkumavky. Rozdělujeme je rovnoměrně. Každá mikrozkumavka pojme nejvýš 150 µl jednotlivých biomarkerů. Volání, která mění panely nebo biomarkery, odpoví 400, pokud výsledná sada toto pravidlo poruší. Tím se stav termínu změní na blood_drawn a spustí se laboratorní zpracování. Tato akce je nevratná.

Vyzvednutí zásilky

POST /api/v1/appointments/pickup byl odstraněn spolu se stavem termínu shipment_picked_up. Nyní vrací 405 Method Not Allowed, protože cesta propadne na routu pro termín podle ID. V poslední fázi tento endpoint sloužil jako no-op, který volání přijal a nic neudělal, takže jeho odstranění nemění žádné chování, na které se spoléháš.
Pro sledování průběhu po odběru krve přejdi u každé položky ve vloženém poli shipments termínu na Získat zásilku – každá zásilka nese vlastní status a historii status_updates.

Propojení zásilek

Termín může být propojený s jednou nebo více zásilkami (a naopak – jde o vazbu mnoho ku mnoha). Aktuální sada vazeb se zobrazuje přímo na obou stranách:
  • u termínu jako pole shipments s položkami { id, added_at };
  • u zásilky jako pole appointments s položkami { id, added_at }.
Obě pole jsou seřazená od nejstarší vazby. Každé id odkazuje na kanonický endpoint detailu (Získat zásilku / Získat termín) pro kompletní payload. Zásilky se propojují při vytvoření přes pole appointment_id ve Vytvořit zásilku. Po vytvoření spravuj vazby ze strany zásilky pomocí Připojit termíny k zásilce a Odpojit termíny od zásilky; každý vrátí seznam termínů dané zásilky po změně. Pro úplné načtení balíků termínu použij Vypsat zásilky s ?appointment_id=. Pravidlo pro změny zní: vazby lze vytvářet nebo odebírat, pokud BUĎ
  • termín je už po odběru krve (blood_drawn), nebo
  • zásilka byla vytvořena před méně než 24 hodinami.
Mimo toto okno je vazba uzamčená, aby historické záznamy zůstaly stabilní.

Načtení laboratorních výsledků

Jakmile laboratoř zpracuje vzorky krve, načti klinické a genetické výsledky:
Odpověď kromě přijatých výsledků obsahuje i plánované testy (stav planned), takže můžeš sledovat, co ještě zbývá. Pole status na nejvyšší úrovni má hodnotu in_progress, dokud se neuzavřou všechny žádanky, a potom completed (nebo fault, když žádná z nich nedodala výsledky) — podle toho poznáš, jestli je laboratorní zpracování termínu hotové. Kdy k tomu dojde, ti oznámí webhook appointment.results.completed, takže nemusíš stav průběžně dotazovat. Pole submissions to rozepisuje podle jednotlivých laboratorních žádanek, každá má svůj lab_code. Každý přijatý výsledek i dokument nese lab_code, pod kterým byl zaevidován. PDF s laboratorními zprávami najdeš v poli documents — stáhneš je pomocí GET /api/v1/documents/{id}.

Příklad termínu