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

# Listează expedierile

> Preia expedieri, filtrate după programare, comandă de kit pentru acasă sau status

Obține expedierile accesibile cheii tale API, cele mai noi primele. Fiecare colet se află în această listă unică:
o preluare prin curier de la un cabinet, kitul în drum spre un pacient cu kit de testare la domiciliu și proba pe
drumul de întoarcere. Filtrează după un singur element părinte cu `appointment_id` sau `home_kit_order_id`.

Necesită scope-ul `shipments_view` sau `shipments_manage`.

Răspunsul vine din baza noastră de date și nu apelează niciodată curierul. O sincronizare în fundal actualizează fiecare
expediere (la fiecare 10 minute pentru GO!, din oră în oră pentru DHL), iar `synced_at` din fiecare rând îți arată când a fost
interogat ultima dată curierul.

## Cerere

### Parametri de interogare

**appointment\_id** `string`

Doar expedierile asociate cu această programare (UUID). `404` când programarea nu există, `403`
când este în afara contextului tău de acces.

**home\_kit\_order\_id** `string`

Doar expedierile asociate cu această comandă de kit de testare la domiciliu (UUID). În mod normal sunt returnate două rânduri — kitul în
drum spre pacient și proba înapoi la laborator (`destination` este laboratorul). Aceleași
reguli `404` / `403` ca la `appointment_id`.

**status** `string`

Doar expedierile cu acest status. Una dintre valorile `pending`, `in_transit`, `delivered`, `fault`, `cancelled`.

**limit** `integer`

Numărul maxim de expedieri returnate. Implicit 100, maximum 500.

**offset** `integer`

Numărul de expedieri omise. Implicit 0. Sortarea este stabilă (`created_at` descrescător, apoi
referință), astfel încât paginile nu se suprapun.

## Răspuns

În caz de succes, API-ul returnează `200 OK` cu un array de obiecte de expediere.

**id** `string` *required*

Identificatorul de referință al expedierii.

**status** `string` *required*

Starea expedierii în ciclul de viață. Una dintre valorile `pending`, `in_transit`, `delivered`, `fault` sau `cancelled`.

**logistics\_provider** `string` *required*

Furnizorul de logistică. Una dintre valorile `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` sau `dhl_express`. Un colet cu kit pentru acasă folosește `dhl_parcel` sau `dhl_warenpost` când pleacă în străinătate
ca Warenpost International.

**tracking\_number** `string`

Numărul extern de urmărire de la furnizorul de logistică. Poate fi `null`.

**contents** `string`

Descriere în text liber a conținutului coletului, așa cum a fost dată la creare (de ex., `"Medizinisch
    freigestellte Probe"`, `"Home test kit"`). Doar informativ — dacă un colet merge către un
laborator se citește din `destination`, iar perechea lui din `paired_with`. Poate fi `null`.

**booked\_by** `string` *required*

