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

# Získat zásilku

> Načíst zásilku podle referenčního ID

Načte jednu zásilku podle jejího referenčního ID. Odpověď pochází z naší databáze a nikdy
nevolá přepravce. Synchronizace na pozadí aktualizuje každou zásilku (každých 10 minut u GO!, každou hodinu u
DHL) a `synced_at` ti ukáže, kdy byl přepravce naposledy dotázán.

Vyžaduje scope `shipments_view` nebo `shipments_manage`.

## Požadavek

### Parametry cesty

**id** `string` *required*

Referenční ID zásilky (např. `P2611194821`).

## Odpověď

Při úspěchu vrátí API `200 OK` s objektem zásilky.

**id** `string` *required*

Referenční identifikátor zásilky.

**status** `string` *required*

Stav životního cyklu zásilky. Jedna z hodnot `pending`, `in_transit`, `delivered`, `fault` nebo `cancelled`.

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

Poskytovatel logistiky. Jedna z hodnot `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` nebo `dhl_express`. Balík s domácí sadou je `dhl_parcel`, případně `dhl_warenpost`, když jde do zahraničí
jako Warenpost International.

**tracking\_number** `string`

Externí sledovací číslo od poskytovatele logistiky. Může být `null`.

**contents** `string`

Volný textový popis obsahu balíku zadaný při vytvoření (např. `"Medizinisch
    freigestellte Probe"`, `"Home test kit"`). Pouze informativní — zda balík míří do
laboratoře, vyčteš z `destination`, a jeho protějšek z `paired_with`. Může být `null`.

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

