Ugrás a fő tartalomhoz
Egy szállítmány egy fizikai csomag: egy futár általi begyűjtés, amely vérmintákat szállít egy vizsgálati helyszínről egy laboratóriumba, az otthoni tesztkészletet használó pácienshez tartó készlet, vagy a minta, amelyet a páciens visszaküld postán. A Shipments API segítségével szállítmányrendeléseket hozhatsz létre, követhetsz nyomon, módosíthatsz és mondhatsz le, emellett egy helyen listáz minden csomagot, függetlenül attól, ki foglalta le.

Egyetlen lista, szűrve

A GET /api/v1/shipments az egyetlen gyűjtemény. Egy szállítmány önálló — több-a-többhöz kapcsolatban áll az időpontokkal, és tartozhat egy otthoni tesztkészlet-rendeléshez —, ezért nincs szülő alá beágyazott lista. Szűkítsd ugyanezt a listát a ?appointment_id= vagy ?home_kit_order_id= paraméterrel, lapozd a limit / offset segítségével, és kövesd a szülő beágyazott shipments tömbjét ({ id, added_at } mind az időpontokon, mind az otthoni tesztkészlet-rendeléseken) a Szállítmány lekérdezése végpontra, ha egyetlen azonosítód van.

Tartalom, és ki foglalta le

Minden szállítmány két olyan információt tartalmaz, amely a címeiből nem derül ki:
  • contents — szabad szöveg, amely leírja, mi van a csomagban; létrehozáskor állítják be ("Medizinisch freigestellte Probe", "Home test kit"), és a futárnak jelenik meg. Csak tájékoztató jellegű. Az irány nem külön mező: az, hogy egy csomag laboratóriumba tart-e, a destination mezőből olvasható ki.
  • booked_by — ki nyomtatta a címkét: aniva vagy external. Csak az aniva szállítmányoknál használható a Frissítés és a Lemondás; az external csomag ugyanebben a listában követhető nyomon, de mindkettőre 501 kóddal tér vissza.
A visszaküldési címkét szállító csomag és az a csomag, amelyet ez a címke visszahoz, a paired_with mezőn keresztül mutat egymásra.

Hozzáférés

  • Akkor olvashatsz egy csomagot, ha legalább egy hozzákapcsolt időpont vagy otthoni tesztkészlet-rendelés a hozzáférési kontextusodban van, vagy ha a csomag egy hozzáférési kontextusodba tartozó helyszínről indult.
  • Az appointments és a home_kit_orders csak a hozzáférési kontextusodban lévő időpontokat és rendeléseket listázza.
  • A Frissítés, a Lemondás, az Időpontok csatolása és az Időpontok leválasztása műveletekhez minden hozzákapcsolt otthoni tesztkészlet-rendelésnek a hozzáférési kontextusodban kell lennie. Ellenkező esetben a hívás 403 kóddal tér vissza, és csak az Aniva módosíthatja a csomagot.

Az olvasások soha nem hívják a futárszolgálatot

Minden olvasást az adatbázisunkból szolgálunk ki. Egy háttérszinkronizálás egyezteti az egyes szállítmányokat a futárszolgálattal (a GO! esetében 10 percenként, a DHL esetében óránként), és beállítja a synced_at időbélyeget, amely megmutatja, milyen régi a válasz. Nincs kényszerített frissítés — a DHL öt másodpercenként egy nyomkövetési hívást engedélyez, ezért olyan olvasást, amely a futárszolgálatot hívja meg, nem tudunk kínálni.

Szállítmány létrehozása

Szállítmány létrehozásakor megadod a kiindulási location_id értéket — azt a vizsgálati helyszínt, ahol a futárnak fel kell vennie a csomagot. A destination_lab mezővel a célként szolgáló laboratóriumot is megnevezed. A szállítmány az adott laboratórium regisztrált szállítási címére megy. A helyszínnek az API-kulcsod hozzáférési kontextusán belül kell lennie. Az elérhető helyszínazonosítók megkereséséhez használd a Helyszínek listázása végpontot. Opcionálisan megadhatod az appointment_id mezőt, hogy a szállítmányt már létrehozáskor egy adott időponthoz kapcsold. A kapcsolat mindkét oldalon beágyazva jelenik meg:
  • a szállítmányon egy { id, added_at } elemekből álló appointments tömbként;
  • az időponton egy { id, added_at } elemekből álló shipments tömbként.
