Egyetlen lista, szűrve
AGET /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, adestinationmezőből olvasható ki.booked_by— ki nyomtatta a címkét:anivavagyexternal. Csak azanivaszállítmányoknál használható a Frissítés és a Lemondás; azexternalcsomag ugyanebben a listában követhető nyomon, de mindkettőre501kóddal tér vissza.
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 ahome_kit_orderscsak 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
403kó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 asynced_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ásilocation_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óappointmentstömbként; - az időponton egy
{ id, added_at }elemekből állóshipmentstömbként.
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. Apickup_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
APATCH /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.
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 aDELETE /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 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ása409 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:
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 egystatus_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 nemcancelled– 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 DHLVA,ZF,LA,ZUkódjai).null, ha a futárszolgálat nem adott meg ilyet. Astatusnyelvi 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 DHLstatusDetailedé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 esetbennull.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).
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
AGET /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:
pending marad, amíg a páciens fel nem adja a mintát – ez a valós állapot, nem hiányosság.