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

# Vytvořit termín

> Naplánovat termín odběru krve pro profil na testovacím místě

Naplánuj termín odběru krve pro profil pacienta na konkrétním odběrovém místě. Po vytvoření přejde termín standardně do stavu `confirmed` (některá odběrová místa mohou mít jako výchozí stav `pending` — jde o nastavení konkrétního místa). Pomocí [Přidat panely](https://docs.anivahealth.com/cs/api/appointments/add-panels.md) připoj panely krevních testů před [potvrzením odběru krve](https://docs.anivahealth.com/cs/api/appointments/confirm-blood-draw.md).

> [!NOTE]
>
> Profil může mít nejvýše **jeden** termín pro dané odběrové místo a čas. Vytvoření termínu pro
> slot, který už profil obsazuje, vrátí `409` s existujícím `appointment_id` místo druhého termínu
> — opakovaný nebo omylem znovu odeslaný požadavek tak nikdy nevytvoří duplicitní rezervaci. Viz
> [Duplicitní termíny](#duplicitni-terminy).

Odešli volitelnou hlavičku `Idempotency-Key`, aby šlo toto vytvoření bezpečně zopakovat — opakované použití stejného klíče vrátí původní odpověď místo vytvoření dalšího záznamu. Viz [Idempotence](https://docs.anivahealth.com/cs/concepts/idempotency.md).

Vyžaduje rozsah `appointments_schedule`.

## Požadavek

### Parametry těla

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

UUID profilu pacienta, pro který se termín vytváří.

**location\_id** `string` *required*

UUID odběrového místa, kde odběr krve proběhne. Dostupná ID míst najdeš přes [Vypsat odběrová
místa](https://docs.anivahealth.com/cs/api/locations/list-locations.md).

**scheduled\_at** `string` *required*

Datum a čas termínu ve formátu ISO 8601 (např. `2026-05-15T10:30:00Z` nebo
`2026-05-15T12:30:00+02:00`). **Musí obsahovat označení časového pásma** — buď `Z`, nebo explicitní
posun jako `+02:00`; hodnoty bez časového pásma jsou odmítnuty. Musí být v budoucnosti.

Musí jít o přesný začátek slotu v rozvrhu odběrového místa a slot musí mít volnou kapacitu — nejprve
načti [Získat dostupnost](https://docs.anivahealth.com/cs/api/locations/get-availability.md). Časy mimo rozvrh vracejí `400`; obsazený
slot vrací `409`. Na odběrových místech provozovaných Anivou musí být termín také alespoň 12 hodin
dopředu — viz [Minimální předstih](#minimalni-predstih).

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

Až 5 adres, z nichž každá dostane jeden e-mail, jakmile budou všechny laboratorní výsledky konečné.
E-mail odkazuje na stránku s výsledky v administračním panelu Aniva. Tvůj klíč potřebuje oprávnění
`results_view` k pacientovi, jinak `403`. Vynech ho, pokud chceš použít výchozí adresy nastavené
pro skupinu pacienta. Prázdný seznam e-maily vypne. 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`

Způsob odběru krve: `capillary` nebo `venous`. Vynech ho, pokud chceš použít `default_draw_method`
daného odběrového místa. Odběrové místo musí tuto metodu uvádět v `draw_methods`, jinak `400`.

## Odpověď

Při úspěchu vrátí API `201 Created` s novým termínem.

**id** `string` *required*

Jedinečný identifikátor termínu (UUID).

**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íhá.

**scheduled\_at** `string`

Plánované datum a čas termínu v UTC (ISO 8601 s příponou `Z`, např.
`2026-05-15T10:30:00Z`). Může být `null`.

**status** `string` *required*

Aktuální stav termínu. Jedna z hodnot `pending`, `confirmed`, `blood_drawn` nebo `cancelled`.
Podrobnější stav dokončení laboratorních výsledků najdeš v [Získat výsledky](https://docs.anivahealth.com/cs/api/appointments/get-results.md);
detailnější průběh zásilky v jednotlivých položkách pole `shipments` (viz níže) a následně v [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.

**profile** `object` *required*

Profil pacienta spojený s tímto termínem.

**profile**

**id** `string`

Jedinečný identifikátor profilu (UUID).

**handle** `string`

Přezdívka profilu nebo uživatelské jméno. Může být `null`.

**first\_name** `string`

Křestní jméno. Může být `null`.

**last\_name** `string`

Příjmení. Může být `null`.

**email** `string`

E-mailová adresa. Může být `null`.

**phone** `string`

Telefonní číslo ve formátu E.164. Může být `null`.

**sex** `integer`

Biologické pohlaví podle ISO/IEC 5218. Může být `null`.

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

Datum narození ve formátu `YYYY-MM-DD`. Může být `null`.

**height** `number`

Výška v centimetrech. Může být `null`.

**weight** `number`

Hmotnost v kilogramech. Může být `null`.

**language** `string`

Preferovaný jazyk: jeden ze 32 kódů ve [Vytvořit profil](https://docs.anivahealth.com/cs/api/profiles/create-profile.md).

**transactional\_emails\_enabled** `boolean`

Zda tento profil přijímá transakční (automatické) e-maily. Může být `null`.

**panels** `AppointmentPanel[]` *required*

Panely aktuálně připojené k tomuto termínu. U nově vytvořených termínů je pole prázdné — připoj
je přes [Přidat panely](https://docs.anivahealth.com/cs/api/appointments/add-panels.md). Detaily panelů (název, biomarkery) najdeš
přes [Vypsat panely](https://docs.anivahealth.com/cs/api/panels/list-panels.md).

**Pole připojeného panelu**

**panel\_id** `string`

UUID panelu — dohledej přes [Vypsat panely](https://docs.anivahealth.com/cs/api/panels/list-panels.md).

**added\_at** `string`

Časové razítko ISO 8601 prvního připojení panelu k tomuto termínu.

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

Samostatné biomarkery připojené k tomuto termínu mimo jakýkoli panel. U nově vytvořených termínů
je pole prázdné — připoj je přes [Přidat jednotlivé biomarkery](https://docs.anivahealth.com/cs/api/appointments/add-individual-biomarkers.md).
Údaje pro zobrazení najdeš spárováním každého `biomarker_id` s [Vypsat biomarkery](https://docs.anivahealth.com/cs/api/biomarkers/list-biomarkers.md).

**Pole jednotlivého biomarkeru**

**biomarker\_id** `integer`

Identifikátor biomarkeru — dohledej přes
[Vypsat biomarkery](https://docs.anivahealth.com/cs/api/biomarkers/list-biomarkers.md).

**added\_at** `string`

Časové razítko ISO 8601 prvního připojení biomarkeru k tomuto termínu.

**shipments** `AppointmentShipmentLink[]` *required*

Zásilky propojené s tímto termínem, od nejstaršího propojení. U nově vytvořených termínů je pole
prázdné — propoj je přes [Vytvořit zásilku](https://docs.anivahealth.com/cs/api/shipments/create-shipment.md) (s `appointment_id`)
nebo [Připojit termíny k zásilce](https://docs.anivahealth.com/cs/api/shipments/attach-appointments-to-shipment.md).

**Pole odkazu na zásilku**

**id** `string`

Referenční identifikátor zásilky — dohledej přes
[Získat zásilku](https://docs.anivahealth.com/cs/api/shipments/get-shipment.md).

**added\_at** `string`

Časové razítko ISO 8601 prvního přiřazení zásilky k tomuto termínu.

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

Laboratorní kódy (čárové kódy zkumavek) zaznamenané pro tento termín v pořadí skenování. Prázdné,
dokud není potvrzen odběr krve. Žilní odběr krve má jeden kód vytištěný na každé zkumavce; kapilární
odběr má jeden kód pro každou mikrozkumavku. Výsledky a dokumenty v [Získat výsledky](https://docs.anivahealth.com/cs/api/appointments/get-results.md)
na tyto kódy odkazují přes `lab_code`.

## Minimální předstih

Termíny na odběrových místech provozovaných Anivou je nutné rezervovat alespoň **12 hodin** předem;
rezervace v kratším předstihu vrátí `400`. [Získat dostupnost](https://docs.anivahealth.com/cs/api/locations/get-availability.md) tyto
sloty už vynechává, takže vše, co z tohoto rozvrhu načteš, lze rezervovat.

Odběrová místa, která provozuješ ve vlastní režii, nemají minimální předstih — rezervace na stejný den i přímo na místě zůstávají beze změny.

## Duplicitní termíny

Profil může mít nejvýše jeden nezrušený termín pro dané odběrové místo a okamžik — jednomu člověku
nelze odebrat krev dvakrát na stejném místě ve stejnou chvíli, bez ohledu na počet odběrových křesel.

Vytvoření termínu pro slot, který už profil obsazuje, vrátí `409` s `appointment_id` už existujícího
termínu:

```json theme={null}
{
  "error": "This profile already has an appointment at this location and time. Reschedule or cancel the existing appointment instead of creating a second one.",
  "appointment_id": "03e916d2-7fd6-4414-8276-8532a105edc3"
}
```

Zpracuj to tak, že požadavek už byl proveden: načti termín přes
[Získat termín](https://docs.anivahealth.com/cs/api/appointments/get-appointment.md), přesuň ho přes
[Upravit termín](https://docs.anivahealth.com/cs/api/appointments/update-appointment.md) nebo ho zruš přes
[Zrušit termín](https://docs.anivahealth.com/cs/api/appointments/cancel-appointment.md). Vytvoření neopakuj — bude dál vracet `409`.

Opakované vytváření je díky tomu bezpečné: požadavek, který po vypršení časového limitu odešleš
znovu, nebo dvakrát odeslaný formulář nemůže vytvořit dva termíny pro stejného pacienta na stejný čas.

> [!NOTE]
>
> `appointment_id` se vrací pouze u duplicitní chyby `409`. Kapacitní `409` — slot je plný,
> protože ho obsadili *jiní* pacienti — vrací pouze `error` a správným řešením je vybrat jiný slot
> v [Získat dostupnost](https://docs.anivahealth.com/cs/api/locations/get-availability.md).

## Chybové odpovědi

| Stav | Popis |
| - | - |
| `400` | Chyba validace — např. `scheduled_at` je v minulosti, je za méně než 12 hodin v místě provozovaném společností Aniva, neodpovídá přesnému začátku slotu v rozvrhu místa nebo místo nemá skladem odběrové nádobky pro `draw_method`. |
| `403` | Zakázáno — tvůj API klíč nemá přístup k této operaci, nebo je nastaveno `results_ready_emails` bez oprávnění `results_view` pro pacienta. |
| `404` | Profil nebo místo nebylo nalezeno, nebo je místo neaktivní. |
| `409` | Tento profil už má v tomto místě a čase termín (obsahuje `appointment_id`), kapacita slotu je naplněna, místo má v toto datum zavřeno, klíč `Idempotency-Key` byl znovu použit s jiným tělem požadavku, nebo se původní požadavek ještě nedokončil. |
| `500` | Interní chyba serveru. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/appointments \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "scheduled_at": "2026-05-15T10:30:00Z"
  }'
```

```json 201 theme={null}
{
  "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
  "scheduled_at": "2026-05-15T10:30:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": null,
  "profile": {
    "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "handle": null,
    "first_name": "Maria",
    "last_name": "Schmidt",
    "email": "maria.schmidt@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1985-03-22",
    "height": 168,
    "weight": 65,
    "language": "de",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:14:32Z",
    "updated_at": null
  },
  "panels": [],
  "individual_biomarkers": [],
  "shipments": [],
  "lab_codes": []
}
```

```json 400 theme={null}
{
  "error": "Appointments must be booked at least 12 hours in advance. Please pick a later time."
}
```

```json 404 theme={null}
{
  "error": "Location not found or inactive"
}
```

```json 409 theme={null}
{
  "error": "This profile already has an appointment at this location and time. Reschedule or cancel the existing appointment instead of creating a second one.",
  "appointment_id": "03e916d2-7fd6-4414-8276-8532a105edc3"
}
```


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