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

# Expedieri

> Cum funcționează logistica în API-ul Aniva: expedieri de probe către laborator și colete cu kituri de testare la domiciliu, cu urmărire și status.

O expediere este un singur colet fizic: o ridicare prin curier care transportă probe de sânge de la o locație de testare la un laborator, kitul aflat pe drum spre un pacient cu kit de testare la domiciliu sau proba pe care acel pacient o trimite înapoi prin poștă. API-ul de expedieri îți permite să creezi, să urmărești, să modifici și să anulezi comenzi de expediere și listează fiecare colet într-un singur loc, indiferent cine l-a rezervat.

## O singură listă, filtrată

`GET /api/v1/shipments` este singura colecție. O expediere este independentă — are o relație mulți-la-mulți cu programările și poate aparține unei comenzi de kit de testare la domiciliu — deci nu există nicio listă imbricată sub un părinte. Restrânge aceeași listă cu `?appointment_id=` sau `?home_kit_order_id=`, pagineaz-o cu `limit` / `offset` și urmărește array-ul `shipments` inline al părintelui (`{ id, added_at }` atât pe programări, cât și pe comenzile de kit de testare la domiciliu) către [Obține expedierea](https://docs.anivahealth.com/ro/api/shipments/get-shipment.md) când ai un id.

## Conținutul și cine a făcut rezervarea

Fiecare expediere conține două informații care nu reies din adresele sale:

* `contents` — text liber care descrie ce se află în colet, setat la creare (`"Medizinisch freigestellte Probe"`, `"Home test kit"`) și afișat curierului. Doar informativ. Direcția nu este un câmp: dacă un colet se îndreaptă spre un laborator se deduce din `destination`.
* `booked_by` — cine a tipărit eticheta: `aniva` sau `external`. Doar expedierile `aniva` acceptă [Actualizează](https://docs.anivahealth.com/ro/api/shipments/update-shipment.md) și [Anulează](https://docs.anivahealth.com/ro/api/shipments/cancel-shipment.md); un colet `external` este urmărit în aceeași listă, dar returnează `501` pentru ambele.

Un colet care a inclus o etichetă de retur și coletul pe care acea etichetă îl aduce înapoi indică unul spre celălalt prin `paired_with`.

## Acces

* Poți citi un colet atunci când cel puțin o programare sau o comandă de kit de testare la domiciliu asociată se află în contextul tău de acces sau când a plecat dintr-o locație aflată în contextul tău de acces.
* `appointments` și `home_kit_orders` listează doar programările și comenzile din contextul tău de acces.
* [Actualizează](https://docs.anivahealth.com/ro/api/shipments/update-shipment.md), [Anulează](https://docs.anivahealth.com/ro/api/shipments/cancel-shipment.md), [Atașează programări](https://docs.anivahealth.com/ro/api/shipments/attach-appointments-to-shipment.md) și [Detașează programări](https://docs.anivahealth.com/ro/api/shipments/detach-appointments-from-shipment.md) necesită ca fiecare comandă de kit de testare la domiciliu asociată să fie în contextul tău de acces. În caz contrar, apelul returnează `403` și doar Aniva poate modifica coletul.

## Citirile nu apelează niciodată curierul

Fiecare citire este servită din baza noastră de date. O sincronizare în fundal reconciliază fiecare expediere cu curierul său (la fiecare 10 minute pentru GO!, din oră în oră pentru DHL) și setează `synced_at`, care indică cât de vechi este orice răspuns. Nu există reîmprospătare forțată — DHL permite un apel de urmărire la fiecare cinci secunde, așa că o citire care să aștepte răspunsul curierului nu ar putea fi oferită.

## Crearea unei expedieri

Când creezi o expediere, specifici `location_id` de origine — locația de testare de unde trebuie să ridice curierul. De asemenea, indici laboratorul de destinație cu `destination_lab`. Expedierea merge la adresa de livrare înregistrată a acelui laborator.

Locația trebuie să fie în contextul de acces al cheii tale API. Folosește [Listează locațiile](https://docs.anivahealth.com/ro/api/locations/list-locations.md) pentru a găsi ID-urile locațiilor disponibile.

Opțional, poți transmite `appointment_id` pentru a asocia expedierea cu o anumită programare la
momentul creării. Asocierea apare inline pe ambele părți:

* pe expediere, ca un array `appointments` de intrări `{ id, added_at }`;
* pe programare, ca un array `shipments` de intrări `{ id, added_at }`.

Ambele array-uri sunt ordonate începând cu cea mai veche asociere. Fiecare `id` face referire la endpoint-ul canonic de detalii
([Obține programarea](https://docs.anivahealth.com/ro/api/appointments/get-appointment.md) /
[Obține expedierea](https://docs.anivahealth.com/ro/api/shipments/get-shipment.md)) pentru payload-ul complet — partenerii care doresc
evoluția curierului pe programare urmăresc fiecare intrare din array-ul `shipments` al programării către
endpoint-ul de detalii al expedierii.

O expediere poate fi asociată cu mai multe programări, iar o programare poate fi asociată cu mai multe
expedieri. După creare, gestionează asocierea cu [Atașează programări la
expediere](https://docs.anivahealth.com/ro/api/shipments/attach-appointments-to-shipment.md) /
[Detașează programări de la expediere](https://docs.anivahealth.com/ro/api/shipments/detach-appointments-from-shipment.md). Fiecare
operație de modificare returnează lista de programări a expedierii după aplicare.

Regula de modificare este: asocierile pot fi create sau eliminate atunci când FIE programarea a trecut de
recoltarea de sânge (`blood_drawn`), fie expedierea a fost creată cu mai puțin de 24 de ore în urmă. În afara acelui
interval, asocierea este blocată, astfel încât înregistrările istorice să rămână stabile.

## Ciclul de viață

Expedierile trec prin următoarele statusuri:

```text theme={null}
pending → in_transit → delivered
              ↓
            fault
    ↓
 cancelled
```

| Status | Semnificație |
| - | - |
| `pending` | Comanda de curierat a fost plasată și așteaptă ridicarea. |
| `in_transit` | Curierul a ridicat coletul și acesta este în tranzit. |
| `delivered` | Coletul a fost livrat. |
| `fault` | A apărut o problemă în timpul tranzitului sau curierul a returnat coletul expeditorului. |
| `cancelled` | Expedierea a fost anulată. |

Fiecare modificare de status trimite un [webhook](https://docs.anivahealth.com/ro/concepts/webhooks.md) `shipment.*`, de exemplu
`shipment.delivered`. `shipment.updated` se declanșează la fiecare modificare pe care o poți citi, cum ar fi o scanare nouă.

## Reguli pentru programul de ridicare

Următoarele reguli se aplică atunci când creezi sau actualizezi programul de ridicare al unei expedieri. `pickup_date`
(`YYYY-MM-DD`) și `pickup_time_from` / `pickup_time_till` (`HH:MM`, 24h) sunt valori de oră locală
**interpretate în fusul orar IANA al locației de origine** — nu trimiți un fus orar împreună cu acestea.

| Regulă | Detaliu |
| - | - |
| **Doar în zilele lucrătoare** | `pickup_date` trebuie să fie de luni până vineri. |
| **Astăzi sau în viitor** | `pickup_date` nu poate fi în trecut. |
| **Limită pentru aceeași zi** | Ridicările în aceeași zi sunt respinse după 16:00 Europe/Berlin. |
| **Interval orar** | `pickup_time_from` și `pickup_time_till` trebuie să fie în intervalul 09:00–19:00. |
| **Interval minim de 2 ore** | Intervalul de ridicare trebuie să aibă cel puțin 2 ore. |

## Modificarea expedierilor

Poți actualiza programul de ridicare, numărul de colete, greutatea și notele unei expedieri folosind `PATCH /api/v1/shipments/{id}`. Dacă se modifică vreun câmp relevant pentru logistică (data ridicării, ora, numărul de colete sau greutatea), comanda logistică existentă este anulată automat și se creează una nouă. Câmpurile pe care le omiți din corpul actualizării sunt păstrate din expedierea existentă — de exemplu, dacă actualizezi doar `weight`, comanda va fi recreată cu același program de ridicare. Câmpurile de program actualizate sunt validate conform acelorași [reguli pentru programul de ridicare](#reguli-pentru-programul-de-ridicare).

> [!WARNING]
>
> Expedierile nu pot fi modificate după ce curierul a ridicat coletul. Încercările de a actualiza o
> expediere cu statusul `in_transit`, `delivered` sau `fault` returnează `409 Conflict`.

Dacă furnizorul de logistică respinge anularea sau recrearea în timpul unei actualizări, API-ul returnează `502 Bad Gateway` împreună cu mesajul de eroare al furnizorului.

## Anularea expedierilor

Anulează o expediere folosind `DELETE /api/v1/shipments/{id}`. Această cerere apelează API-ul furnizorului de logistică pentru a anula comanda și actualizează statusul la `cancelled`.

> [!WARNING]
>
> Expedierile nu pot fi anulate după ridicare. Încercările de a anula o expediere care este deja
> `in_transit`, `delivered` sau `fault` returnează `409 Conflict`. Anularea uneia care este deja
> `cancelled` nu are niciun efect și returnează `200` cu expedierea — vezi
> [Idempotență](https://docs.anivahealth.com/ro/concepts/idempotency.md).

Furnizorul de logistică poate, de asemenea, să respingă anularea din motive proprii (de ex., termenul-limită de anulare a trecut). În acest caz, API-ul returnează `502 Bad Gateway` cu mesajul de eroare și codul de eroare ale furnizorului.

### Etichete de retur

O etichetă de retur DHL face parte din comanda sa inițială. DHL nu poate anula eticheta separat, așa că anularea rândului care urmărește o etichetă de retur returnează `409 Conflict`. Anulează în schimb coletul inițial, cât timp este `pending`. Astfel se anulează și eticheta: fiecare rând de retur aflat în `pending` al coletului inițial devine `cancelled` și primește o intrare `RETURN_LEG_CANCELLED` în `status_updates`. Un colet de retur pe care pacientul l-a trimis deja își continuă traseul. După ce coletul inițial pleacă, eticheta rămâne valabilă, iar Aniva închide manual rândul de retur.

## ID-uri de referință ale expedierilor

Fiecare expediere are un ID de referință de 11 caractere: o literă, data și patru caractere, `{letter}YYMMDDXXXX` (de exemplu, `P2611194821`). Litera arată cui aparține expedierea, niciodată direcția ei:

| Literă | Expediere |
| - | - |
| `P` | O expediere pe care o creezi prin acest API. |
| `M` | O expediere creată de echipa Aniva. |
| `C` | O expediere din trimiterea zilnică Aniva. |
| `K` | Un colet cu kit pentru acasă. |
| `F`, `S` | Colete din stocul propriu Aniva. |

O expediere din 20–22 noiembrie 2026 își păstrează ID-ul cu un cuvânt în față: `API`, `MAN`, `AUTO` sau `KIT` (de exemplu, `AUTO261121UWKX`). Ambele forme rămân valide. Nu verifica lungimea sau prima literă a unui ID. Folosește ID-ul pentru a prelua, actualiza sau anula expedierea.

## Adresele expedierii

Câmpurile `origin` și `destination` din răspunsul expedierii conțin obiecte de adresă rezolvate cu următoarea structură:

```json theme={null}
{
  "name": "Aniva Berlin Mitte",
  "company_name": null,
  "street": "Unter den Linden",
  "house_number": "42",
  "address_line_2": null,
  "postal_code": "10117",
  "city": "Berlin",
  "state": null,
  "country_code": "DE",
  "phone": "+4930987654321",
  "email": "berlin-mitte@anivahealth.com"
}
```

Pentru un colet de la cabinet, adresa `origin` este rezolvată din locația de testare pe care ai specificat-o la
creare, iar `destination` este laboratorul pe care l-ai indicat în `destination_lab`.
Pentru un colet cu kit pentru acasă, adresa de livrare a pacientului este `destination` pentru kit și
`origin` pentru returul probei; locația care ambalează kitul este `origin` al acestuia.
Adresa nu conține `location_id` — corelează un colet de la cabinet prin programarea de care este
legat.

## Interval de ridicare

Câmpul `pickup` din răspunsul expedierii conține intervalul programat de ridicare de către curier. Acesta
include marcajele temporale `from` și `till` ca momente UTC (ISO 8601 cu sufix `Z`, de ex.
`2026-04-15T07:00:00Z`) și un șir `timezone` (fusul orar IANA al locației de ridicare). Valorile
de oră locală `pickup_date` / `pickup_time_*` pe care le-ai trimis la creare / actualizare sunt convertite în aceste
momente absolute folosind acel fus orar — folosește `timezone` pentru a afișa `from` / `till` înapoi în
ora locală a locației de ridicare. Câmpul este `null` atunci când nu a fost programat niciun interval de ridicare.

## Jurnalul actualizărilor de status

Fiecare expediere conține un array `status_updates` — fiecare eveniment din ciclul de viață raportat
de furnizorul de logistică, de la cel mai vechi la cel mai nou. Fiecare intrare conține:

* `state` — evenimentul exprimat în vocabularul de statusuri ale expedierii (`pending`, `in_transit`, `delivered`,
  `fault`), ca să poți citi cronologia fără să cunoști codurile curierului. `null` când evenimentul
  nu poartă o stare (crearea etichetei, o scanare fără informații a curierului, intrări înregistrate înainte ca
  acest câmp să existe). Niciodată `cancelled` — o anulare este a noastră, nu un eveniment al curierului.
* `code` — codul propriu de status al curierului (`GO10`, `GO90`, `GOY001` la GO!; `VA`, `ZF`,
  `LA`, `ZU` la DHL). `null` când curierul nu a furnizat niciunul. Stabil indiferent de limba în care este tradus
  `status`.
* `detail_code` — codul mai detaliat al curierului, acolo unde există: `statusDetailed` de la DHL, de ex.
  `CNRFC_NRQRD_ZF` (redirecționat către un oficiu poștal), `HLDCC_SERPT_LA` (gata de ridicare acolo),
  `DLVRD_SERPT_ZU` (ridicat). `null` în rest.
* `status` — eticheta lizibilă a curierului (de ex. `"Shipment picked up"`,
  `"Die Sendung wurde abgeholt."`).
* `description` — o explicație a codului sau propoziția mai lungă a curierului. `null` când
  nu există niciuna.
* `location` — locul unde a avut loc scanarea, așa cum îl numește curierul: un depozit GO!, un oraș DHL. Text
  liber, nu o coordonată.
* `time` — marcajul temporal ISO 8601 al evenimentului, așa cum a fost raportat de curier (cu decalajul său).

Când curierul returnează coletul expeditorului, cronologia primește o intrare cu `code`
`RETURNED_TO_SENDER`. Câmpul său `status` conține motivul curierului. Expedierea rămâne apoi `fault`, chiar și
după ce curierul ne livrează coletul înapoi.

Lista poate fi goală dacă curierul nu a raportat încă niciun eveniment.

Folosește câmpul `status` de nivel superior pentru starea curentă canonică. Acesta avansează într-o singură direcție — de la `pending`
la `in_transit` și apoi la `delivered` — cu `fault` suprapus cât timp cel mai recent eveniment raportează o problemă;
curierii nu își ordonează evenimentele după importanță (DHL adaugă o notificare de redirecționare cu cod `pre-transit`
după scanarea de predare), așa că cea mai recentă intrare singură nu arată în ce stadiu se află un colet.

## Exemplu de expediere

```json theme={null}
{
  "id": "P2611194821",
  "status": "pending",
  "logistics_provider": "go",
  "tracking_number": null,
  "contents": null,
  "booked_by": "aniva",
  "paired_with": null,
  "origin": {
    "name": "Aniva Berlin Mitte",
    "company_name": null,
    "street": "Unter den Linden",
    "house_number": "42",
    "address_line_2": null,
    "postal_code": "10117",
    "city": "Berlin",
    "state": null,
    "country_code": "DE",
    "phone": "+4930987654321",
    "email": "berlin-mitte@anivahealth.com"
  },
  "destination": {
    "name": "LabClinic GmbH",
    "company_name": null,
    "street": "Laborstraße",
    "house_number": "10",
    "address_line_2": null,
    "postal_code": "80331",
    "city": "München",
    "state": null,
    "country_code": "DE",
    "phone": null,
    "email": null
  },
  "pickup": {
    "from": "2026-04-15T07:00:00Z",
    "till": "2026-04-15T10:00:00Z",
    "timezone": "Europe/Berlin"
  },
  "notes": "Handle with care — temperature-sensitive samples",
  "status_updates": [],
  "appointments": [
    {
      "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
      "added_at": "2026-04-03T14:30:00Z"
    }
  ],
  "home_kit_orders": [],
  "synced_at": null,
  "created_at": "2026-04-03T14:30:00Z",
  "updated_at": null
}
```

## Exemplu de colete cu kit pentru acasă

`GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-…` returnează kitul aflat pe drum spre pacient și proba aflată pe drum înapoi, în pereche:

```json theme={null}
[
  {
    "id": "K2609041FQ7",
    "status": "in_transit",
    "logistics_provider": "dhl_parcel",
    "tracking_number": "00340434779457841299",
    "contents": "Home test kit",
    "booked_by": "aniva",
    "paired_with": "K260904P3XD",
    "origin": { "name": "Aniva Health", "street": "Wilhelmstraße", "house_number": "118", "postal_code": "10963", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "destination": { "name": "Jane Doe", "street": "Friedrichstraße", "house_number": "123", "postal_code": "10117", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "pickup": null,
    "notes": null,
    "status_updates": [
      {
        "state": "pending",
        "code": "VA",
        "detail_code": "PARCV_NRQRD_VA",
        "status": "Die Auftragsdaten zu dieser Sendung wurden vom Absender elektronisch an DHL übermittelt.",
        "description": "Electronic advice from DHL — not a parcel scan",
        "location": null,
        "time": "2026-09-02T18:17:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "ES",
        "detail_code": "SHRCU_SERPT_ES",
        "status": "Die Sendung wurde in der Filiale eingeliefert.",
        "description": "Shipment in transit",
        "location": "Berlin",
        "time": "2026-09-04T18:13:00+02:00"
      }
    ],
    "appointments": [],
    "home_kit_orders": [{ "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "added_at": "2026-09-02T18:20:00Z" }],
    "synced_at": "2026-09-05T10:00:00Z",
    "created_at": "2026-09-02T18:20:00Z",
    "updated_at": "2026-09-05T10:00:00Z"
  },
  {
    "id": "K260904P3XD",
    "status": "pending",
    "logistics_provider": "dhl_parcel",
    "tracking_number": "00340434850359000004",
    "contents": "Sample return to lab",
    "booked_by": "aniva",
    "paired_with": "K2609041FQ7",
    "origin": { "name": "Jane Doe", "street": "Friedrichstraße", "house_number": "123", "postal_code": "10117", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "destination": { "name": "Labor Quade", "street": "Laborstraße", "house_number": "10", "postal_code": "50667", "city": "Köln", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "pickup": null,
    "notes": null,
    "status_updates": [],
    "appointments": [],
    "home_kit_orders": [{ "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "added_at": "2026-09-02T18:20:00Z" }],
    "synced_at": "2026-09-05T10:00:00Z",
    "created_at": "2026-09-02T18:20:00Z",
    "updated_at": null
  }
]
```

Rândul de retur există din momentul în care eticheta de retur este tipărită și rămâne `pending` până când pacientul trimite proba — aceasta este starea reală, nu o lipsă.


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