Az otthoni tesztkészlet-rendelések végpontjaihoz a
home_kit_orders_view (olvasás) vagy a home_kit_orders_manage
(írás) jogosultsági kör szükséges. Az Aktiválás a szűkebb
home_kit_orders_activate jogosultsági kört is elfogadja. Az Eredmények lekérése és az
Eredmények küldése e-mailben emellett a results_view jogosultsági kört is igényli — a laboreredmények
és dokumentumok mindig ehhez vannak kötve.Mezők
Az Aniva által automatikusan generált UUID. Ezzel módosíthatod a rendelést, cserélheted benne a panelt, aktiválhatod, lemondhatod
és lekérheted az eredményeket.
Aktuális életciklus-állapot. Lehetséges értékei:
pending, dispatched, activated vagy cancelled. Lásd az alábbi
Életciklus részt. A laboreredmények elkészültségének részletesebb állapota (in_progress vagy completed) az
Eredmények lekérése végpontból állapítható meg.A cím, ahová a készletet postázzuk — kétféle formában adható meg: vagy egy ismert vizsgálati helyszínre
hivatkozó
{location_id}, vagy közvetlen címmezők (name, street, city, postal_code,
country_code; a company_name / house_number / address_line_2 / state / phone / email
mezők opcionálisak — ugyanaz a mezőkészlet, mint a helyszínek API-jában). Pontosan az egyiket add meg — helyszínhivatkozást
vagy közvetlen címet, mindkettőt ne.Packstation vagy Postfiliale (csak Németországban): állítsd a
street mezőt Packstation vagy Postfiliale értékre,
a house_number mezőt a háromjegyű állomásszámra, az address_line_2 mezőt pedig a címzett DHL
Postnummer azonosítójára (6–10 számjegy, szóköz engedélyezett). Postnummer nélkül a csomag nem foglalható le.
A Postfach nem támogatott.A legutóbbi frissítés ISO 8601 időbélyege. Null, ha az otthoni tesztkészlet-rendelést még soha nem frissítették.
Az otthoni tesztkészlet-rendeléshez csatolt panel — mindig pontosan egy
{ panel_id, added_at } elem,
mivel egy otthoni tesztkészlet 1:1 arányban felel meg egy fizikai tesztkészlet-terméknek. A panel_id értéket a
Panelek listázása végponttal vetheted össze.Az otthoni tesztkészlet-rendeléshez a panelen kívül csatolt biomarkerek. Minden elem egy
{ biomarker_id, added_at } objektum. Az egyes biomarker_id értékeket a
Biomarkerek listázása végponttal vetheted össze home_kit=true paraméterrel. Normál rendelésnél ezek a panelen felüli, egyedileg választható tesztek;
cserekészletnél pedig ezeket futtatja újra a laboratórium.Az az otthoni tesztkészlet-rendelés, amelyet ez helyettesít, ha cserekészletről van szó. Normál rendelésnél
null.Kisbetűs e-mail-címek, amelyek mindegyike kap egy e-mailt, amint minden laboreredmény végleges. Mindig jelen van —
üres, ha ki van kapcsolva. A Létrehozás vagy a
Frissítés végponton állíthatod be. Lásd:
Eredmények elkészültéről szóló e-mailek.
Saját kulcs-érték párok, amelyeket az Aniva szó szerint visszaad, és soha nem értelmez. Olvasáskor mindig
jelen van —
{} értékkel, ha nem adtál meg egyet sem. Legfeljebb 20 kulcs; a kulcsok illeszkednek a [A-Za-z0-9_-] mintára, és legfeljebb 40
karakter hosszúak; az értékek szöveg, szám vagy logikai érték típusúak lehetnek, a szövegek legfeljebb 500 karakteresek; szerializálva összesen legfeljebb 16 384
bájt. Az aniva_ előtaggal kezdődő kulcsok fenntartottak. A
Frissítés végponton a metaadatok egyesülnek: a kihagyott kulcsok megmaradnak, a
null értékkel küldött kulcs törlődik, a {} pedig mindent töröl. Az ellenőrzés mindent vagy semmit alapon működik. Soha ne tegyél
személyes vagy klinikai adatot a metadata mezőbe — nem páciensadatként kezeljük.A laboratóriumi mintakód. Egy kód, három szerep: ez alatt érkeznek a laboreredmények, ez van rányomtatva
a fizikai készletre, és ezt olvassa le a páciens a dobozról aktiválási kódként. A készlet becsomagolásakor
rendeljük hozzá —
null, amíg a rendelés pending állapotban van, kivéve miután az Aniva újraküld egy készletet (lásd:
Életciklus). Mindig csak olvasható. Egy kézben lévő készlethez a
GET /api/v1/home-kit-orders?lab_code=… kéréssel keresheted meg a hozzá tartozó rendelést.Az Aktiválás végponton jelentett mintavételi időbélyeg — amikor
a páciens ténylegesen levette a mintát, UTC időpontként.
null, amíg a készletet nem aktiválták.
Ez a mintavételi időpont szerepel a laborjelentésen is.Az ehhez a rendeléshez kapcsolt csomagok a legrégebben kapcsolttól kezdve, egyenként
{ id, added_at } formában — a pácienshez
úton lévő készlet, valamint a követett visszaküldésű készleteknél a laboratóriumba visszafelé tartó
minta, amely abban a pillanatban megjelenik, amikor kinyomtatják a címkéket. Üres, amíg a rendelés
pending állapotban van, kivéve miután az Aniva újraküld egy készletet. A teljes csomagadatokat
egy hívással kérheted le a GET /api/v1/shipments?home_kit_order_id={id} végponton — lásd:
Szállítmányok.Életciklus
Az otthoni tesztkészlet-rendeléseknek négy életciklus-állapota van:
Amikor az Aniva újraküld egy elveszett tesztkészletet, a rendelés visszakerül
pending állapotba, de megtartja a lab_code kódját és a
korábbi csomagjait a shipments mezőben. Az új tesztkészlet ugyanezt a kódot kapja. Az új dobozba
egy felhasználatlan visszaküldési címke kerül. Csak az Aniva végzi el ezt a két lépést; az API nem kínálja őket. Mindkét lépés egy
home_kit_order.pending vagy home_kit_order.cancelled webhookot küld.
Az otthoni tesztkészlet-rendelés állapotrendszere szándékosan nagy vonalakú. A pácienshez és a pácienstől
történő szállítás haladását a rendelés szállítmányai követik – a
dispatched azt jelenti, hogy a tesztkészlet
kapott címkét és laborkódot, nem azt, hogy már el is indult; a kimenő szállítmány status mezője mutatja meg,
elindult-e. A laboreredmények feldolgozása a beküldéseknél zajlik. A laboreredmények elkészültsége (in_progress vagy
completed) az Eredmények lekérése végponton érhető el – a felső szintű
status mező mindaddig in_progress, amíg az összes beküldés le nem zárul, utána completed – vagy fault, ha
minden beküldés jelentés nélkül meghiúsult.A csomagok nyomon követése
destination mezője a laboratórium), amelyeket a paired_with kapcsol össze. A
visszaküldési csomag pending állapotban marad – már ismert nyomkövetési számmal –, amíg a páciens fel nem
adja. A bélmikrobiom-tesztkészlet egy szállítmányként jelenik meg: a páciensnek küldött tesztkészletként. A visszaküldési borítékja
előre bérmentesített és nem nyomon követett, így a visszaútra nincs foglalás. A booked_by mutatja meg, ki foglalta a
címkét: "aniva" vagy "external". Itt csak az "aniva" csomag módosítható, és a címke kinyomtatása után már csak a
notes mezője. Minden csomag tartalmazza a futárszolgálat teljes status_updates listáját,
beleértve a DHL detail_code kódját a postahivatalba történő átirányításhoz.
A szállítmányon szereplő home_kit_orders csak a hozzáférési kontextusodba tartozó rendeléseket listázza. Lásd:
Hozzáférés.
Otthoni tesztkészlet-rendelések listázása
Kérd le az API-kulcsoddal elérhető összes otthoni tesztkészlet-rendelést:?profile_id={uuid} paramétert egy adott profilra való szűréshez, vagy a ?lab_code={code} paramétert, hogy
egy kézben tartott fizikai tesztkészletet visszakeress a rendeléséhez – ez az aktiválási folyamat természetes első lépése.
Otthoni tesztkészlet-rendelés létrehozása
Rendelj otthoni tesztkészletet egy páciensprofilhoz:profile_id, a delivery_address és egyetlen panel_id értékét. A rendelés pending állapotban jön létre.
Adj meg egy opcionális Idempotency-Key fejlécet, hogy egy újrapróbálkozás ne rendeljen második tesztkészletet – lásd: Idempotencia.
Pontosan egy panel, mert egy otthoni tesztkészlet 1:1 arányban felel meg egy fizikai tesztkészlet-terméknek – a panel maga a tesztkészlet. Csak azok a panelek rendelhetők, amelyeket az Aniva otthoni tesztkészletként állított be; minden más panelt 422 hibával elutasít a rendszer. Létrehozáskor kötelező megadni, mert a rendelés azonnal bekerül a csomagolási sorba, és a csomagolás rögtön elindulhat. Amíg a rendelés pending állapotban van, a panelt lecserélheted a Módosítás végponton keresztül.
Ha második tesztkészletet szeretnél küldeni egy olyan helyett, amely nem tudott eredményeket adni, panelválasztás helyett add meg a replaces_home_kit_order_id mezőt – lásd: Cserekészletek.
Cserekészletek
Előfordul, hogy egy tesztkészlet nem tud eredményeket adni: a páciens nem tudta megtölteni a csövet, a minta túl kevés anyaggal érkezett be, a laboratórium nem tudta elemezni egy részét. Rendelj helyette cserekészletet:replaces_home_kit_order_id mezővel összekapcsolva.
A lecserélt rendelés érintetlen marad. Megtartja az állapotát, a laborkódját és a már alatta rögzített eredményeket, így ha a páciens mégis feladja az első tesztkészletet, megkapja mindazt, amit a laboratórium ki tud olvasni belőle.
A panel öröklődik. Hagyd ki a panel_id mezőt, és a cserekészlet annak a rendelésnek a paneljét kapja, amelyet helyettesít – ezt vásárolta meg a páciens, és ilyen a doboz arculata is. Másik panelt csak teljes panel cseréjekor küldj; egy panel és egy marker-részhalmaz együttes megadását a rendszer 422 hibával elutasítja, mert egy részhalmaz csak annak a panelnek a keretében értelmezhető, amelyből kiválasztották. A cserekészlet panelje utólag sem cserélhető le.
Te választod ki, mit futtassanak újra. Küldd el a biomarker_ids mezőben a sikertelen markereket, és a laboratórium csak azokat futtatja újra, így a tesztkészlet csak a hozzájuk szükséges csövekkel indul útnak. Hagyd ki a mezőt a teljes panel újrafuttatásához – ez a jó választás, ha semmit sem tudtak elemezni. Ehhez nincs szükség külön scope-ra: a páciens által már kifizetett markerek újrafuttatása nem à la carte választás. Ezeket a markereket utólag nem lehet eltávolítani, mert ezek teszik ki a teljes kérőlapot.
A markereket a panel csoportjai szerint futtatják újra, nem egyenként. Ha egy csoport egyetlen markerét megadod,
az a teljes csoportot újrafuttatja, mert nem adható le olyan laboratóriumi rendelés, amely többet jelent a kértnél.
Egyetlen marker cseréje ezért egynél több eredménnyel is visszatérhet, és
a csövek száma is nagyobb lehet annál, mint amit a markerlista sejtet.
pending vagy dispatched állapotban van, az ugyanahhoz a rendeléshez indított második létrehozás 409 hibát ad vissza, megnevezve azt. Az eredmények a cserekészlet saját lab_code kódja alatt, a saját Eredmények lekérése végpontján érkeznek meg.
A cserekészlet nem a soha meg nem érkezett csomagok kezelésére való. Inkább szólj az Anivának: az ugyanannak a rendelésnek az újraküldése ugyanazzal a laborkóddal, nem pedig új rendelés.
Otthoni tesztkészlet-rendelés módosítása
Módosítsd a szállítási címet, cseréld le a panelt, frissítsd a metaadataidat, vagy cseréld le az eredményértesítő e-mail-címeket:panel_id lecseréli a csatolt panelt – mivel tesztkészletenként pontosan egy panel van, a csere az egyetlen értelmes panelművelet, ezért nincsenek panel hozzáadására vagy eltávolítására szolgáló végpontok. A cím és a panel csak pending állapotban módosítható; a metadata a rendelés teljes élettartama alatt írható marad. A results_ready_emails mindaddig írható marad, amíg a rendelés cancelled állapotba nem kerül.
Otthoni tesztkészlet-rendelés lemondása
Mondj le egy már nem szükséges otthoni tesztkészlet-rendelést:cancelled értékre állítja. A válasz a lemondott otthoni tesztkészlet-rendelést adja vissza.
Csak pending állapotú rendelés mondható le. A dispatched állapottól kezdve a tesztkészlet már be van csomagolva és fel van címkézve – nincs automatikus visszahívás –, így a hívás 409 hibát ad vissza. Ha egy már feladott tesztkészletet meg kell állítani, vedd fel közvetlenül a kapcsolatot az Anivával.
Egy olyan pending rendelés lemondása, amelynek tesztkészletét már megrendelték a logisztikai partnertől, ott is lemondja azt, és a hívás csak akkor sikeres, ha a logisztikai partner ezt elfogadja:
409– a tesztkészletet már becsomagolták és felcímkézték, így már nem hívható vissza, még akkor sem, ha a rendelésnél mégpendingszerepel.502– a logisztikai partner elutasította a lemondást (a hiba tartalmazza az indokát), vagy nem volt elérhető. Semmi sem változott – a rendelés továbbra is él, és újra lemondható.
200 az egyetlen megerősítés arra, hogy nem érkezik tesztkészlet.
Egy már cancelled állapotú rendelés lemondása ugyanezt a 200 választ adja vissza, függetlenül attól, milyen állapotból mondták le.
Otthoni tesztkészlet-rendelés aktiválása
Amikor a páciens levette a mintát, jelentsd:activated_at mezőt – azt a pillanatot UTC időpontként, amikor a páciens ténylegesen levette a mintát. Ez lesz a laborleleten szereplő mintavételi idő, ezért a valós mintavételi pillanatot küldd, ne a saját feldolgozási idődet. Az aktiválás végleges: a rendelés activated állapotba lép, és többé nem mondható le és nem módosítható. Ez a Vérvétel megerősítése végpont otthoni tesztkészletes megfelelője, vonalkód nélkül – a tesztkészlet kódját csomagoláskor helyezik rá, így neked sosem kell ismerned. A rendelésnek eddigre már rendelkeznie kell lab_code kóddal; e nélkül a hívás 409 hibát ad vissza.
Az aktiválás adja le a laboratóriumi rendelést is: a tesztkészlet paneljét a lab_code kódja alatt megrendeljük a laboratóriumban, így a visszaküldött mintát már várják, és az eredmények csatolódnak, ahogy a laboratórium jelenti őket. Ez a válasz után fut le, és a laboratóriumi oldali problémát az Aniva kezeli ahelyett, hogy a kérésedben jelenne meg.
Egyedi biomarkerek
A panelen kívül egyedi biomarkereket is csatolhatsz egy otthoni tesztkészlet-rendeléshez à la carte vizsgálatokként. Ez akkor hasznos, ha a tesztkészleten felül testreszabott választékot szeretnél. A csatolt biomarkerek az otthoni tesztkészlet-rendelés válaszában egyindividual_biomarkers tömbként jelennek meg (a panels mellett, azzal azonos szinten).
Mindkét biomarker-végponthoz a home_kit_orders_manage mellett a home_kit_orders_individual_biomarker_selection jogosultsági scope is szükséges — az otthoni tesztkészleteket panelenként lehet rendelni, ezért az egyedi markereket partnerenként engedélyezzük. Szólj az Anivának, ha az integrációdnak szüksége van rá.
Biomarkerek hozzáadása (idempotens – a már csatolt biomarkerek megmaradnak):
biomarker_ids tömböt vár. A biomarker-azonosítók lekéréséhez használd a Biomarkerek listázása végpontot a home_kit=true paraméterrel. A biomarkerek csak addig módosíthatók, amíg a tesztkészlet pending állapotban van (lásd: Életciklus).
Laboreredmények lekérése
Miután a labor feldolgozta a visszaküldött mintát, lekérheted a klinikai és genetikai eredményeket:planned állapottal), így követheted, mi van még hátra. Az eredmények a rendelés lab_code kódja alatt gyűlnek, és markerenként érkeznek meg, ahogy a labor elemzi őket, ezért a részleges válasz teljesen normális. A legfelső szintű status mező a végleges leletig in_progress, utána completed (vagy fault, ha minden laborrendelés eredmény nélkül meghiúsult) — ebből tudod megállapítani, hogy elkészült-e az otthoni tesztkészlet-rendelés laborfeldolgozása. A home_kit_order.results.completed webhook értesít, amikor ez megtörténik, így nem kell folyamatosan lekérdezned. A laborleletek PDF-jeire a documents tömb hivatkozik — a letöltésükhöz használd a GET /api/v1/documents/{id} végpontot.