Přejít na hlavní obsah
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.

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 a Zrušit; 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, Zrušit, Připojit termíny a Odpojit termíny 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. 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 / Získat zásilku) 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 / Odpojit termíny od zásilky. 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:
Každá změna stavu odešle webhook 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áš.

Ú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í.
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.
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.
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: 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:
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

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