Cine a tipărit eticheta: `aniva` sau `external`. Doar expedierile `aniva` acceptă
[Actualizare](https://docs.anivahealth.com/ro/api/shipments/update-shipment.md) și [Anulare](https://docs.anivahealth.com/ro/api/shipments/cancel-shipment.md); un
colet `external` este urmărit, dar returnează `501` la oricare dintre cele două.

**paired\_with** `string`

Referința celuilalt colet dintr-o expediere cu două colete — coletul care a conținut o etichetă
de retur și coletul pe care acea etichetă îl aduce înapoi. Setat pe ambele. `null` pentru un colet într-un singur sens.

**origin** `object`

Adresa de ridicare. Poate fi `null`.

**obiect adresă**

**name** `string` *required*

Numele destinatarului, al companiei sau al locației.

**company\_name** `string`

Linie companie / c/o. Poate fi `null`.

**street** `string` *required*

Numele străzii, fără numărul casei.

**house\_number** `string`

Numărul casei. Poate fi `null`.

**address\_line\_2** `string`

Bloc, scară sau etaj. Poate fi `null`.

**city** `string` *required*

Oraș.

**state** `string`

Stat sau provincie. Poate fi `null`.

**postal\_code** `string` *required*

Cod poștal.

**country\_code** `string` *required*

Cod de țară ISO 3166-1 alpha-2.

**phone** `string`

Număr de telefon de contact. Poate fi `null`.

**email** `string`

E-mail de contact. Poate fi `null`.

**destination** `object`

Adresa de livrare. Aceeași structură ca `origin`. Poate fi `null`.

**pickup** `object`

Intervalul programat de ridicare. Poate fi `null`.

**Obiectul pickup**

**from** `string` *required*

Începutul intervalului de ridicare ca moment UTC (ISO 8601 cu sufixul `Z`).

**till** `string` *required*

Sfârșitul intervalului de ridicare ca moment UTC (ISO 8601 cu sufixul `Z`).

**timezone** `string` *required*

Fusul orar IANA al locației de ridicare (de ex., `Europe/Berlin`). Folosește-l pentru a afișa `from` / `till` în ora locală a locației de ridicare.

**notes** `string`

Note opționale. Poate fi `null`.

**status\_updates** `object[]` *required*

Evenimentele cronologice din ciclul de viață de la furnizorul de logistică (cele mai vechi primele). Array gol dacă
furnizorul nu a raportat încă niciun eveniment. Folosește acest câmp pentru UI per eveniment, audit și semnalele mai detaliate
ale curierului; bazează-te pe `status` pentru starea curentă canonică.

**câmpurile actualizării de status**

**state** `string | null` *required*

Evenimentul în vocabularul de status al expedierii — `pending`, `in_transit`, `delivered` sau
`fault` — ca să poți citi un istoric fără să cunoști codurile curierului. `null` când
evenimentul nu are o stare (crearea etichetei, o scanare a curierului fără informații, înregistrări salvate
înainte ca acest câmp să existe). Niciodată `cancelled`.

**code** `string | null` *required*

Codul propriu de status al curierului: `GO10` / `GO90` / `GOY001` de la GO!, `VA` / `ZF` / `LA`
/ `ZU` de la DHL. `null` când curierul nu a furnizat niciunul. Rămâne stabil indiferent de traducerea câmpului
`status`.

**detail\_code** `string | null` *required*

Codul mai detaliat al curierului, acolo unde există — `statusDetailed` de la DHL, de ex. `CNRFC_NRQRD_ZF`
(redirecționat la un oficiu poștal), `HLDCC_SERPT_LA` (gata de ridicare de acolo), `DLVRD_SERPT_ZU`
(ridicat). `null` pentru curierii fără un astfel de cod.

**status** `string` *required*

Eticheta de status de la furnizor (text liber, de ex. `"Shipment picked up"`,
`"Die Sendung wurde abgeholt."`).

**description** `string | null` *required*

O explicație a codului sau fraza mai lungă a curierului. `null` când nu există niciuna.

**location** `string | null` *required*

Unde a avut loc scanarea, așa cum o numește curierul — un depozit GO! (`"HUB Niederaula"`) sau un
oraș DHL. Text liber, nu o coordonată. `null` când curierul nu a raportat niciuna.

**time** `string` *required*

Momentul la care a fost observat evenimentul (ISO 8601, cu decalajul raportat de curier).

**appointments** `ShipmentAppointmentLink[]` *required*

Programările asociate cu această expediere, în ordinea asocierii (cele mai vechi primele). Fiecare intrare este `{ id, added_at }`;
corelează fiecare `id` cu [Obține programarea](https://docs.anivahealth.com/ro/api/appointments/get-appointment.md) pentru
payload-ul complet al programării. Array gol când nu există programări asociate.
Sunt listate doar programările din contextul tău de acces.

**home\_kit\_orders** `ShipmentHomeKitOrderLink[]` *required*

Comenzile de kit de testare la domiciliu asociate cu această expediere, în ordinea asocierii (cele mai vechi primele), în același format `{ id, added_at }`.
Corelează fiecare `id` cu [Obține comanda de kit de testare la domiciliu](https://docs.anivahealth.com/ro/api/home-kit-orders/get-home-kit.md). Array
gol pentru coletele de la cabinete. Sunt listate doar comenzile din contextul tău de acces. Vezi
[Acces](https://docs.anivahealth.com/ro/concepts/shipments.md#acces).

**synced\_at** `string`

Când a fost sincronizată ultima dată expedierea cu curierul său, ca moment UTC. Citirile nu apelează niciodată
curierul — o sincronizare în fundal menține expedierile actualizate — așa că aceasta arată cât de vechi este răspunsul. `null` până
la prima sincronizare.

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

Data și ora creării (ISO 8601).

**updated\_at** `string`

Data și ora ultimei actualizări (ISO 8601). Poate fi `null`.

## Apeluri repetate

Aniva stochează răspunsul acestui endpoint timp de 5 minute pentru fiecare cheie API. Un apel repetat în
acest interval primește răspunsul stocat. Antetele `Cache-Status` și `Age` arată că răspunsul este
stocat și cât de vechi este.

Pentru a afla imediat despre o modificare, abonează-te la evenimentele webhook `shipment.created` și `shipment.updated`.
Vezi [Citiri repetate](https://docs.anivahealth.com/ro/concepts/webhooks.md#citiri-repetate).

## Răspunsuri de eroare

| Status | Descriere |
| - | - |
| `400` | Parametru de interogare invalid. |
| `403` | Interzis — scope lipsă sau programarea / comanda de kit de testare la domiciliu filtrată este în afara scope-ului tău. |
| `404` | Programarea sau comanda de kit de testare la domiciliu filtrată nu a fost găsită. |
| `500` | Eroare internă de server. |

```bash cURL (all shipments, first page) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?limit=100&offset=0' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (one home-kit order) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?home_kit_order_id=d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (one appointment, in transit) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?appointment_id=c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a&status=in_transit' \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
[
  {
    "id": "P2611194821",
    "status": "in_transit",
    "logistics_provider": "go",
    "tracking_number": "GO1234567890",
    "contents": "Medizinisch freigestellte Probe",
    "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": null,
    "status_updates": [
      {
        "state": "in_transit",
        "code": "GO10",
        "detail_code": null,
        "status": "Shipment picked up",
        "description": "Picked up at the consignor",
        "location": "Berlin",
        "time": "2026-04-15T09:22:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "GO50",
        "detail_code": null,
        "status": "Receiving station",
        "description": null,
        "location": "HUB Niederaula",
        "time": "2026-04-15T11:18:00+02:00"
      }
    ],
    "appointments": [
      {
        "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
        "added_at": "2026-04-15T08:30:00Z"
      }
    ],
    "home_kit_orders": [],
    "synced_at": "2026-04-15T11:20:00Z",
    "created_at": "2026-04-14T16:00:00Z",
    "updated_at": "2026-04-15T11:20:00Z"
  }
]
```


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