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

# Vypsat zásilky

> Načíst zásilky filtrované podle termínu, objednávky domácí sady nebo stavu

Načti zásilky přístupné tvému API klíči, od nejnovějších. V tomto jednom seznamu je každý balík:
kurýrní svoz z ordinace, sada na cestě k pacientovi s domácí testovací sadou i vzorek na
cestě zpět. Filtrovat na jednu nadřazenou položku můžeš pomocí `appointment_id` nebo `home_kit_order_id`.

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

Odpověď pochází z naší databáze a nikdy nevolá dopravce. Synchronizace na pozadí aktualizuje každou
zásilku (každých 10 minut u GO!, každou hodinu u DHL) a pole `synced_at` u každého řádku ti řekne, kdy jsme se
dopravce naposledy ptali.

## Požadavek

### Parametry dotazu

**appointment\_id** `string`

Pouze zásilky propojené s tímto termínem (UUID). `404`, když termín neexistuje, `403`,
když je mimo tvůj přístupový kontext.

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

Pouze zásilky propojené s touto objednávkou domácí testovací sady (UUID). Obvykle se vrátí dva řádky – sada na
cestě k pacientovi a vzorek zpět do laboratoře (jeho `destination` je laboratoř). Stejná
pravidla pro `404` / `403` jako u `appointment_id`.

**status** `string`

Pouze zásilky v tomto stavu. Jedna z hodnot `pending`, `in_transit`, `delivered`, `fault`, `cancelled`.

**limit** `integer`

Maximální počet vrácených zásilek. Výchozí hodnota je 100, maximum 500.

**offset** `integer`

Počet zásilek k přeskočení. Výchozí hodnota je 0. Řazení je stabilní (`created_at` sestupně, poté
reference), takže se stránky nepřekrývají.

## Odpověď

Při úspěchu vrátí API `200 OK` s polem objektů zásilek.

**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 po dobu 5 minut pro každý API klíč. Opakované volání v tomto
čase dostane uloženou odpověď. Hlavičky `Cache-Status` a `Age` ukazují, že je odpověď
uložená a jak je stará.

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ý parametr dotazu. |
| `403` | Zakázáno – chybějící scope, nebo je filtrovaný termín / objednávka domácí testovací sady mimo tvůj rozsah. |
| `404` | Filtrovaný termín nebo objednávku domácí testovací sady se nepodařilo najít. |
| `500` | Interní chyba serveru. |

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