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 poledestination.booked_by— kdo vytiskl štítek:anivaneboexternal. Pouze zásilkyanivapodporují Aktualizovat a Zrušit; balíkexternalse sleduje ve stejném seznamu, ale u obou operací vrátí501.
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.
appointmentsahome_kit_ordersuvá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í
403a 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ítkosynced_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
appointmentsse záznamy{ id, added_at }; - u termínu jako pole
shipmentsse záznamy{ id, added_at }.
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í.
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.
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
Poleorigin a destination v odpovědi zásilky obsahují vyhodnocené objekty adres s následující strukturou:
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í
Polepickup 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 polestatus_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). Nikdycancelled– zrušení je naše akce, ne událost dopravce.code– vlastní stavový kód dopravce (u GO!GO10,GO90,GOY001; u DHLVA,ZF,LA,ZU).null, když dopravce žádný nedodal. Zůstává stabilní napříč jazykovými překlady polestatus.detail_code– podrobnější kód dopravce, pokud ho používá: u DHLstatusDetailed, např.CNRFC_NRQRD_ZF(přesměrováno na poštu),HLDCC_SERPT_LA(připraveno tam k vyzvednutí),DLVRD_SERPT_ZU(vyzvednuto). Jinaknull.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).
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:
pending, dokud pacient vzorek nepošle – je to skutečný stav, ne mezera.