Mindkét tömbben a legrégebbi kapcsolat áll elöl. Minden id a teljes adatcsomagot adó kanonikus részletvégpontra (Időpont lekérdezése / Szállítmány lekérdezése) hivatkozik — azok a partnerek, akik időpontonként szeretnék követni a futár állapotát, az időpont shipments tömbjének minden elemét a szállítmány részletvégpontjáig követhetik. Egy szállítmány több időponthoz is kapcsolható, és egy időpont is kapcsolható több szállítmányhoz. Létrehozás után a kapcsolatot az Időpontok csatolása szállítmányhoz / Időpontok leválasztása szállítmányról végpontokkal kezelheted. Minden módosítás a szállítmány módosítás utáni időpontlistájával tér vissza. A módosítási szabály: kapcsolatok akkor hozhatók létre vagy távolíthatók el, ha VAGY az időpont már túl van a vérvételen (blood_drawn), vagy a szállítmány kevesebb mint 24 órája jött létre. Ezen az időablakon kívül a kapcsolat zárolva van, hogy az előzményadatok stabilak maradjanak.

Életciklus

A küldemények a következő státuszokon mennek keresztül:
Minden státuszváltozás egy shipment.* webhookot küld, például shipment.delivered eseményt. A shipment.updated minden kiolvasható változáskor aktiválódik, például egy új szkennelésnél.

Felvételi ütemezési szabályok

A következő szabályok érvényesek a küldemény felvételi ütemezésének létrehozásakor vagy módosításakor. A pickup_date (YYYY-MM-DD) és a pickup_time_from / pickup_time_till (HH:MM, 24 órás) helyi idő szerinti értékek, amelyeket a feladóhely IANA időzónája szerint értelmezünk – külön időzónát nem kell küldened mellettük.

Küldemények módosítása

A PATCH /api/v1/shipments/{id} hívással módosíthatod a küldemény felvételi ütemezését, csomagszámát, súlyát és megjegyzéseit. Ha bármely logisztikai szempontból lényeges mező megváltozik (felvételi dátum, idő, csomagszám vagy súly), a meglévő logisztikai megbízást automatikusan lemondjuk, és újat hozunk létre. A kérés törzséből kihagyott mezők megmaradnak a meglévő küldeményből – ha például csak a weight mezőt frissíted, a megbízás ugyanazzal a felvételi ütemezéssel jön létre újra. A módosított ütemezési mezőket ugyanazok a felvételi ütemezési szabályok alapján ellenőrizzük.
A küldemények nem módosíthatók, miután a futár felvette a csomagot. Az in_transit, delivered vagy fault státuszú küldemény frissítésére tett kísérlet 409 Conflict választ ad.
Ha a logisztikai szolgáltató a frissítés során elutasítja a lemondást vagy az újbóli létrehozást, az API 502 Bad Gateway választ ad a szolgáltató hibaüzenetével.

Küldemények lemondása

Küldemény lemondásához használd a DELETE /api/v1/shipments/{id} végpontot. Ez meghívja a logisztikai szolgáltató API-ját a megbízás lemondásához, és cancelled státuszra frissíti a küldeményt.
A küldemények a felvétel után nem mondhatók le. A már in_transit, delivered vagy fault státuszú küldemény lemondására tett kísérlet 409 Conflict választ ad. A már cancelled státuszú küldemény lemondása nem végez műveletet, és 200 kóddal visszaadja a küldeményt – lásd: Idempotencia.
A logisztikai szolgáltató saját okokból is elutasíthatja a lemondást (például ha lejárt a lemondási határidő). Ilyenkor az API 502 Bad Gateway választ ad a szolgáltató hibaüzenetével és hibakódjával.

Visszaküldési címkék

A DHL visszaküldési címke a kimenő megbízás része. A DHL önmagában nem tudja lemondani a címkét, ezért a visszaküldési címkét követő sor lemondása 409 Conflict választ ad. Ehelyett mondd le a kimenő csomagot, amíg pending státuszú. Ez a címkét is lemondja vele együtt: a kimenő csomag minden pending státuszú visszaküldési sora cancelled lesz, és kap egy RETURN_LEG_CANCELLED bejegyzést a status_updates mezőjébe. A páciens által már feladott visszaküldési csomag továbbhalad. Miután a kimenő csomag elindult, a címke érvényes marad, az Aniva pedig manuálisan zárja le a visszaküldési sort.

A küldemények hivatkozási azonosítói

Minden küldeménynek van egy 11 karakteres hivatkozási azonosítója: egy betű, a dátum és négy karakter, {letter}YYMMDDXXXX (például P2611194821). A betű azt jelzi, hogy mihez tartozik a küldemény, soha nem az irányát: Egy 2026. november 20. és 22. közötti küldemény megtartja a szóval kezdődő azonosítóját: API, MAN, AUTO vagy KIT (például AUTO261121UWKX). Mindkét formátum érvényes marad. Ne ellenőrizd az azonosító hosszát vagy első betűjét. Használd az azonosítót a küldemény lekérdezéséhez, frissítéséhez vagy lemondásához.

