> ## 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ásilky

> Jak v Aniva API funguje logistika: zásilky vzorků do laboratoře a balíčky s domácími testovacími sadami, včetně sledování a stavu.

Zásilka je jeden fyzický balík: kurýrní svoz vzorků krve z odběrového místa do laboratoře, domácí testovací sada na cestě k pacientovi nebo vzorek, který pacient posílá zpět. API pro zásilky ti umožňuje vytvářet, sledovat, upravovat a rušit objednávky zásilek a zobrazuje každý balík na jednom místě bez ohledu na to, kdo ho objednal.

## Jeden seznam, filtrovaný

`GET /api/v1/shipments` je jediná kolekce. Zásilka stojí samostatně — má vztah M:N k termínům a může patřit k objednávce domácí testovací sady — takže pod nadřazeným záznamem neexistuje žádný vnořený seznam. Stejný seznam zúžíš pomocí `?appointment_id=` nebo `?home_kit_order_id=`, stránkuješ ho přes `limit` / `offset` a když máš jedno ID, přejdi přes vložené pole `shipments` u nadřazeného záznamu (`{ id, added_at }` u termínů i objednávek domácích testovacích sad) na [Získat zásilku](https://docs.anivahealth.com/cs/api/shipments/get-shipment.md).

## Obsah a kdo zásilku objednal

Každá zásilka nese dva údaje, které nejsou vidět z jejích adres:

* `contents` — volný text popisující obsah balíku, nastavený při vytvoření (`"Medizinisch freigestellte Probe"`, `"Home test kit"`) a zobrazený kurýrovi. Má jen informační charakter. Směr není samostatné pole: jestli balík míří do laboratoře, vyčteš z pole `destination`.
* `booked_by` — kdo vytiskl štítek: `aniva` nebo `external`. Pouze zásilky `aniva` podporují [Aktualizovat](https://docs.anivahealth.com/cs/api/shipments/update-shipment.md) a [Zrušit](https://docs.anivahealth.com/cs/api/shipments/cancel-shipment.md); balík `external` se sleduje ve stejném seznamu, ale u obou operací vrátí `501`.

Balík, který vezl zpětný štítek, a balík, který se s tímto štítkem vrací zpět, na sebe vzájemně odkazují přes `paired_with`.

## Přístup

* Balík můžeš číst, když je v tvém přístupovém kontextu alespoň jeden propojený termín nebo objednávka domácí testovací sady, nebo když odešel z místa v tvém přístupovém kontextu.
* `appointments` a `home_kit_orders` uvádějí jen termíny a objednávky v tvém přístupovém kontextu.
* [Aktualizovat](https://docs.anivahealth.com/cs/api/shipments/update-shipment.md), [Zrušit](https://docs.anivahealth.com/cs/api/shipments/cancel-shipment.md), [Připojit termíny](https://docs.anivahealth.com/cs/api/shipments/attach-appointments-to-shipment.md) a [Odpojit termíny](https://docs.anivahealth.com/cs/api/shipments/detach-appointments-from-shipment.md) vyžadují, aby v tvém přístupovém kontextu byla každá propojená objednávka domácí testovací sady. Jinak volání vrátí `403` a balík může změnit jen Aniva.

## Čtení nikdy nevolá dopravce

Každé čtení se obsluhuje z naší databáze. Synchronizace na pozadí porovnává každou zásilku s jejím dopravcem (každých 10 minut pro GO!, každou hodinu pro DHL) a zapisuje časové razítko `synced_at`, podle kterého poznáš stáří odpovědi. Vynucená aktualizace neexistuje — DHL povoluje jedno sledovací volání každých pět sekund, takže čtení s přímým dotazem na dopravce nelze nabídnout.

## Vytvoření zásilky

Při vytváření zásilky zadáš výchozí `location_id` — odběrové místo, kde má kurýr zásilku vyzvednout. Pomocí `destination_lab` také uvedeš cílovou laboratoř. Zásilka míří na registrovanou doručovací adresu této laboratoře.

Místo musí být v přístupovém kontextu tvého API klíče. Pro zjištění dostupných ID míst použij [Vypsat místa](https://docs.anivahealth.com/cs/api/locations/list-locations.md).

Volitelně můžeš předat `appointment_id` a propojit zásilku s konkrétním termínem už při jejím
vytvoření. Propojení se zobrazí přímo na obou stranách:

* u zásilky jako pole `appointments` se záznamy `{ id, added_at }`;
* u termínu jako pole `shipments` se záznamy `{ id, added_at }`.

Obě pole jsou seřazená od nejstaršího propojení. Každé `id` odkazuje na kanonický endpoint detailu
([Získat termín](https://docs.anivahealth.com/cs/api/appointments/get-appointment.md) /
[Získat zásilku](https://docs.anivahealth.com/cs/api/shipments/get-shipment.md)) pro kompletní data — partneři, kteří chtějí sledovat
průběh přepravy u jednotlivých termínů, přejdou podle každého záznamu v poli `shipments` termínu
na endpoint detailu zásilky.

Jedna zásilka může být propojená s více termíny a jeden termín může být propojený s více
zásilkami. Po vytvoření spravuj propojení pomocí [Připojit termíny
k zásilce](https://docs.anivahealth.com/cs/api/shipments/attach-appointments-to-shipment.md) /
[Odpojit termíny od zásilky](https://docs.anivahealth.com/cs/api/shipments/detach-appointments-from-shipment.md). Každá
změna vrátí aktualizovaný seznam termínů zásilky.

Pravidlo pro úpravy zní: propojení lze vytvořit nebo odebrat, pokud je BUĎ termín po
odběru krve (`blood_drawn`), nebo byla zásilka vytvořena před méně než 24 hodinami. Mimo toto
okno je propojení uzamčené, aby historické záznamy zůstaly stabilní.

## Životní cyklus

Zásilky procházejí následujícími stavy:

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

| Stav | Význam |
| - | - |
| `pending` | Objednávka kurýra byla zadána a čeká na vyzvednutí. |
| `in_transit` | Kurýr balík vyzvedl a ten je na cestě. |
| `delivered` | Balík byl doručen. |
| `fault` | Během přepravy nastal problém, nebo dopravce poslal balík zpět odesílateli. |
| `cancelled` | Zásilka byla zrušena. |

Každá změna stavu odešle [webhook](https://docs.anivahealth.com/cs/concepts/webhooks.md) `shipment.*`, například
`shipment.delivered`. `shipment.updated` se spustí při každé změně, kterou můžeš přečíst, například při novém skenu.

## Pravidla pro plánování vyzvednutí

Při vytváření nebo úpravě plánu vyzvednutí zásilky platí následující pravidla. `pickup_date`
(`YYYY-MM-DD`) a `pickup_time_from` / `pickup_time_till` (`HH:MM`, 24h) jsou hodnoty místního času
**interpretované v časovém pásmu IANA místa odeslání** – časové pásmo s nimi neposíláš.

| Pravidlo | Detail |
| - | - |
| **Jen pracovní dny** | `pickup_date` musí být pondělí–pátek. |
| **Dnes nebo v budoucnu** | `pickup_date` nesmí být v minulosti. |
| **Uzávěrka pro stejný den** | Vyzvednutí v tentýž den jsou po 16:00 Europe/Berlin zamítnuta. |
| **Rozsah okna** | `pickup_time_from` a `pickup_time_till` musí být v rozmezí 09:00–19:00. |
| **Minimálně 2hodinové okno** | Okno pro vyzvednutí musí být dlouhé alespoň 2 hodiny. |

## Úprava zásilek

Plán vyzvednutí zásilky, počet balíků, hmotnost a poznámky můžeš upravit pomocí `PATCH /api/v1/shipments/{id}`. Pokud se změní některé pole důležité pro logistiku (datum vyzvednutí, čas, počet balíků nebo hmotnost), stávající logistická objednávka se automaticky zruší a vytvoří se nová. Pole, která v těle požadavku vynecháš, se převezmou ze stávající zásilky – například úprava samotného pole `weight` vytvoří objednávku znovu se stejným plánem vyzvednutí. Upravená pole plánu se ověřují podle stejných [pravidel pro plánování vyzvednutí](#pravidla-pro-planovani-vyzvednuti).

> [!WARNING]
>
> Zásilky nelze upravovat poté, co kurýr balík vyzvedne. Pokusy o úpravu
> zásilky ve stavu `in_transit`, `delivered` nebo `fault` vrátí `409 Conflict`.

Pokud poskytovatel logistiky zrušení nebo opětovné vytvoření během úpravy zamítne, API vrátí `502 Bad Gateway` s chybovou zprávou poskytovatele.

## Rušení zásilek

Zásilku zrušíš pomocí `DELETE /api/v1/shipments/{id}`. Tím se zavolá API poskytovatele logistiky pro zrušení objednávky a stav se změní na `cancelled`.

> [!WARNING]
>
> Zásilky nelze po vyzvednutí zrušit. Pokusy o zrušení zásilky, která je už
> ve stavu `in_transit`, `delivered` nebo `fault`, vrátí `409 Conflict`. Zrušení zásilky, která už je
> `cancelled`, nic nezmění a vrátí `200` se zásilkou – viz
> [Idempotence](https://docs.anivahealth.com/cs/concepts/idempotency.md).

Poskytovatel logistiky může zrušení zamítnout i z vlastních důvodů (např. uplynula lhůta pro zrušení). V takovém případě API vrátí `502 Bad Gateway` s chybovou zprávou a kódem chyby poskytovatele.

### Zpětné štítky

Zpětný štítek DHL je součástí odchozí objednávky. DHL nemůže štítek zrušit samostatně, takže zrušení záznamu, který zpětný štítek sleduje, vrátí `409 Conflict`. Místo toho zruš odchozí balík, dokud je ve stavu `pending`. Tím se zruší i štítek: každý zpětný záznam odchozího balíku ve stavu `pending` přejde do stavu `cancelled` a do `status_updates` dostane položku `RETURN_LEG_CANCELLED`. Zpětný balík, který pacient už podal, pokračuje v cestě. Jakmile odchozí balík odejde, štítek zůstává platný a Aniva záznam zpětné zásilky uzavře ručně.

## Referenční ID zásilek

Každá zásilka má 11znakové referenční ID: písmeno, datum a čtyři znaky, `{letter}YYMMDDXXXX` (například `P2611194821`). Písmeno určuje, k čemu zásilka patří, nikdy ne její směr:

| Písmeno | Zásilka |
| - | - |
| `P` | Zásilka, kterou vytvoříš přes toto API. |
| `M` | Zásilka, kterou vytvoří tým Aniva. |
| `C` | Zásilka z denní expedice Aniva. |
| `K` | Balíček s domácí sadou. |
| `F`, `S` | Vlastní skladové balíky Aniva. |

Zásilka z 20. až 22. listopadu 2026 si ponechává své ID se slovem na začátku: `API`, `MAN`, `AUTO` nebo `KIT` (například `AUTO261121UWKX`). Oba tvary zůstávají platné. Nekontroluj délku ani první písmeno ID. Použij ID k načtení, aktualizaci nebo zrušení zásilky.

## Adresy zásilek

Pole `origin` a `destination` v odpovědi zásilky obsahují vyhodnocené objekty adres s následující strukturou:

```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"
}
```

U balíku z ordinace se adresa `origin` určí podle testovacího místa zadaného při
vytvoření a `destination` je laboratoř uvedená v `destination_lab`.
U balíku s domácí sadou je doručovací adresa pacienta `destination` sady a
`origin` pro vrácení vzorku; pracoviště, které sadu balí, je její `origin`. Adresa
neobsahuje `location_id` – balík z ordinace spáruj přes termín, ke kterému je
připojený.

## Okno pro vyzvednutí

Pole `pickup` v odpovědi zásilky obsahuje naplánované okno pro vyzvednutí kurýrem.
Zahrnuje časová razítka `from` a `till` jako okamžiky v UTC (ISO 8601 s příponou `Z`, např.
`2026-04-15T07:00:00Z`) a řetězec `timezone` (časové pásmo IANA místa vyzvednutí). Hodnoty
místního času `pickup_date` / `pickup_time_*` odeslané při vytvoření nebo úpravě se pomocí tohoto
časového pásma převedou na tyto absolutní okamžiky – použij `timezone` k převodu `from` / `till` zpět na
místní čas místa vyzvednutí. Pokud není naplánováno žádné okno pro vyzvednutí, pole má hodnotu `null`.

## Záznam změn stavu

Každá zásilka obsahuje pole `status_updates` – všechny události životního cyklu, které poskytovatel
logistiky nahlásil, od nejstarší. Každá položka obsahuje:

* `state` – událost ve slovníku stavů zásilky (`pending`, `in_transit`, `delivered`,
  `fault`), takže časovou osu přečteš i bez znalosti kódů dopravce. `null`, když událost
  nenese žádný stav (vytvoření štítku, sken dopravce bez informací, položky zaznamenané před
  vznikem tohoto pole). Nikdy `cancelled` – zrušení je naše akce, ne událost dopravce.
* `code` – vlastní stavový kód dopravce (u GO! `GO10`, `GO90`, `GOY001`; u DHL `VA`, `ZF`,
  `LA`, `ZU`). `null`, když dopravce žádný nedodal. Zůstává stabilní napříč jazykovými překlady
  pole `status`.
* `detail_code` – 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). Jinak `null`.
* `status` – čitelný popis od dopravce (např. `"Shipment picked up"`,
  `"Die Sendung wurde abgeholt."`).
* `description` – vysvětlení kódu nebo delší věta od dopravce. `null`, když
  ani jedno neexistuje.
* `location` – místo skenu podle pojmenování dopravce: depo GO!, město u DHL. Volný
  text, ne souřadnice.
* `time` – časové razítko události ve formátu ISO 8601, jak ho nahlásil dopravce (včetně posunu).

Když dopravce pošle balík zpět odesílateli, na časové ose přibude jedna položka s `code`
`RETURNED_TO_SENDER`. Její `status` obsahuje důvod od dopravce. Zásilka pak zůstane ve stavu `fault`, a to i
poté, co dopravce balík doručí zpět k nám.

Seznam může být prázdný, pokud dopravce zatím nenahlásil žádné události.

Pro směrodatný aktuální stav použij pole `status` nejvyšší úrovně. Posouvá se jedním směrem – z `pending`
přes `in_transit` do `delivered` – přičemž `fault` ho překryje, dokud nejnovější událost hlásí chybu;
dopravci neřadí události podle významu (DHL po skenu předání přidává oznámení o přesměrování s kódem
`pre-transit`), takže samotná nejnovější položka neříká, v jaké fázi balík je.

## Příklad zásilky

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

## Příklad balíků s domácí sadou

`GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-…` vrátí sadu na cestě k pacientovi a vzorek na cestě zpět v páru:

```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
  }
]
```

Záznam zpětné zásilky existuje od chvíle, kdy se vytiskne zpětný štítek, a zůstává ve stavu `pending`, dokud pacient vzorek nepošle – je to skutečný stav, ne mezera.


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