Pāriet uz galveno saturu
Mājas testa komplekta pasūtījums nosūta pacientam pa pastu mājās lietojamu testa komplektu. Aniva izsūta komplektu, pacients pats mājās paņem paraugu un nosūta to atpakaļ pa pastu. Tas atšķiras no pieraksta, kas ir venozo asiņu paņemšana fiziskā testēšanas vietā, ko veic veselības aprūpes speciālists.
Mājas testa komplekta pasūtījumu galapunktiem nepieciešams home_kit_orders_view (lasīšana) vai home_kit_orders_manage (rakstīšana) piekļuves apjoms. Aktivizēt pieņem arī šaurāko home_kit_orders_activate piekļuves apjomu. Iegūt rezultātus un Nosūtīt rezultātus e-pastā papildus prasa results_view — laboratorijas rezultāti un dokumenti vienmēr ir aizsargāti ar to.

Lauki

string
obligāts
Aniva automātiski ģenerēts UUID. Izmanto to, lai atjauninātu pasūtījumu, nomainītu tā paneli, aktivizētu to, atceltu to un iegūtu rezultātus.
string
obligāts
Profila UUID, kuram pieder šis mājas testa komplekta pasūtījums.
string
obligāts
Pašreizējais dzīves cikla statuss. Viens no: pending, dispatched, activated vai cancelled. Skati sadaļu Dzīves cikls zemāk. Detalizēts laboratorijas rezultātu izpildes statuss (in_progress pret completed) tiek iegūts no Iegūt rezultātus.
object
obligāts
Adrese, uz kuru nosūtīt komplektu — viens no diviem variantiem: vai nu {location_id}, kas atsaucas uz zināmu testēšanas vietu, vai tiešie adreses lauki (name, street, city, postal_code, country_code; company_name / house_number / address_line_2 / state / phone / email ir neobligāti — tie paši nosaukumi kā atrašanās vietu API). Norādi tieši vienu — atsauci uz atrašanās vietu vai tiešo adresi, nevis abus.
Packstation vai Postfiliale (tikai Vācijā): laukā street norādi Packstation vai Postfiliale, laukā house_number — trīsciparu stacijas numuru, bet laukā address_line_2 — saņēmēja DHL Postnummer (6–10 cipari, atstarpes atļautas). Bez Postnummer sūtījumu nevar noformēt. Postfach netiek atbalstīts.
string
obligāts
ISO 8601 laikspiedols, kad tika izveidots mājas testa komplekta pasūtījums.
string
Pēdējās atjaunināšanas ISO 8601 laika zīmogs. Null, ja mājas testa komplekta pasūtījums nekad nav ticis atjaunināts.
object
Pilns pacienta profila objekts, kas iekļauts katrā mājas testa komplekta pasūtījuma atbildē.
object[]
Mājas testa komplekta pasūtījumam piesaistītais panelis — vienmēr tieši viens ieraksts { panel_id, added_at }, jo mājas testa komplekts atbilst 1:1 fiziskam komplekta produktam. Salīdzini panel_id ar Paneļu sarakstu.
object[]
Biomarķieri, kas piesaistīti mājas testa komplekta pasūtījumam ārpus tā paneļa. Katrs ieraksts ir { biomarker_id, added_at }. Salīdzini katru biomarker_id ar Biomarķieru sarakstu, norādot home_kit=true. Parastā pasūtījumā tie ir atsevišķi pievienoti testi papildus panelim; aizstāšanas komplektā tie ir testi, ko laboratorija veic atkārtoti.
string
Mājas testa komplekta pasūtījums, ko šis aizstāj, ja tas ir aizstāšanas komplekts. Parastam pasūtījumam vērtība ir null.
string
Kāpēc tika nosūtīts aizstāšanas komplekts — vienā teikumā. Parastam pasūtījumam vērtība ir null.
string[]
Adreses mazajiem burtiem — katra saņem vienu e-pastu, tiklīdz visi laboratorijas rezultāti ir galīgi. Vienmēr ir iekļauts — tukšs, kad izslēgts. Iestati to pieprasījumā Izveidot vai Atjaunināt. Skati E-pasti par gataviem rezultātiem.
object
Tavi atslēgas/vērtības pāri, kas tiek atgriezti bez izmaiņām un kurus Aniva nekad neinterpretē. Vienmēr iekļauts lasīšanas atbildē — {}, ja neesi iestatījis nevienu. Ne vairāk kā 20 atslēgas; atslēgas atbilst [A-Za-z0-9_-] un ir ne garākas par 40 rakstzīmēm; vērtības ir virkne, skaitlis vai būla vērtība, virknēm nepārsniedzot 500 rakstzīmes; kopā līdz 16 384 baitiem serializētā veidā. Atslēgas, kas sākas ar aniva_, ir rezervētas. Pieprasījumā Atjaunināt metadati tiek apvienoti: izlaistās atslēgas saglabājas, atslēga ar vērtību null tiek dzēsta, bet {} notīra visu. Validācija darbojas pēc principa viss vai nekas. Nekad neievieto personas vai klīniskos datus laukā metadata — tie netiek apstrādāti kā pacienta dati.
string
Laboratorijas parauga kods. Viens kods, trīs lomas: ar to tiek iesniegti laboratorijas rezultāti, tas ir uzdrukāts uz fiziskā komplekta, un pacients to nolasa no kastītes kā aktivizācijas kodu. Piešķirts, kad komplekts tiek iepakots — null, kamēr pasūtījuma statuss ir pending, izņemot pēc tam, kad Aniva atkārtoti izsūta komplektu (skati Dzīves cikls). Vienmēr tikai lasāms. Atrodi pasūtījumu pēc rokās esošā komplekta ar GET /api/v1/home-kit-orders?lab_code=….
string
Parauga paņemšanas laika zīmogs, kas paziņots ar Aktivizēt — brīdis UTC laikā, kad pacients faktiski paņēma paraugu. null, līdz komplekts tiek aktivizēts. Šis ir parauga paņemšanas laiks, kas tiek norādīts laboratorijas pārskatā.
object[]
Ar šo pasūtījumu saistītie sūtījumi, sākot ar vissenāk piesaistīto, katrs formātā { id, added_at } — komplekts ceļā pie pacienta un, komplektiem ar izsekojamu atpakaļceļu, paraugs ceļā atpakaļ uz laboratoriju, parādoties brīdī, kad tiek izdrukātas uzlīmes. Tukšs, kamēr pasūtījuma statuss ir pending, izņemot pēc tam, kad Aniva atkārtoti izsūta komplektu. Iegūsti pilnus sūtījumu datus vienā pieprasījumā ar GET /api/v1/shipments?home_kit_order_id={id} — skati Sūtījumi.

