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

# Programări

> Cum funcționează programările pentru recoltare de sânge în API-ul de analize de laborator Aniva: rezervare, paneluri, biomarkeri, modificări de status și anulare.

O programare este o recoltare de sânge planificată pentru un profil de pacient la o locație fizică de testare, efectuată de un cadru medical. Kiturile trimise prin poștă unui pacient nu sunt programări — vezi [Comenzi de kituri de testare la domiciliu](https://docs.anivahealth.com/ro/concepts/home-kit-orders.md).

## Câmpuri

**id** `string` *required*

UUID generat automat de Aniva. Folosește-l pentru a adăuga paneluri, a confirma recoltarea și a prelua rezultatele.

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

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

**location\_id** `string`

UUID-ul locației de testare unde va avea loc recoltarea. Kiturile de testare la domiciliu nu sunt programări — vezi
[Comenzi de kituri de testare la domiciliu](https://docs.anivahealth.com/ro/concepts/home-kit-orders.md).

**scheduled\_at** `string`

Data și ora programate pentru recoltarea de sânge, în format ISO 8601. Se returnează întotdeauna ca moment UTC cu sufix `Z`
(de ex. `2026-04-15T08:30:00Z`). La creare / actualizare, valoarea **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, iar în locațiile operate de Aniva cu cel puțin 12 ore în avans ([preaviz
minim](https://docs.anivahealth.com/ro/api/appointments/create-appointment.md#preaviz-minim)).

**status** `string` *required*

Statusul curent din ciclul de viață. Una dintre valorile `pending`, `confirmed`, `blood_drawn` sau `cancelled`. Vezi
[Ciclul de viață](#ciclul-de-viata) mai jos. Detaliile privind finalizarea rezultatelor de laborator (`in_progress` față de `completed`) se
obțin din [Obținere rezultate](https://docs.anivahealth.com/ro/api/appointments/get-results.md); evoluția detaliată a expedierii (în
tranzit, livrată etc.) se obține urmărind fiecare intrare din array-ul inline `shipments` în
[Obținere expediere](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ă.

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

Timestamp ISO 8601 al creării programării.

**updated\_at** `string`

Marcajul temporal ISO 8601 al celei mai recente actualizări. Null dacă programarea nu a fost actualizată niciodată.

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

Coduri de laborator (coduri de bare ale eprubetelor) înregistrate la [Confirmare recoltare de sânge](https://docs.anivahealth.com/ro/api/appointments/confirm-blood-draw.md),
în ordinea scanării. Gol până la confirmarea recoltării. O recoltare venoasă are un singur cod tipărit pe fiecare
eprubetă; o recoltare capilară are un cod pentru fiecare microtub. Rezultatele și documentele fac referire la acestea prin
`lab_code`.

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

Panelurile asociate acestei programări, ca intrări `{ panel_id, added_at }`. Vezi
[Adăugarea panelurilor](#adaugarea-panelurilor).

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

Biomarkerii aleși individual asociați acestei programări, ca intrări `{ biomarker_id, added_at }`. Vezi
[Biomarkeri individuali](#biomarkeri-individuali).

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

Expedierile asociate acestei programări, ca intrări `{ id, added_at }`, începând cu cea mai veche asociere. Vezi
[Asocierea expedierilor](#asocierea-expedierilor).

**profile** `object` *required*

Obiectul complet de profil al pacientului, inclus în fiecare răspuns de programare. Câmpurile de mai jos
reprezintă un subset. [Obținere programare](https://docs.anivahealth.com/ro/api/appointments/get-appointment.md) le enumeră pe toate.

**proprietăți**

**id** `string`

UUID-ul profilului asociat.

**first\_name** `string`

Prenumele pacientului.

**last\_name** `string`

Numele de familie al pacientului.

**email** `string`

Adresa de e-mail a pacientului.

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

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

**sex** `integer`

Sexul biologic conform ISO/IEC 5218.

## Ciclul de viață

Programările expun patru stări ale ciclului de viață:

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

| Status | Semnificație |
| - | - |
| `pending` | Programarea este planificată și așteaptă confirmarea. Poate fi [actualizată](https://docs.anivahealth.com/ro/api/appointments/update-appointment.md) sau [anulată](https://docs.anivahealth.com/ro/api/appointments/cancel-appointment.md). |
| `confirmed` | Programarea a fost confirmată (de ex. de către cabinet), dar sângele nu a fost încă recoltat. Încă poate fi actualizată sau anulată. |
| `blood_drawn` | Codurile de laborator au fost trimise prin [Confirmare recoltare de sânge](https://docs.anivahealth.com/ro/api/appointments/confirm-blood-draw.md), iar fluxul de comandă către laborator a fost declanșat. Panelurile sunt blocate, iar programarea nu mai poate fi reprogramată sau anulată. |
| `cancelled` | Programarea a fost anulată. Stare finală — fără alte tranziții. |

> [!NOTE]
>
> Statusul programării este intenționat general — evoluția mai detaliată este expusă
> prin endpoint-uri dedicate:
>
> * **Finalizarea rezultatelor de laborator** →
>   [Obținere rezultate](https://docs.anivahealth.com/ro/api/appointments/get-results.md) — câmpul `status` de nivel superior este `in_progress` sau
>   `completed`.
> * **Evoluția expedierii** (în tranzit, livrată etc.) → urmărește fiecare intrare din array-ul inline
>   `shipments` al programării în [Obținere expediere](https://docs.anivahealth.com/ro/api/shipments/get-shipment.md) — fiecare
>   expediere are propriul `status` și un jurnal de evenimente `status_updates`.
>
> Fiecare schimbare de status trimite un [webhook](https://docs.anivahealth.com/ro/concepts/webhooks.md) `appointment.*`, de exemplu
> `appointment.confirmed`. O oră sau o locație nouă trimite `appointment.rescheduled`.

> [!WARNING]
>
> Confirmarea unei programări (trecerea ei în `blood_drawn`) este **ireversibilă**. După ce trimiți
> codul sau codurile de laborator, fluxul de comandă către laborator este declanșat și nu poate fi anulat. Actualizările și anulările
> sunt permise doar cât timp programarea are statusul `pending` sau `confirmed`.

## Listarea programărilor

Preia toate programările accesibile cheii tale API:

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

Poți transmite opțional `?profile_id={uuid}` pentru a filtra după un anumit profil. Fără acest parametru, se aplică un interval de timp implicit (ultimele 2 luni până la luna următoare).

## Actualizarea unei programări

Înainte de confirmarea recoltării de sânge, poți reprograma sau schimba locația de testare:

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

Transmite orice combinație de `scheduled_at`, `location_id`, `draw_method` și `results_ready_emails` pentru actualizare. Include doar câmpurile pe care vrei să le modifici.

## Metoda de recoltare

Fiecare programare are un `draw_method`: `capillary` (din vârful degetului sau din partea superioară a brațului, în microtuburi) sau
`venous` (din venă, în eprubete). Se aplică doar recoltării de sânge. Probele de urină, cele recoltate cu tampon și alte
probe care nu sunt de sânge se colectează la fel, indiferent de metodă.

Implicit, acesta este `default_draw_method` al locației. Setează `draw_method` la creare sau actualizare pentru
a folosi o altă metodă sau setează-l la `null` pentru a reveni la valoarea implicită a locației. Locația trebuie să includă
metoda în `draw_methods`, iar testele programate trebuie să fie posibile cu aceasta, altfel cererea
returnează `400`. Nu îl poți modifica după recoltarea de sânge. După recoltare, `draw_method` reprezintă
metoda care a fost folosită.

## O singură programare per profil, locație și oră

Un profil poate avea cel mult o programare neanulată pentru fiecare pereche `(location_id, scheduled_at)` — unei
persoane nu i se poate recolta sânge de două ori în același loc și în același moment, indiferent câte programări paralele
acceptă locația.

Atât [Creare programare](https://docs.anivahealth.com/ro/api/appointments/create-appointment.md), cât și
[Actualizare programare](https://docs.anivahealth.com/ro/api/appointments/update-appointment.md) impun această regulă, returnând `409` cu un
`appointment_id` care indică programarea deja existentă. Tratează acel răspuns ca pe o programare deja
făcută, nu ca pe o eroare de reîncercat: preia, reprogramează sau anulează programarea indicată.

Efectul practic este că cererile repetate de creare sunt sigure. O creare pe care o retrimiți după un timeout de rețea,
sau una pe care un utilizator o declanșează de două ori, duce la o singură programare în loc de două — ceea ce înseamnă și că nu
trebuie niciodată să reconciliezi ulterior programări duplicate pentru același pacient.

> [!NOTE]
>
> Actualizările sunt permise doar înainte de recoltarea de sânge — adică cât timp programarea are statusul `pending` sau
> `confirmed`. După ce programarea trece în `blood_drawn` sau a fost `cancelled`, nu mai poate
> fi modificată. Singura excepție este `results_ready_emails`: îl poți modifica separat și după
> recoltarea de sânge.

## Anularea unei programări

Anulează o programare care nu mai este necesară:

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

Aceasta setează statusul programării la `cancelled`. Programarea anulată este returnată în răspuns.

Opțional, trimite un `cancellation_reason` (până la 500 de caractere) în corpul cererii pentru a înregistra motivul. Acesta este
stocat în programare și returnat ca `cancellation_reason` la citirile ulterioare.

> [!NOTE]
>
> Anularea este permisă doar înainte de recoltarea de sânge — adică cât timp programarea are statusul `pending` sau
> `confirmed`. Programările care au trecut deja în `blood_drawn` nu pot fi anulate.

## Adăugarea panelurilor

Înainte de a confirma recoltarea de sânge, adaugă panelurile de analize de sânge pe care vrei să le efectuezi apelând:

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

Trimite un array cu UUID-urile panelurilor în câmpul `panel_ids`. ID-urile panelurilor sunt furnizate de Aniva pentru contul tău de partener.

> [!NOTE]
>
> Panelurile trebuie adăugate înainte de recoltarea de sânge — adică cât timp programarea are statusul `pending` sau
> `confirmed`. Nu poți adăuga sau modifica paneluri după ce programarea a trecut în
> `blood_drawn`.

## Eliminarea panelurilor

Dacă trebuie să elimini paneluri înainte de recoltarea de sânge, apelează:

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

Trimite un array cu UUID-urile panelurilor în câmpul `panel_ids`. Eliminarea este idempotentă: un panel care nu este atașat este ignorat.

> [!NOTE]
>
> La fel ca adăugarea panelurilor, eliminarea este permisă doar înainte de recoltarea de sânge — adică cât timp programarea are
> statusul `pending` sau `confirmed`. Panelurile nu mai pot fi eliminate după ce programarea a trecut în
> `blood_drawn`.

## Biomarkeri individuali

Poți atașa biomarkeri individuali la o programare ca teste à la carte, în afara oricărui panel predefinit. Acest lucru este util când un practician dorește o selecție personalizată în locul unui pachet prestabilit. Biomarkerii atașați apar în răspunsul programării ca un array `individual_biomarkers` (la același nivel cu `panels`). Deciziile de rutare sunt luate ulterior de pipeline-ul de logistică a comenzilor, pe baza mapărilor per laborator ale fiecărui biomarker.

Adaugă biomarkeri (idempotent — biomarkerii deja atașați sunt păstrați):

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

Elimină biomarkeri (idempotent — biomarkerii care nu sunt atașați sunt ignorați):

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

Ambele endpoint-uri primesc un array `biomarker_ids` și validează setul rezultat conform regulilor de închidere ale fiecărui laborator — o comandă care nu poate fi plasată corect (de ex. un raport CRP/HDL fără CRP și HDL) returnează `400` cu biomarkerii pe care ar trebui să îi adaugi și nu salvează nimic. Folosește [Listează biomarkerii](https://docs.anivahealth.com/ro/api/biomarkers/list-biomarkers.md) pentru a afla ID-urile biomarkerilor.

> [!NOTE]
>
> La fel ca modificările de paneluri, biomarkerii individuali pot fi adăugați sau eliminați doar înainte de recoltarea de sânge
> — adică cât timp programarea are statusul `pending` sau `confirmed`. Odată ce programarea trece în
> `blood_drawn`, snapshot-ul personalizat este blocat.

## Previzualizarea necesarului de recipiente

După adăugarea panelurilor sau a biomarkerilor individuali, previzualizează recipientele fizice de recoltare care vor fi necesare pentru prelevarea probelor:

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

Array-ul `containers` din răspuns include tipul, numele, culoarea capacului, volumul, codul de articol al producătorului și numărul de bucăți pentru fiecare recipient necesar. Acest lucru îi ajută pe practicieni să pregătească materialele corecte înainte de recoltarea de sânge. Răspunsul conține și un obiect `pricing` — nota de plată pentru întregul coș al programării (pozițiile aplicate, panelurile atașate și câte un rând pentru fiecare biomarker livrat, cu tariful din grila ta alături de prețul de retail; vezi [Prețuri](https://docs.anivahealth.com/ro/concepts/pricing.md)), populat când programarea are analize atașate și cheia ta are scope-ul `prices_view`, altfel `null`. În mod intenționat, `routing` nu este expus niciodată și este întotdeauna `null`.

> [!NOTE]
>
> Previzualizarea reflectă panelurile și biomarkerii atașați în prezent. Dacă adaugi sau elimini paneluri
> după previzualizare, apelează din nou endpoint-ul de previzualizare pentru a obține necesarul actualizat de recipiente.

## Confirmarea recoltării de sânge

După recoltarea de sânge, trimite codurile de laborator (codurile de bare ale eprubetelor) pentru a declanșa pipeline-ul de comenzi de laborator:

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

Trimite `lab_code` când același cod este tipărit pe fiecare eprubetă (recoltare venoasă) sau `lab_codes` cu câte o intrare
pentru fiecare cod — fiecare cu `panel_ids` pe care le acoperă — când fiecare panel este recoltat în propriile eprubete, cu
propriul cod (recoltare capilară). Fiecare panel devine apoi propria cerere de laborator sub codul său. Codurile
sunt returnate ca `lab_codes` în programare.

La o recoltare capilară, recoltarea de sânge este repartizată în microtainere. Panelurile intră primele, în ordinea rezervării. Biomarkerii
individuali ocupă apoi spațiul liber din microtainerele panelurilor. Când au nevoie de mai mult spațiu, deschid
microtainere noi. Îi distribuim uniform. Fiecare microtainer conține cel mult 150 µl de biomarkeri
individuali. Apelurile care modifică paneluri sau biomarkeri răspund cu `400` când setul rezultat încalcă
această regulă.

Aceasta trece statusul programării în `blood_drawn` și inițiază procesarea în laborator. Această acțiune este ireversibilă.

## Preluarea expedierii

> [!WARNING]
>
> `POST /api/v1/appointments/pickup` a fost **eliminat**, împreună cu statusul de programare
> `shipment_picked_up`. Acum răspunde cu `405 Method Not Allowed`, deoarece calea ajunge în ruta
> pentru programare după ID. În ultima sa fază, endpoint-ul a funcționat ca un no-op care accepta apelul și
> nu făcea nimic, deci eliminarea lui nu modifică niciun comportament pe care te bazai.

Pentru a urmări evoluția după recoltarea de sânge, accesează fiecare intrare din array-ul inline `shipments`
al programării prin [Obține expedierea](https://docs.anivahealth.com/ro/api/shipments/get-shipment.md) — fiecare expediere are propriul `status`
și un istoric `status_updates`.

## Asocierea expedierilor

O programare poate fi asociată cu una sau mai multe expedieri (și invers — relația este
many-to-many). Setul curent de asocieri apare inline pe ambele părți:

* în programare, ca un array `shipments` cu intrări `{ id, added_at }`;
* în expediere, ca un array `appointments` cu intrări `{ id, added_at }`.

Ambele array-uri sunt ordonate de la cea mai veche asociere. Fiecare `id` face trimitere la endpoint-ul canonic de detalii
([Obține expedierea](https://docs.anivahealth.com/ro/api/shipments/get-shipment.md) /
[Obține programarea](https://docs.anivahealth.com/ro/api/appointments/get-appointment.md)) pentru payload-ul complet.

Expedierile sunt asociate la creare prin câmpul `appointment_id` din
[Creează expediere](https://docs.anivahealth.com/ro/api/shipments/create-shipment.md). După creare, gestionează asocierile din expediere
cu [Atașează programări la expediere](https://docs.anivahealth.com/ro/api/shipments/attach-appointments-to-shipment.md) și
[Detașează programări de la expediere](https://docs.anivahealth.com/ro/api/shipments/detach-appointments-from-shipment.md); fiecare returnează
lista actualizată de programări pentru expedierea respectivă. Pentru a citi integral coletele unei programări,
folosește [Listează expedierile](https://docs.anivahealth.com/ro/api/shipments/list-shipments.md) cu `?appointment_id=`.

Regula de modificare este: asocierile pot fi create sau eliminate când FIE

* programarea a trecut de recoltarea de sânge (`blood_drawn`), fie
* expedierea a fost creată acum mai puțin de 24 de ore.

În afara acestui interval, asocierea este blocată pentru ca înregistrările istorice să rămână stabile.

## Preluarea rezultatelor de laborator

După ce laboratorul a procesat probele de sânge, preia rezultatele clinice și genetice:

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

Răspunsul include testele planificate (cu status `planned`) alături de rezultatele primite, astfel încât poți
urmări ce este încă în așteptare. Câmpul `status` de la nivel superior este `in_progress` până când fiecare trimitere
se închide, apoi `completed` (sau `fault` când niciuna nu a raportat) — folosește-l pentru a determina dacă
analizele de laborator ale programării sunt gata. Un [webhook](https://docs.anivahealth.com/ro/concepts/webhooks.md) `appointment.results.completed`
îți spune când se întâmplă acest lucru, deci nu trebuie să interoghezi periodic. Lista
`submissions` detaliază acest lucru pe fiecare solicitare de laborator, fiecare cu propriul `lab_code`. Fiecare
rezultat și document primit include `lab_code` sub care a fost înregistrat. Rapoartele de laborator în format PDF sunt
referențiate în lista `documents` — folosește `GET /api/v1/documents/{id}` pentru a le descărca.

## Exemplu de programare

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