Ugrás a fő tartalomhoz
Az otthoni tesztkészlet-rendelés egy postán küldött, otthon elvégezhető tesztkészletet juttat el a pácienshez. Az Aniva kiszállítja a készletet, a páciens otthon maga veszi le a mintát, majd visszaküldi postán. Ez eltér az időponttól, amely egy fizikai vizsgálati helyszínen, egészségügyi szakember által végzett vénás vérvétel.
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

string
kötelező
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.
string
kötelező
Annak a profilnak az UUID-je, amelyhez ez az otthoni tesztkészlet-rendelés tartozik.
string
kötelező
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.
object
kötelező
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.
string
kötelező
Az otthoni tesztkészlet-rendelés létrehozásának ISO 8601 időbélyege.
string
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.
object
A páciens teljes profilobjektuma, minden otthoni tesztkészlet-rendelés válaszába beágyazva.
object[]
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.
object[]
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.
string
Az az otthoni tesztkészlet-rendelés, amelyet ez helyettesít, ha cserekészletről van szó. Normál rendelésnél null.
string
Egy mondatban megadva, miért küldték a cserekészletet. Normál rendelésnél null.
string[]
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.
object
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.
string
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.
string
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.
object[]
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

Az, hogy mi jön vissza, a tesztkészlettől függ. Egy vértesztkészlet két szállítmányként jelenik meg, amint az Aniva becsomagolta: az Anivától a pácienshez menő csomag, valamint a pácienstől a laboratóriumba menő (a 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.
Egy otthoni tesztkészlet-rendelés összetétele csak pending állapotban módosítható. Amint a rendelés dispatched (vagy későbbi – activated/cancelled) állapotba kerül, a panelcserék és a /biomarkers végpontok 409 Conflict hibát adnak vissza: a fizikai tesztkészletet a kiválasztott panel alapján csomagolják össze, így a tartalma abban a pillanatban rögzül, amikor elindul a pácienshez. Ha mégis módosítanod kell a vizsgálatokat egy már zárolt rendelésen, vedd fel közvetlenül a kapcsolatot az Anivával – ez általában még lehetséges, és elvégezzük helyetted a módosítást, hogy a tesztkészlet tartalma összhangban maradjon. Ha a tesztkészletet már használták, és nem tudott eredményeket adni, rendelj helyette cserekészletet.

Otthoni tesztkészlet-rendelések listázása

Kérd le az API-kulcsoddal elérhető összes otthoni tesztkészlet-rendelést:
Opcionálisan add meg a ?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:
Add meg a 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:
A cserekészlet egy új rendelés új laborkóddal, akkor is, ha az első tesztkészletet soha nem aktiválták: a laboratóriumnak új kérőlapra van szüksége, és két, ugyanazon kód alatti mintát nem lehet megkülönböztetni. Mindkét rendelés olvasható marad, a 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.
Tesztkészletenként egyszerre csak egy cserekészlet lehet úton – amíg egy cserekészlet 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:
Csak azokat a mezőket add meg, amelyeket módosítani szeretnél. A 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:
Ez az otthoni tesztkészlet-rendelés állapotát 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ég pending szerepel.
  • 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ó.
A hibával visszatérő lemondás pontosan úgy hagyja a rendelést, ahogy volt, így a 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:
Add meg az 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 egy individual_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):
Biomarkerek eltávolítása (idempotens — a nem csatolt azonosítót figyelmen kívül hagyja):
Mindkét végpont egy 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:
A válasz a megérkezett eredmények mellett a tervezett vizsgálatokat is tartalmazza (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.

Példa otthoni tesztkészlet-rendelésre