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

# Termíny

> Jak fungují termíny odběru krve v Aniva API pro laboratorní testy: rezervace, panely, biomarkery, změny stavu a zrušení.

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](https://docs.anivahealth.com/cs/concepts/home-kit-orders.md).

## Pole

**id** `string` *required*

UUID automaticky vygenerované systémem Aniva. Použij ho k přidání panelů, potvrzení odběru krve a získání výsledků.

**profile\_id** `string` *required*

UUID profilu, ke kterému tento termín patří.

**location\_id** `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](https://docs.anivahealth.com/cs/concepts/home-kit-orders.md).

**scheduled\_at** `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](https://docs.anivahealth.com/cs/api/appointments/create-appointment.md#minimalni-predstih)).

**status** `string` *required*

Aktuální stav životního cyklu. Jedna z hodnot `pending`, `confirmed`, `blood_drawn` nebo `cancelled`. Viz
[Životní cyklus](#zivotni-cyklus) níže. Podrobnější stav dokončení laboratorních výsledků (`in_progress` vs. `completed`)
zjistíš přes [Získat výsledky](https://docs.anivahealth.com/cs/api/appointments/get-results.md); 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](https://docs.anivahealth.com/cs/api/shipments/get-shipment.md).

**cancellation\_reason** `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`.

**results\_ready\_emails** `string[]` *required*

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](https://docs.anivahealth.com/cs/concepts/results.md#e-maily-o-pripravenych-vysledcich).

**draw\_method** `string` *required*

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](https://docs.anivahealth.com/cs/concepts/locations.md). Po odběru krve uvádí metodu, která byla použita.

**created\_at** `string` *required*

Časové razítko ISO 8601 vytvoření termínu.

**updated\_at** `string`

Časové razítko poslední úpravy ve formátu ISO 8601. Null, pokud termín nebyl nikdy upraven.

**lab\_codes** `string[]` *required*

Laboratorní kódy (čárové kódy zkumavek) zaznamenané přes [Potvrdit odběr krve](https://docs.anivahealth.com/cs/api/appointments/confirm-blood-draw.md),
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`.

**panels** `object[]` *required*

Panely připojené k tomuto termínu jako položky `{ panel_id, added_at }`. Viz
[Přidání panelů](#pridani-panelu).

**individual\_biomarkers** `object[]` *required*

Samostatné biomarkery připojené k tomuto termínu jako položky `{ biomarker_id, added_at }`. Viz
[Jednotlivé biomarkery](#jednotlive-biomarkery).

**shipments** `object[]` *required*

Zásilky propojené s tímto termínem jako položky `{ id, added_at }`, od nejstaršího propojení. Viz
[Propojení zásilek](#propojeni-zasilek).

**profile** `object` *required*

Celý objekt profilu pacienta vložený do každé odpovědi termínu. Pole níže
tvoří jen podmnožinu. [Získat termín](https://docs.anivahealth.com/cs/api/appointments/get-appointment.md) uvádí všechna.

**vlastnosti**

**id** `string`

UUID přiřazeného profilu.

**first\_name** `string`

Jméno pacienta.

**last\_name** `string`

Příjmení pacienta.

**email** `string`

E-mailová adresa pacienta.

**date\_of\_birth** `string`

Datum narození ve formátu `YYYY-MM-DD`.

**sex** `integer`

Biologické pohlaví podle ISO/IEC 5218.

## Životní cyklus

Termíny mají čtyři stavy životního cyklu:

```
pending → confirmed → blood_drawn
   │          │             │
   └──────────┴─────────────┴──→ cancelled
```

| Stav | Význam |
| - | - |
| `pending` | Termín je naplánovaný a čeká na potvrzení. Lze ho [upravit](https://docs.anivahealth.com/cs/api/appointments/update-appointment.md) nebo [zrušit](https://docs.anivahealth.com/cs/api/appointments/cancel-appointment.md). |
| `confirmed` | Termín byl potvrzen (např. ordinací), ale odběr krve ještě neproběhl. Stále ho lze upravit nebo zrušit. |
| `blood_drawn` | Laboratorní kódy byly odeslány přes [Potvrdit odběr krve](https://docs.anivahealth.com/cs/api/appointments/confirm-blood-draw.md) a spustilo se zpracování laboratorní objednávky. Panely jsou uzamčené a termín už nelze přeobjednat ani zrušit. |
| `cancelled` | Termín byl zrušen. Konečný stav — žádné další přechody. |

> [!NOTE]
>
> 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](https://docs.anivahealth.com/cs/api/appointments/get-results.md) — 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](https://docs.anivahealth.com/cs/api/shipments/get-shipment.md) — každá
>   zásilka má vlastní `status` a záznam událostí `status_updates`.
>
> Každá změna stavu odešle [webhook](https://docs.anivahealth.com/cs/concepts/webhooks.md) `appointment.*`, například
> `appointment.confirmed`. Nový čas nebo odběrové místo odešle `appointment.rescheduled`.

> [!WARNING]
>
> 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íč:

```
GET /api/v1/appointments
```

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:

```
PATCH /api/v1/appointments/{id}
```

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](https://docs.anivahealth.com/cs/api/appointments/create-appointment.md) i
[Upravit termín](https://docs.anivahealth.com/cs/api/appointments/update-appointment.md) 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.

> [!NOTE]
>
> Ú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:

```
DELETE /api/v1/appointments/{id}
```

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

> [!NOTE]
>
> 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:

```
POST /api/v1/appointments/{id}/panels
```

V poli `panel_ids` předej pole UUID panelů. ID panelů ti Aniva poskytne pro tvůj partnerský účet.

> [!NOTE]
>
> 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:

```
DELETE /api/v1/appointments/{id}/panels
```

V poli `panel_ids` předej pole UUID panelů. Odebrání je idempotentní: panel, který není připojený, se ignoruje.

> [!NOTE]
>
> 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):

```
PATCH /api/v1/appointments/{id}/biomarkers
```

Odeber biomarkery (idempotentní – biomarkery, které nejsou připojené, se ignorují):

```
DELETE /api/v1/appointments/{id}/biomarkers
```

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](https://docs.anivahealth.com/cs/api/biomarkers/list-biomarkers.md).

> [!NOTE]
>
> 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ů:

```
GET /api/v1/appointments/{id}/preview
```

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](https://docs.anivahealth.com/cs/concepts/pricing.md)), 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`.

> [!NOTE]
>
> 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:

```
POST /api/v1/appointments/{id}/confirm
```

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

> [!WARNING]
>
> `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](https://docs.anivahealth.com/cs/api/shipments/get-shipment.md) – 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](https://docs.anivahealth.com/cs/api/shipments/get-shipment.md) /
[Získat termín](https://docs.anivahealth.com/cs/api/appointments/get-appointment.md)) pro kompletní payload.

Zásilky se propojují při vytvoření přes pole `appointment_id` ve
[Vytvořit zásilku](https://docs.anivahealth.com/cs/api/shipments/create-shipment.md). Po vytvoření spravuj vazby ze strany zásilky
pomocí [Připojit termíny k zásilce](https://docs.anivahealth.com/cs/api/shipments/attach-appointments-to-shipment.md) a
[Odpojit termíny od zásilky](https://docs.anivahealth.com/cs/api/shipments/detach-appointments-from-shipment.md); 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](https://docs.anivahealth.com/cs/api/shipments/list-shipments.md) 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:

```
GET /api/v1/appointments/{id}/results
```

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](https://docs.anivahealth.com/cs/concepts/webhooks.md) `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

```json theme={null}
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "profile_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "location_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "scheduled_at": "2026-04-15T08:30:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": null,
  "profile": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "handle": null,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1990-06-15",
    "height": 170,
    "weight": 62,
    "language": "en",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:55:00Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T10:05:00Z"
    }
  ],
  "individual_biomarkers": [
    {
      "biomarker_id": 42,
      "added_at": "2026-04-01T10:07:00Z"
    }
  ],
  "shipments": [
    {
      "id": "P2611194821",
      "added_at": "2026-04-15T07:00:00Z"
    }
  ],
  "lab_codes": []
}
```


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