Küldeménycímek

A küldemény válaszában található origin és destination mezők feloldott címobjektumokat tartalmaznak a következő szerkezettel:
Rendelői csomagnál az origin címet a létrehozáskor megadott vizsgálati helyszín alapján oldjuk fel, a destination pedig a destination_lab mezőben megnevezett laboratórium. Otthoni tesztcsomagnál a páciens szállítási címe a készlet destination címe és a minta visszaküldésének origin címe; a készlet origin címe a csomagolást végző telephely. A cím nem tartalmaz location_id mezőt – egy rendelői csomagot a hozzá kapcsolt időpont alapján tudsz összepárosítani.

Felvételi időablak

A küldemény válaszában található pickup mező az ütemezett futárfelvételi időablakot tartalmazza. Ez magában foglalja a from és till időbélyegeket UTC időpontként (ISO 8601 formátumban, Z utótaggal, pl. 2026-04-15T07:00:00Z), valamint egy timezone szöveget (a felvételi helyszín IANA időzónája). A létrehozáskor vagy módosításkor küldött helyi idő szerinti pickup_date / pickup_time_* értékeket ezen időzóna alapján oldjuk fel ezekre az abszolút időpontokra – a timezone segítségével jelenítheted meg újra a from / till értékeket a felvételi helyszín helyi idejében. A mező értéke null, ha nincs ütemezve felvételi időablak.

Státuszfrissítések naplója

Minden küldemény tartalmaz egy status_updates tömböt – a logisztikai szolgáltató által jelentett összes életciklus-eseményt, a legrégebbitől kezdve. Minden bejegyzés a következőket tartalmazza:
  • state – az esemény a küldemény státuszai szerint (pending, in_transit, delivered, fault), így a futárszolgálat kódjainak ismerete nélkül is követheted az idővonalat. null, ha az esemény nem hordoz állapotot (címkelétrehozás, a futárszolgálat információ nélküli szkennelése, a mező bevezetése előtt rögzített bejegyzések). Soha nem cancelled – a lemondás tőlünk származik, nem futárszolgálati esemény.
  • code – a futárszolgálat saját státuszkódja (a GO! GO10, GO90, GOY001, illetve a DHL VA, ZF, LA, ZU kódjai). null, ha a futárszolgálat nem adott meg ilyet. A status nyelvi fordításaitól függetlenül változatlan marad.
  • detail_code – a futárszolgálat részletesebb kódja, ahol létezik ilyen: a DHL statusDetailed értéke, pl. CNRFC_NRQRD_ZF (postára irányítva), HLDCC_SERPT_LA (ott átvételre kész), DLVRD_SERPT_ZU (átvéve). Minden más esetben null.
  • status – a futárszolgálat ember által olvasható felirata (pl. "Shipment picked up", "Die Sendung wurde abgeholt.").
  • description – a kód magyarázata vagy a futárszolgálat hosszabb mondata. null, ha egyik sincs.
  • location – a szkennelés helye a futárszolgálat megnevezése szerint: egy GO! depó, egy DHL város. Szabad szöveg, nem koordináta.
  • time – az esemény ISO 8601 időbélyege a futárszolgálat jelentése szerint (időeltolással).
Amikor a futárszolgálat visszaküldi a csomagot a feladónak, az idővonal kap egy bejegyzést RETURNED_TO_SENDER code értékkel. Ennek status mezője tartalmazza a futárszolgálat indokát. A küldemény ezután fault státuszban marad, akkor is, miután a futárszolgálat visszakézbesíti nekünk a csomagot. A lista üres lehet, ha a futárszolgálat még nem jelentett eseményeket. Az irányadó aktuális állapothoz a legfelső szintű status mezőt használd. Ez egyirányúan halad – pending státuszból in_transit, majd delivered felé –, és a fault kerül rá, amíg a legújabb esemény hibát jelez; a futárszolgálatok nem fontossági sorrendbe rendezik az eseményeiket (a DHL például egy pre-transit kódú átirányítási értesítést fűz az átadási szkennelés után), így a legújabb bejegyzés önmagában nem mutatja meg, hol tart a csomag.

Példa küldeményre

Példa otthoni tesztcsomagokra

A GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-… hívás párban adja vissza a pácienshez tartó készletet és a visszafelé tartó mintát:
A visszaküldési sor a visszaküldési címke kinyomtatásának pillanatától létezik, és pending marad, amíg a páciens fel nem adja a mintát – ez a valós állapot, nem hiányosság.