Dzīves cikls

Mājas testa komplekta pasūtījumiem ir četri dzīves cikla stāvokļi:
Kad Aniva atkārtoti nosūta nozaudētu komplektu, pasūtījums atgriežas statusā pending, bet saglabā savu lab_code un iepriekšējās pakas laukā shipments. Jaunajam komplektam ir tas pats kods. Jaunajā kastē tiek ielikta neizmantota atgriešanas uzlīme. Tikai Aniva veic šīs divas pārejas; API tās nepiedāvā. Katra pāreja nosūta home_kit_order.pending vai home_kit_order.cancelled webhook paziņojumu.
Mājas testa komplekta pasūtījuma statusu sistēma apzināti ir vispārīga. Piegādes gaita pie pacienta un no viņa tiek izsekota pasūtījuma sūtījumos — dispatched nozīmē, ka komplektam ir uzlīme un laboratorijas kods, nevis ka tas jau ir ceļā; to, vai tā ir, rāda izejošā sūtījuma status. Laboratorijas rezultātu apstrāde notiek iesniegumos. Laboratorijas rezultātu gatavība (in_progress vai completed) ir pieejama ar Iegūt rezultātus — augšējā līmeņa lauks status ir in_progress, līdz visi iesniegumi ir noslēgti, tad completed — vai fault, ja visi iesniegumi beidzās bez rezultātu iesniegšanas.

Paku izsekošana