Kdo vytiskl štítek: `aniva` nebo `external`. Pouze zásilky `aniva` podporují
[Aktualizaci](https://docs.anivahealth.com/cs/api/shipments/update-shipment.md) a [Zrušení](https://docs.anivahealth.com/cs/api/shipments/cancel-shipment.md); balík
`external` je sledovaný, ale u obou vrátí `501`.

**paired\_with** `string`

Reference druhého balíku z dvoubalíkové zásilky – balíku, který obsahoval štítek pro vrácení,
a balíku, který tento štítek vrací zpět. Nastaveno u obou. `null` u jednosměrného balíku.

**origin** `object`

Adresa vyzvednutí. Může být `null`.

**objekt adresy**

**name** `string` *required*

Jméno příjemce, název firmy nebo místa.

**company\_name** `string`

Řádek firma / c/o. Může být `null`.

**street** `string` *required*

Název ulice bez čísla domu.

**house\_number** `string`

Číslo domu. Může být `null`.

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

Budova, vchod nebo patro. Může být `null`.

**city** `string` *required*

Město.

**state** `string`

Stát nebo provincie. Může být `null`.

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

PSČ.

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

Kód země podle ISO 3166-1 alpha-2.

**phone** `string`

Kontaktní telefonní číslo. Může být `null`.

**email** `string`

Kontaktní e-mail. Může být `null`.

**destination** `object`

Doručovací adresa. Stejná struktura jako `origin`. Může být `null`.

**pickup** `object`

Naplánované okno vyzvednutí. Může být `null`.

**objekt pickup**

**from** `string` *required*

Začátek okna vyzvednutí jako okamžik v UTC (ISO 8601 s příponou `Z`).

**till** `string` *required*

Konec okna vyzvednutí jako okamžik v UTC (ISO 8601 s příponou `Z`).

**timezone** `string` *required*

Časové pásmo IANA místa vyzvednutí (např. `Europe/Berlin`). Použij k zobrazení `from` / `till` v místním čase místa vyzvednutí.

**notes** `string`

Volitelné poznámky. Může být `null`.

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

Chronologické události životního cyklu od logistického poskytovatele (od nejstarší). Prázdné pole, pokud
poskytovatel ještě žádné události neohlásil. Použij je pro zobrazení jednotlivých událostí v UI, audit a jemnější signály
dopravce; pro aktuální kanonický stav se spolehni na `status`.

**pole aktualizace stavu**

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

Událost ve slovníku stavů zásilky – `pending`, `in_transit`, `delivered` nebo
`fault` – takže si můžeš projít časovou osu bez znalosti kódů dopravce. `null`, když
událost nenese žádný stav (vytvoření štítku, sken dopravce „bez informací“, záznamy pořízené
před zavedením tohoto pole). Nikdy `cancelled`.

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

Vlastní stavový kód dopravce: u GO! `GO10` / `GO90` / `GOY001`, u DHL `VA` / `ZF` / `LA`
/ `ZU`. `null`, když dopravce žádný neposkytl. Zůstává stejný bez ohledu na jazykovou verzi
`status`.

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

Podrobnější kód dopravce, pokud ho používá – u DHL `statusDetailed`, např. `CNRFC_NRQRD_ZF`
(přesměrováno na poštu), `HLDCC_SERPT_LA` (připraveno tam k vyzvednutí), `DLVRD_SERPT_ZU`
(vyzvednuto). `null` u dopravců, kteří ho nemají.

**status** `string` *required*

Stavový popisek od poskytovatele (volný text, např. `"Shipment picked up"`,
`"Die Sendung wurde abgeholt."`).

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

Vysvětlení kódu nebo delší věta od dopravce. `null`, když neexistuje ani jedno.

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

Místo skenu, jak ho pojmenovává dopravce – depo GO! (`"HUB Niederaula"`) nebo
město u DHL. Volný text, ne souřadnice. `null`, když dopravce žádné neuvedl.

**time** `string` *required*

Čas zaznamenání události (ISO 8601 s časovým posunem uvedeným dopravcem).

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

Termíny propojené s touto zásilkou, od nejstaršího propojení. Každá položka má tvar `{ id, added_at }`;
každé `id` si dohledej přes [Získat termín](https://docs.anivahealth.com/cs/api/appointments/get-appointment.md) pro
kompletní data termínu. Prázdné pole, když nejsou propojené žádné termíny.
Uvedeny jsou pouze termíny v tvém přístupovém kontextu.

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

Objednávky domácích testovacích sad propojené s touto zásilkou, od nejstaršího propojení, ve stejném tvaru `{ id, added_at }`.
Každé `id` si dohledej přes [Získat objednávku domácí testovací sady](https://docs.anivahealth.com/cs/api/home-kit-orders/get-home-kit.md). Prázdné
pole pro balíky z ordinací. Uvedeny jsou pouze objednávky v tvém přístupovém kontextu. Viz
[Přístup](https://docs.anivahealth.com/cs/concepts/shipments.md#pristup).

**synced\_at** `string`

Čas posledního sladění zásilky s dopravcem v UTC. Čtení nikdy nevolá
dopravce – zásilky udržuje aktuální synchronizace na pozadí – takže tento údaj říká, jak stará je odpověď. `null` až do
první synchronizace.

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

Časové razítko vytvoření (ISO 8601).

**updated\_at** `string`

Časové razítko poslední aktualizace (ISO 8601). Může být `null`.

## Opakovaná volání

Aniva ukládá odpověď tohoto endpointu pro každý API klíč na 60 minut. Opakované volání během
této doby dostane uloženou odpověď, dokud se zásilka nezmění. Po změně dostaneš čerstvou
odpověď. Hlavičky `Cache-Status` a `Age` ukazují, že je odpověď
uložená a jak je stará.

V uložené odpovědi mohou být `synced_at` a `updated_at` starší než v čerstvé odpovědi.

Pokud se chceš o změně dozvědět hned, přihlas se k odběru webhookových událostí `shipment.created` a `shipment.updated`.
Viz [Opakované čtení](https://docs.anivahealth.com/cs/concepts/webhooks.md#opakovana-cteni).

## Chybové odpovědi

| Stav | Popis |
| - | - |
| `400` | Neplatný formát ID. |
| `403` | Zakázáno – tvůj API klíč nemá přístup k této operaci nebo je zásilka mimo tvůj přístupový kontext. Balík je v tvém přístupovém kontextu tehdy, když v něm je alespoň jeden propojený termín nebo objednávka domácí testovací sady. |
| `404` | Zásilka nenalezena. |
| `500` | Interní chyba serveru. |

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