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

# Obține expedierea

> Preia o expediere după ID-ul de referință

Preia o singură expediere după ID-ul ei de referință. Răspunsul vine din baza noastră de date și nu apelează
niciodată transportatorul. O sincronizare în fundal actualizează fiecare expediere (la fiecare 10 minute pentru GO!, din oră în oră pentru
DHL), iar `synced_at` îți spune când a fost interogat ultima dată transportatorul.

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

## Cerere

### Parametri de cale

**id** `string` *required*

ID-ul de referință al expedierii (de ex., `P2611194821`).

## Răspuns

În caz de succes, API-ul returnează `200 OK` împreună cu obiectul expedierii.

**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 60 de minute pentru fiecare cheie API. Un apel repetat în
acest interval primește răspunsul stocat cât timp expedierea rămâne neschimbată. După o modificare, primești un răspuns
nou. Antetele `Cache-Status` și `Age` arată că răspunsul este
stocat și cât de vechi este.

Într-un răspuns stocat, `synced_at` și `updated_at` pot fi mai vechi decât într-un răspuns nou.

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` | Format de ID invalid. |
| `403` | Interzis — cheia ta API nu are acces la această operațiune sau expedierea este în afara contextului tău de acces. Un colet este în contextul tău de acces când cel puțin o programare sau o comandă de kit de testare la domiciliu asociată este în acesta. |
| `404` | Expedierea nu a fost găsită. |
| `500` | Eroare internă de server. |

```bash cURL theme={null}
curl --request GET \
  --url https://anivahealth.com/api/v1/shipments/P2611194821 \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
{
  "id": "P2611194821",
  "status": "in_transit",
  "logistics_provider": "go",
  "tracking_number": "GO123456789",
  "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-03T14:30:00Z",
  "updated_at": "2026-04-15T11:20:00Z"
}
```

```json 404 theme={null}
{
  "error": "Shipment not found"
}
```


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