Tas, kas tiek atgriezts, ir atkarīgs no komplekta. Asins analīžu komplekts, tiklīdz Aniva to ir iepakojusi, sastāv no diviem sūtījumiem: paka no Aniva pacientam un paka no pacienta laboratorijai (tās destination ir laboratorija), kas savienotas ar paired_with. Atgriešanas paka paliek statusā pending — ar jau zināmu izsekošanas numuru —, līdz pacients to nosūta. Zarnu mikrobioma komplekts sastāv no viena sūtījuma: komplekts pacientam. Tā atgriešanas aploksne ir priekšapmaksāta un netiek izsekota, tāpēc atpakaļceļam nekas netiek rezervēts. booked_by norāda, kas rezervēja uzlīmi: "aniva" vai "external". Šeit var mainīt tikai "aniva" paku, un pēc uzlīmes izdrukāšanas — tikai tās notes. Katrai pakai ir pievienoti pilni pārvadātāja status_updates, tostarp DHL detail_code novirzīšanai uz pasta nodaļu. home_kit_orders sūtījumā uzskaita tikai tos pasūtījumus, kas ir tavā piekļuves kontekstā. Skatīt Piekļuve.
Mājas testa komplekta pasūtījuma sastāvu var mainīt tikai tad, kad tas ir statusā pending. Tiklīdz pasūtījums ir dispatched (vai vēlāk — activated/cancelled), paneļa maiņa un /biomarkers galapunkti atgriež 409 Conflict: fiziskais komplekts tiek iepakots atbilstoši izvēlētajam panelim, tāpēc tā saturs ir fiksēts brīdī, kad tas dodas pie pacienta. Ja tev tomēr jāmaina analīzes pasūtījumā, kas jau ir slēgts, sazinies ar Aniva tieši — parasti tas vēl ir iespējams, un mēs veiksim izmaiņas tavā vietā, lai komplekta saturs paliktu saskaņots. Ja komplekts jau ir izmantots un nevarēja sniegt rezultātus, tā vietā pasūti aizstāšanas komplektu.

Mājas testa komplektu pasūtījumu saraksts

Iegūsti visus mājas testa komplektu pasūtījumus, kas pieejami tavai API atslēgai:
Pēc izvēles padod ?profile_id={uuid}, lai filtrētu pēc konkrēta profila, vai ?lab_code={code}, lai rokās esošu fizisku komplektu sasaistītu ar tā pasūtījumu — tas ir loģisks pirmais solis aktivizēšanas plūsmā.

Mājas testa komplekta pasūtījuma izveide

Pieprasi mājas testa komplekta pasūtījumu pacienta profilam:
Padod profile_id, delivery_address un vienu panel_id. Pasūtījums tiek izveidots statusā pending. Pēc izvēles padod galveni Idempotency-Key, lai atkārtots mēģinājums nepasūtītu otru komplektu — skatīt Idempotence. Tieši vienu paneli, jo mājas testa komplekts atbilst 1:1 fiziskam komplekta produktam — panelis ir komplekts. Pasūtīt var tikai tos paneļus, kurus Aniva ir konfigurējusi kā mājas testa komplektus; jebkurš cits panelis tiek noraidīts ar 422. Tas ir obligāts izveides brīdī, jo pasūtījums uzreiz nonāk iepakošanas rindā un iepakošana var sākties nekavējoties. Kamēr pasūtījums ir statusā pending, tu vari nomainīt paneli, izmantojot Atjaunināt. Lai nosūtītu otru komplektu tā vietā, kurš nevarēja sniegt rezultātus, paneļa izvēles vietā padod replaces_home_kit_order_id — skatīt Aizstāšanas komplekti.

Aizvietošanas komplekti

