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

# Időpont létrehozása

> Vérvételi időpont foglalása egy profilhoz egy vizsgálati helyszínen

Foglalj vérvételi időpontot egy páciensprofilnak egy adott vizsgálati helyszínen. Létrehozás után az időpont alapértelmezés szerint `confirmed` állapotba kerül (egyes helyszíneken ehelyett a `pending` lehet az alapértelmezett — ez helyszínenkénti beállítás). Használd a [Panelek hozzáadása](https://docs.anivahealth.com/hu/api/appointments/add-panels.md) végpontot vérvizsgálati panelek csatolásához [a vérvétel megerősítése](https://docs.anivahealth.com/hu/api/appointments/confirm-blood-draw.md) előtt.

> [!NOTE]
>
> Egy profilnak helyszínenként és idősávonként legfeljebb **egy** időpontja lehet. Ha olyan idősávra
> hozol létre időpontot, amelyet a profil már lefoglalt, második időpont helyett `409`-es válasz
> érkezik a meglévő `appointment_id` értékkel — így egy újrapróbált vagy véletlenül megismételt
> kérés soha nem duplikálja a foglalást. Lásd: [Duplikált időpontok](#duplikalt-idopontok).

Küldj opcionális `Idempotency-Key` fejlécet, hogy a létrehozás biztonságosan újrapróbálható legyen — ugyanazzal a kulccsal megismételve az eredeti válasz érkezik vissza egy újabb létrehozása helyett. Lásd: [Idempotencia](https://docs.anivahealth.com/hu/concepts/idempotency.md).

Az `appointments_schedule` jogosultsági kör szükséges hozzá.

## Kérés

### Törzsparaméterek

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

Annak a páciensprofilnak az UUID-je, amelyhez az időpontot létrehozod.

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

Annak a vizsgálati helyszínnek az UUID-je, ahol a vérvétel történik. A [Helyszínek
listázása](https://docs.anivahealth.com/hu/api/locations/list-locations.md) végponttal keresheted meg az elérhető
helyszínazonosítókat.

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

Az időpont dátuma és ideje ISO 8601 formátumban (pl. `2026-05-15T10:30:00Z` vagy
`2026-05-15T12:30:00+02:00`). **Tartalmaznia kell időzóna-jelölőt** — `Z`-t vagy explicit
eltolást, például `+02:00` értéket; az időzóna nélküli dátum-idő értékeket a rendszer elutasítja.
Jövőbeli időpontnak kell lennie.

A helyszín időbeosztása szerinti pontos idősávkezdetnek kell lennie, és az idősávban még kell lennie
szabad helynek — először nézd meg az [Elérhetőség lekérése](https://docs.anivahealth.com/hu/api/locations/get-availability.md)
végpontot. A beosztáson kívüli időpontok `400`-at adnak vissza; a betelt idősáv `409`-et ad vissza.
Az Aniva által üzemeltetett helyszíneken legalább 12 órával későbbinek kell lennie — lásd: [Minimális
előfoglalási idő](#minimalis-elofoglalasi-ido).

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

Legfeljebb 5 cím, amelyek mindegyike egy e-mailt kap, amint minden laboreredmény végleges. Az
e-mail az Aniva adminfelületének eredményoldalára mutat. A kulcsodnak `results_view` hozzáférésre
van szüksége a pácienshez, különben `403`-at kapsz. Hagyd el, ha a páciens csoportjához beállított
alapértelmezett címeket szeretnéd használni. Üres listával kikapcsolhatod az e-maileket. Lásd:
[Elkészült eredményekről szóló e-mailek](https://docs.anivahealth.com/hu/concepts/results.md#e-mailek-az-elkeszuelt-eredmenyekrol).

**draw\_method** `string`

A vérvétel módja: `capillary` vagy `venous`. Hagyd el, ha a helyszín `default_draw_method`
értékét szeretnéd használni. A módszernek szerepelnie kell a helyszín `draw_methods` listájában,
különben `400`-at kapsz.

## Válasz

Siker esetén az API `201 Created` választ ad vissza az új időponttal.

**id** `string` *required*

Az időpont egyedi azonosítója (UUID).

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

Annak a profilnak az UUID-ja, amelyhez ez az időpont tartozik.

**location\_id** `string`

Annak a vizsgálati helyszínnek az UUID-ja, ahol a vérvétel történik.

**scheduled\_at** `string`

A lefoglalt időpont dátuma és ideje UTC időpontként (ISO 8601 `Z` végződéssel, pl.
`2026-05-15T10:30:00Z`). Lehet `null`.

**status** `string` *required*

Az időpont aktuális állapota. A következő értékek egyike: `pending`, `confirmed`, `blood_drawn`
vagy `cancelled`. A laboreredmények elkészültségének részleteit az [Eredmények
lekérése](https://docs.anivahealth.com/hu/api/appointments/get-results.md) végpont adja meg; a szállítmány részletesebb
előrehaladását pedig a beágyazott `shipments` tömb egyes elemein (lásd alább) keresztül a
[Szállítmány lekérése](https://docs.anivahealth.com/hu/api/shipments/get-shipment.md) végponton követheted.

**cancellation\_reason** `string`

Az időpont lemondásakor rögzített szabadszöveges ok (pl. meg nem jelenés, késői lemondás,
„Sikertelen. Ismétlés szükséges”). `null`, kivéve, ha a `status` értéke `cancelled`.

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

Címek, amelyek mindegyike egy-egy e-mailt kap, amint minden laboreredmény végleges, kisbetűvel. Kikapcsolva üres. Lásd:
[Eredmények elkészültéről szóló e-mailek](https://docs.anivahealth.com/hu/concepts/results.md#e-mailek-az-elkeszuelt-eredmenyekrol).

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

A vérvétel módja: `capillary` (ujjbegyből vagy felkarból, mikrocsövekbe) vagy `venous` (vénából,
csövekbe). Az időpontnál beállított módszer, ennek hiányában a
[helyszín](https://docs.anivahealth.com/hu/concepts/locations.md) `default_draw_method` értéke. A vérvétel után a ténylegesen használt módszer.

**profile** `object` *required*

Az időponthoz tartozó páciensprofil.

**profile**

**id** `string`

Egyedi profilazonosító (UUID).

**handle** `string`

Profil-handle vagy felhasználónév. Lehet `null`.

**first\_name** `string`

Keresztnév. Lehet `null`.

**last\_name** `string`

Vezetéknév. Lehet `null`.

**email** `string`

E-mail-cím. Lehet `null`.

**phone** `string`

Telefonszám E.164 formátumban. Lehet `null`.

**sex** `integer`

Biológiai nem az ISO/IEC 5218 szabvány szerint. Lehet `null`.

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

Születési dátum `YYYY-MM-DD` formátumban. Lehet `null`.

**height** `number`

Magasság centiméterben. Lehet `null`.

**weight** `number`

Testsúly kilogrammban. Lehet `null`.

**language** `string`

Előnyben részesített nyelv: a [Profil létrehozása](https://docs.anivahealth.com/hu/api/profiles/create-profile.md) végpont 32 kódjának egyike.

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

Kap-e ez a profil tranzakciós (programozott) e-maileket. Lehet `null`.

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

Az időponthoz jelenleg csatolt panelek. Újonnan létrehozott időpontoknál üres — a [Panelek
hozzáadása](https://docs.anivahealth.com/hu/api/appointments/add-panels.md) végponttal csatolhatod őket. A panelek részleteit (név,
biomarkerek) a [Panelek listázása](https://docs.anivahealth.com/hu/api/panels/list-panels.md) végponton keresheted meg.

**Panelcsatolás mezői**

**panel\_id** `string`

A panel UUID-ja — vesd össze ezzel: [Panelek listázása](https://docs.anivahealth.com/hu/api/panels/list-panels.md).

**added\_at** `string`

ISO 8601 időbélyeg arról, amikor a panelt először csatolták ehhez az időponthoz.

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

Az időponthoz panelen kívül csatolt, külön választható biomarkerek. Újonnan létrehozott
időpontoknál üres — az [Egyedi biomarkerek
hozzáadása](https://docs.anivahealth.com/hu/api/appointments/add-individual-biomarkers.md) végponttal csatolhatod őket. A
megjelenítési adatokhoz vesd össze az egyes `biomarker_id` értékeket a [Biomarkerek
listázása](https://docs.anivahealth.com/hu/api/biomarkers/list-biomarkers.md) végponttal.

**Egyedi biomarker mezői**

**biomarker\_id** `integer`

Biomarker-azonosító — vesd össze ezzel:
[Biomarkerek listázása](https://docs.anivahealth.com/hu/api/biomarkers/list-biomarkers.md).

**added\_at** `string`

ISO 8601 időbélyeg arról, amikor a biomarkert először csatolták ehhez az időponthoz.

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

Az időponthoz kapcsolt szállítmányok, a legrégebben kapcsolttal kezdve. Újonnan létrehozott
időpontoknál üres — a [Szállítmány létrehozása](https://docs.anivahealth.com/hu/api/shipments/create-shipment.md) (az
`appointment_id` megadásával) vagy az [Időpontok csatolása
szállítmányhoz](https://docs.anivahealth.com/hu/api/shipments/attach-appointments-to-shipment.md) végponttal kapcsolhatod össze őket.

**Szállítmány-hivatkozás mezői**

**id** `string`

Szállítmány hivatkozási azonosítója — vesd össze ezzel:
[Szállítmány lekérése](https://docs.anivahealth.com/hu/api/shipments/get-shipment.md).

**added\_at** `string`

ISO 8601 időbélyeg arról, amikor a szállítmányt először kapcsolták ehhez az időponthoz.

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

Ehhez az időponthoz rögzített laborkódok (csővonalkódok), beolvasási sorrendben. A vérvétel
megerősítéséig üres. A vénás vérvétel egyetlen kódot használ, amely minden csőre rá van nyomtatva; a kapilláris vérvétel mikrocsövenként egy
kódot használ. Az [Eredmények lekérése](https://docs.anivahealth.com/hu/api/appointments/get-results.md) eredményei és dokumentumai a `lab_code` segítségével hivatkoznak
ezekre a kódokra.

## Minimális előfoglalási idő

Az Aniva által üzemeltetett helyszíneken az időpontokat legalább **12 órával** előre kell foglalni;
ezen az időablakon belüli foglalás `400`-at ad vissza. Az [Elérhetőség
lekérése](https://docs.anivahealth.com/hu/api/locations/get-availability.md) végpont már eleve visszatartja ezeket az idősávokat, így
minden foglalható, ami abban a beosztásban megjelenik.

A saját üzemeltetésű helyszíneiden nincs minimális előfoglalási idő — az aznapi és a helyszíni foglalás változatlan marad.

## Duplikált időpontok

Egy profilnak helyszínenként és időpillanatonként legfeljebb egy nem lemondott időpontja lehet —
egy személynél nem lehet kétszer vérvételt végezni ugyanazon a helyen és ugyanabban a pillanatban,
bármennyi szék is van a helyszínen.

Ha olyan idősávra hozol létre időpontot, amelyet a profil már elfoglalt, `409`-es válasz érkezik egy
`appointment_id` mezővel, amely a már meglévő időpontot azonosítja:

```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"
}
```

Kezeld úgy, mintha a kérés már teljesült volna: kérd le az időpontot az [Időpont
lekérése](https://docs.anivahealth.com/hu/api/appointments/get-appointment.md) végponttal, helyezd át az [Időpont
módosítása](https://docs.anivahealth.com/hu/api/appointments/update-appointment.md) végponttal, vagy mondd le az [Időpont
lemondása](https://docs.anivahealth.com/hu/api/appointments/cancel-appointment.md) végponttal. Ne próbáld újra a létrehozást —
továbbra is `409`-et fog visszaadni.

Így az ismételt létrehozások biztonságosak: egy időtúllépés után újraküldött kérés vagy egy kétszer
beküldött űrlap nem hozhat létre két időpontot ugyanannak a páciensnek ugyanabban az időben.

> [!NOTE]
>
> Az `appointment_id` csak a duplikáció miatti `409`-es válaszban szerepel. A kapacitás miatti
> `409` — amikor az idősáv azért telt be, mert *más* páciensek foglalták el — csak `error` mezőt
> ad vissza, és ilyenkor az a helyes megoldás, ha egy másik idősávot választasz az [Elérhetőség
> lekérése](https://docs.anivahealth.com/hu/api/locations/get-availability.md) végpontból.

## Hibaválaszok

| Státusz | Leírás |
| - | - |
| `400` | Validációs hiba — például a `scheduled_at` a múltban van, 12 órán belüli egy Aniva által üzemeltetett helyszínen, nem pontosan egy idősáv kezdetére esik a helyszín beosztásában, vagy a helyszín nem tart készleten tárolókat a `draw_method` számára. |
| `403` | Tiltott — az API-kulcsodnak nincs hozzáférése ehhez a művelethez, vagy a `results_ready_emails` be van állítva a páciensre vonatkozó `results_view` hozzáférés nélkül. |
| `404` | A profil vagy a helyszín nem található, vagy a helyszín inaktív. |
| `409` | Ennek a profilnak már van időpontja ezen a helyszínen és ebben az időben (tartalmazza az `appointment_id` értéket), az idősáv betelt, a helyszín zárva tart azon a napon, vagy az `Idempotency-Key` más törzzsel lett újrahasználva, illetve az eredeti kérése még nem fejeződött be. |
| `500` | Belső szerverhiba. |

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