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

# Creează o programare

> Programează o recoltare de sânge pentru un profil la o locație de testare

Creează o programare de recoltare de sânge pentru profilul unui pacient la o anumită locație de testare. Odată creată, programarea intră implicit în statusul `confirmed` (unele locații pot folosi implicit `pending` — aceasta este o setare specifică fiecărei locații). Folosește [Adaugă paneluri](https://docs.anivahealth.com/ro/api/appointments/add-panels.md) pentru a atașa paneluri de analize de sânge înainte de [confirmarea recoltării de sânge](https://docs.anivahealth.com/ro/api/appointments/confirm-blood-draw.md).

> [!NOTE]
>
> Un profil poate avea cel mult **o** programare per locație și oră. Crearea unei programări pentru
> un interval pe care profilul îl ocupă deja returnează `409` cu `appointment_id` existent în loc de o
> a doua programare — astfel, o cerere reîncercată sau repetată din greșeală nu poate duplica niciodată o programare.
> Vezi [Programări duplicate](#programari-duplicate).

Trimite un antet opțional `Idempotency-Key` pentru ca această creare să poată fi reîncercată în siguranță — repetarea aceleiași chei returnează răspunsul inițial în loc să creeze încă una. Vezi [Idempotență](https://docs.anivahealth.com/ro/concepts/idempotency.md).

Necesită scope-ul `appointments_schedule`.

## Cerere

### Parametri de corp

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

UUID-ul profilului pacientului pentru care creezi programarea.

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

UUID-ul locației de testare unde va avea loc recoltarea de sânge. Folosește [Listează
locațiile](https://docs.anivahealth.com/ro/api/locations/list-locations.md) pentru a găsi ID-urile locațiilor disponibile.

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

Data și ora programării în format ISO 8601 (de ex., `2026-05-15T10:30:00Z` sau
`2026-05-15T12:30:00+02:00`). **Trebuie să includă un indicator de fus orar** — fie `Z`, fie un decalaj
explicit precum `+02:00`; valorile fără fus orar sunt respinse. Trebuie să fie în viitor.

Trebuie să fie ora exactă de început a unui interval din grila locației, iar intervalul trebuie să mai aibă capacitate — consultă
mai întâi [Obține disponibilitatea](https://docs.anivahealth.com/ro/api/locations/get-availability.md). Orele din afara grilei returnează `400`; un interval
ocupat complet returnează `409`. La locațiile operate de Aniva trebuie să fie și cu cel puțin 12 ore în avans — vezi
[Preaviz minim](#preaviz-minim).

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

Până la 5 adrese care primesc fiecare câte un email odată ce toate rezultatele de laborator sunt finale. Emailul conține un link către
pagina de rezultate din panoul de administrare Aniva. Cheia ta are nevoie de acces `results_view` pentru pacient, altfel returnează
`403`. Omite câmpul pentru a folosi adresele implicite setate pentru grupul pacientului. O listă goală dezactivează
emailurile. Vezi [Emailuri când rezultatele sunt gata](https://docs.anivahealth.com/ro/concepts/results.md#e-mailuri-cand-rezultatele-sunt-gata).

**draw\_method** `string`

Cum se face recoltarea de sânge: `capillary` sau `venous`. Omite câmpul pentru a folosi `default_draw_method` al
locației. Locația trebuie să includă metoda în `draw_methods`, altfel returnează `400`.

## Răspuns

În caz de succes, API-ul returnează `201 Created` împreună cu noua programare.

**id** `string` *required*

Identificatorul unic al programării (UUID).

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

UUID-ul profilului căruia îi aparține această programare.

**location\_id** `string`

UUID-ul locației de testare unde are loc recoltarea de sânge.

**scheduled\_at** `string`

Data și ora programării în format UTC (ISO 8601 cu sufixul `Z`, de ex.
`2026-05-15T10:30:00Z`). Poate fi `null`.

**status** `string` *required*

Statusul curent al programării. Una dintre valorile `pending`, `confirmed`, `blood_drawn` sau `cancelled`.
Detaliile privind finalizarea rezultatelor de laborator se obțin din [Obține rezultatele](https://docs.anivahealth.com/ro/api/appointments/get-results.md);
evoluția detaliată a expedierii se obține din fiecare intrare din lista inline `shipments` (vezi mai jos),
urmată de [Obține expedierea](https://docs.anivahealth.com/ro/api/shipments/get-shipment.md).

**cancellation\_reason** `string`

Motivul în text liber înregistrat la anularea programării (de ex. neprezentare, anulare tardivă,
„Eșuat. Necesită repetare”). Este `null` dacă `status` nu este `cancelled`.

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

Adresele care primesc fiecare câte un e-mail când toate rezultatele de laborator sunt finale, cu
litere mici. Gol când este dezactivat. Vezi
[E-mailuri pentru rezultate gata](https://docs.anivahealth.com/ro/concepts/results.md#e-mailuri-cand-rezultatele-sunt-gata).

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

Cum se face recoltarea de sânge: `capillary` (din vârful degetului sau partea superioară a brațului, în
microtainere) sau `venous` (din venă, în eprubete). Este metoda setată pe programare sau
`default_draw_method` al [locației](https://docs.anivahealth.com/ro/concepts/locations.md) acesteia. După recoltarea de sânge, este
metoda care a fost folosită.

**profile** `object` *required*

Profilul pacientului asociat cu această programare.

**profil**

**id** `string`

Identificator unic al profilului (UUID).

**handle** `string`

Handle sau nume de utilizator al profilului. Poate fi `null`.

**first\_name** `string`

Prenume. Poate fi `null`.

**last\_name** `string`

Nume de familie. Poate fi `null`.

**email** `string`

Adresă de email. Poate fi `null`.

**phone** `string`

Număr de telefon în format E.164. Poate fi `null`.

**sex** `integer`

Sex biologic conform ISO/IEC 5218. Poate fi `null`.

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

Data nașterii în format `YYYY-MM-DD`. Poate fi `null`.

**height** `number`

Înălțime în centimetri. Poate fi `null`.

**weight** `number`

Greutate în kilograme. Poate fi `null`.

**language** `string`

Limbă preferată: unul dintre cele 32 de coduri din [Creează profil](https://docs.anivahealth.com/ro/api/profiles/create-profile.md).

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

Indică dacă acest profil primește emailuri tranzacționale (programatice). Poate fi `null`.

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

Panelurile atașate în prezent acestei programări. Listă goală pentru programările nou create — atașează-le prin
[Adaugă paneluri](https://docs.anivahealth.com/ro/api/appointments/add-panels.md). Consultă detaliile panelurilor (nume, biomarkeri) prin
[Listează panelurile](https://docs.anivahealth.com/ro/api/panels/list-panels.md).

**Câmpurile panelului asociat**

**panel\_id** `string`

UUID-ul panelului — corelează cu [Listează paneluri](https://docs.anivahealth.com/ro/api/panels/list-panels.md).

**added\_at** `string`

Timestamp ISO 8601 al primei asocieri a panelului cu această programare.

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

Biomarkeri individuali atașați acestei programări în afara unui panel. Listă goală pentru programările nou
create — atașează-i prin [Adaugă biomarkeri individuali](https://docs.anivahealth.com/ro/api/appointments/add-individual-biomarkers.md).
Corelează fiecare `biomarker_id` cu [Listează biomarkerii](https://docs.anivahealth.com/ro/api/biomarkers/list-biomarkers.md)
pentru datele de afișare.

**Câmpurile biomarkerului individual**

**biomarker\_id** `integer`

Identificatorul biomarkerului — corelează cu
[Listează biomarkeri](https://docs.anivahealth.com/ro/api/biomarkers/list-biomarkers.md).

**added\_at** `string`

Timestamp ISO 8601 al primei asocieri a biomarkerului cu această programare.

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

Expedierile asociate acestei programări, începând cu cea mai veche asociere. Listă goală pentru programările nou create —
asociază-le prin [Creează expediere](https://docs.anivahealth.com/ro/api/shipments/create-shipment.md) (cu `appointment_id`) sau
[Atașează programări la expediere](https://docs.anivahealth.com/ro/api/shipments/attach-appointments-to-shipment.md).

**Câmpurile expedierii asociate**

**id** `string`

Identificatorul de referință al expedierii — corelează cu
[Obține expediere](https://docs.anivahealth.com/ro/api/shipments/get-shipment.md).

**added\_at** `string`

Timestamp ISO 8601 al primei asocieri a expedierii cu această programare.

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

Codurile de laborator (codurile de bare de pe eprubete) înregistrate pentru această programare, în
ordinea scanării. Gol până la confirmarea recoltării de sânge. O recoltare venoasă are un singur
cod tipărit pe fiecare eprubetă; o recoltare capilară are câte un cod per microtainer. Rezultatele
și documentele din [Obține rezultate](https://docs.anivahealth.com/ro/api/appointments/get-results.md) fac referire la aceste coduri
prin `lab_code`.

## Preaviz minim

Programările la locațiile operate de Aniva trebuie făcute cu cel puțin **12 ore** în avans; programarea în
acea fereastră returnează `400`. [Obține disponibilitatea](https://docs.anivahealth.com/ro/api/locations/get-availability.md) exclude deja
acele intervale, așa că tot ce citești din acea grilă poate fi programat.

Locațiile pe care le operezi tu nu au preaviz minim — programările în aceeași zi și cele pe loc rămân neschimbate.

## Programări duplicate

Un profil poate avea cel mult o programare neanulată per locație și moment — o persoană nu poate
face două recoltări de sânge în același loc și în același moment, indiferent câte scaune are locația.

Crearea unei programări pentru un interval pe care profilul îl ocupă deja returnează `409` cu un
`appointment_id` care indică programarea deja existentă:

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

Tratează situația ca și cum cererea ar fi fost deja aplicată: preia programarea cu
[Obține programarea](https://docs.anivahealth.com/ro/api/appointments/get-appointment.md), mut-o cu
[Actualizează programarea](https://docs.anivahealth.com/ro/api/appointments/update-appointment.md) sau renunță la ea cu
[Anulează programarea](https://docs.anivahealth.com/ro/api/appointments/cancel-appointment.md). Nu reîncerca crearea — va continua
să returneze `409`.

Astfel, creările repetate sunt sigure: o cerere pe care o retrimiți după un timeout sau un formular trimis de două ori
nu poate genera două programări pentru același pacient la aceeași oră.

> [!NOTE]
>
> `appointment_id` este prezent doar în cazul `409` pentru duplicat. Codul `409` de capacitate — intervalul este plin
> deoarece *alți* pacienți îl ocupă — returnează doar `error`, iar soluția potrivită în acel caz este să alegi
> un alt interval din [Obține disponibilitatea](https://docs.anivahealth.com/ro/api/locations/get-availability.md).

## Răspunsuri de eroare

| Status | Descriere |
| - | - |
| `400` | Eroare de validare — de ex., `scheduled_at` este în trecut, este peste mai puțin de 12 ore la o locație operată de Aniva sau nu este începutul exact al unui interval din grila locației, ori locația nu are în stoc recipiente pentru `draw_method`. |
| `403` | Interzis — cheia ta API nu are acces la această operațiune sau `results_ready_emails` este setat fără acces `results_view` la pacient. |
| `404` | Nu s-a găsit profilul sau locația ori locația este inactivă. |
| `409` | Acest profil are deja o programare la această locație și oră (include `appointment_id`), intervalul este complet ocupat, locația este închisă la acea dată sau `Idempotency-Key` a fost reutilizat cu un alt corp ori cererea originală nu s-a finalizat. |
| `500` | Eroare internă de server. |

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