Dažkārt komplekts nevar sniegt rezultātus: pacients nevarēja piepildīt stobriņu, paraugs pienāca ar pārāk mazu materiāla daudzumu vai laboratorija nevarēja analizēt daļu no tā. Pasūti tam aizstājēju:
Aizstājējs ir jauns pasūtījums ar jaunu laboratorijas kodu, arī tad, ja pirmais komplekts nekad netika aktivizēts: laboratorijai ir nepieciešams jauns nosūtījums, un divus paraugus ar vienu kodu nevar atšķirt. Abi pasūtījumi paliek lasāmi, savienoti ar replaces_home_kit_order_id. Aizstājamais pasūtījums netiek aiztikts. Tas saglabā savu statusu, laboratorijas kodu un visus rezultātus, kas tajā jau reģistrēti, tāpēc pacients, kurš tomēr nosūta pirmo komplektu, saņem visu, ko laboratorija no tā var nolasīt. Panelis tiek mantots. Nenorādi panel_id, un aizstājējs pārņems aizstājamā pasūtījuma paneli — to, ko pacients iegādājās un kā ir noformēta kaste. Sūti citu paneli tikai visa paneļa aizstāšanai; panelis kopā ar marķieru apakškopu tiek noraidīts ar 422, jo apakškopai ir nozīme tikai tajā panelī, no kura tā izvēlēta. Arī aizstājēja paneli vēlāk nevar nomainīt. Tu izvēlies, ko atkārtot. Nosūti biomarker_ids ar marķieriem, kas neizdevās, un laboratorija atkārtos tikai tos, tāpēc komplektā būs tikai tiem nepieciešamie stobriņi. Nenorādi to, lai atkārtotu visu paneli — tā ir pareizā izvēle, ja nekas vispār netika analizēts. Tam nav nepieciešams papildu scope: to marķieru atkārtošana, par kuriem pacients jau samaksāja, nav à-la-carte izvēle. Šos marķierus vēlāk nevar noņemt, jo tie veido visu nosūtījumu.
Marķieri tiek atkārtoti pa paneļa grupām, nevis pa vienam. Norādot vienu grupas marķieri, tiek atkārtota visa šī grupa, jo nevar veikt laboratorijas pasūtījumu, kas ziņo vairāk, nekā pieprasīts. Tāpēc viena marķiera aizstājējs var atgriezt vairāk nekā vienu rezultātu, un tā stobriņu skaits var būt lielāks, nekā liecina marķieru saraksts.
Vienam komplektam vienlaikus ceļā var būt tikai viens aizstājējs — kamēr aizstājējs ir statusā pending vai dispatched, otrs izveides pieprasījums tam pašam pasūtījumam atgriež 409, norādot esošo aizstājēju. Rezultāti pienāk ar aizstājēja paša lab_code, izmantojot tā Iegūt rezultātus. Aizstājējs nav paredzēts pakām, kas nekad nepienāca. Tā vietā sazinies ar Aniva: tas ir tā paša pasūtījuma atkārtots sūtījums ar to pašu laboratorijas kodu, nevis jauns pasūtījums.

Mājas testa komplekta pasūtījuma atjaunināšana

Maini piegādes adresi, nomaini paneli, atjaunini metadatus vai aizstāj e-pasta adreses paziņojumiem par gataviem rezultātiem:
Iekļauj tikai tos laukus, kurus vēlies mainīt. panel_id aizstāj pievienoto paneli — tā kā vienam komplektam ir tieši viens panelis, maiņa ir vienīgā jēgpilnā operācija ar paneli, tāpēc nav paneļu pievienošanas/noņemšanas galapunktu. Adresi un paneli var mainīt tikai statusā pending; metadata var rakstīt visā pasūtījuma dzīves ciklā. results_ready_emails var rakstīt, līdz pasūtījums ir cancelled.

Mājas testa komplekta pasūtījuma atcelšana

Atcel mājas testa komplekta pasūtījumu, kas vairs nav nepieciešams:
Tas iestata mājas testa komplekta pasūtījuma statusu uz cancelled. Atbildē tiek atgriezts atceltais mājas testa komplekta pasūtījums. Atcelt var tikai pasūtījumu statusā pending. Sākot no dispatched, komplekts ir iepakots un marķēts — automātiskas atsaukšanas nav — un izsaukums atgriež 409. Ja jāaptur komplekts, kas jau ir izsūtīts, sazinies ar Aniva tieši. Atceļot pending pasūtījumu, kura komplekts jau ir pasūtīts izpildes centrā, tas tiek atcelts arī tur, un izsaukums izdodas tikai tad, ja izpildes centrs to apstiprina:
  • 409 — komplekts jau tika iepakots un marķēts, tāpēc to vairs nevar atsaukt, lai gan pasūtījumam joprojām rādās pending.
  • 502 — izpildes centrs atteica atcelšanu (kļūdā ir norādīts tā iemesls) vai nebija sasniedzams. Nekas netika mainīts — pasūtījums joprojām ir aktīvs, un to var atcelt atkārtoti.
Atcelšana, kas atgriež kļūdu, atstāj pasūtījumu tieši tādu, kāds tas bija, tāpēc 200 ir vienīgais apstiprinājums, ka komplekts netiks sūtīts. Atceļot pasūtījumu, kas jau ir statusā cancelled, tiek atgriezts tas pats 200, neatkarīgi no statusa, no kura tas tika atcelts.

Mājas testa komplekta pasūtījuma aktivizēšana

Kad pacients ir paņēmis paraugu, paziņo par to:
Padod activated_at — brīdi, kad pacients faktiski paņēma paraugu, UTC formātā. Šis ir parauga paņemšanas laiks, kas parādīsies laboratorijas pārskatā, tāpēc sūti faktisko paņemšanas brīdi, nevis apstrādes laiku. Aktivizēšana ir galastāvoklis: pasūtījums pāriet uz activated, un to vairs nevar atcelt vai mainīt. Šis ir mājas testa komplekta ekvivalents Apstiprināt asins paņemšanu bez svītrkoda — komplekta kods tiek piešķirts iepakošanas laikā, tāpēc tev tas nekad nav jāzina. Līdz tam brīdim pasūtījumam jau jābūt lab_code; pasūtījums bez tā atgriež 409. Aktivizēšana arī veic laboratorijas pasūtījumu: komplekta panelis tiek pasūtīts laboratorijā ar tā lab_code, tāpēc atgrieztais paraugs tiek gaidīts un rezultāti tiek pievienoti, tiklīdz laboratorija tos iesniedz. Tas notiek pēc atbildes nosūtīšanas, un problēmas laboratorijas pusē risina Aniva, nevis tās tiek atgrieztas tavā pieprasījumā.

Atsevišķi biomarķieri

Mājas testa komplekta pasūtījumam vari pievienot atsevišķus biomarķierus kā à la carte analīzes ārpus paneļa. Tas ir noderīgi, ja papildus komplektam vēlies pielāgotu izvēli. Pievienotie biomarķieri mājas testa komplekta pasūtījuma atbildē parādās masīvā individual_biomarkers (līdzās panels). Abiem biomarķieru galapunktiem papildus home_kit_orders_manage nepieciešams home_kit_orders_individual_biomarker_selection atļaujas tvērums — mājas testa komplektus pasūta pa paneļiem, tāpēc atsevišķus marķierus ieslēdz katram partnerim atsevišķi. Jautā Aniva, ja tavai integrācijai tas ir nepieciešams. Pievieno biomarķierus (idempotenti — jau piesaistītie biomarķieri tiek saglabāti):
Noņemt biomarķierus (idempotenti — nepiesaistīts ID tiek ignorēts):
Abi galapunkti pieņem masīvu biomarker_ids. Izmanto Biomarķieru sarakstu ar home_kit=true, lai atrastu biomarķieru ID. Biomarķierus var mainīt tikai tad, kamēr komplektam ir statuss pending (sk. Dzīves cikls).

Laboratorijas rezultātu iegūšana

Kad laboratorija ir apstrādājusi atgriezto paraugu, izgūsti klīniskos un ģenētiskos rezultātus:
Atbildē līdzās saņemtajiem rezultātiem ir iekļauti plānotie testi (statuss planned), lai tu varētu sekot, kas vēl gaida izpildi. Rezultāti tiek pievienoti pasūtījuma lab_code un pienāk pa vienam marķierim, laboratorijai tos analizējot, tāpēc daļēji dati ir normāla parādība. Augstākā līmeņa lauks status līdz galīgajam pārskatam ir in_progress, pēc tam completed (vai fault, ja visi laboratorijas pasūtījumi neizdevās bez rezultātu iesniegšanas) — izmanto to, lai noteiktu, vai mājas testa komplekta pasūtījuma laboratorijas darbs ir pabeigts. home_kit_order.results.completed webhook tev paziņo, kad tas notiek, tāpēc tev nav nepārtraukti jāveic vaicājumi. Atsauces uz laboratorijas pārskatu PDF failiem ir masīvā documents — izmanto GET /api/v1/documents/{id}, lai tos lejupielādētu.

Mājas testa komplekta pasūtījuma piemērs