Endpointurile pentru comenzi de kituri de testare la domiciliu necesită scope-ul
home_kit_orders_view (citire) sau home_kit_orders_manage
(scriere). Activare acceptă și scope-ul mai restrâns
home_kit_orders_activate. Preluare rezultate și
Trimitere rezultate pe e-mail necesită în plus results_view — rezultatele
de laborator și documentele sunt întotdeauna restricționate de acesta.Câmpuri
UUID generat automat de Aniva. Folosește-l pentru a actualiza comanda, a-i schimba panelul, a o activa, a o
anula și a prelua rezultatele.
UUID-ul profilului căruia îi aparține această comandă de kit de testare la domiciliu.
Statusul curent din ciclul de viață. Una dintre valorile
pending, dispatched, activated sau cancelled. Vezi
Ciclu de viață mai jos. Granularitatea finalizării rezultatelor de laborator (in_progress față de completed) se
deduce din Preluare rezultate.Adresa la care se trimite kitul prin poștă — una dintre două forme: fie
{location_id} care face referire la o
locație de testare cunoscută, fie câmpurile de adresă inline (name, street, city, postal_code,
country_code; company_name / house_number / address_line_2 / state / phone / email
opționale — același vocabular ca în API-ul de locații). Furnizează exact una — o referință de locație
sau o adresă inline, nu ambele.Packstation sau Postfiliale (doar Germania): setează
street la Packstation sau Postfiliale,
house_number la numărul de trei cifre al stației și address_line_2 la DHL
Postnummer al destinatarului (6–10 cifre, spațiile sunt permise). Fără Postnummer, coletul nu poate fi înregistrat.
Postfach nu este acceptat.Marcajul temporal ISO 8601 al momentului în care a fost creată comanda de kit de testare la domiciliu.
Marcaj temporal ISO 8601 al celei mai recente actualizări. Null dacă comanda de kit de testare la domiciliu nu a fost actualizată niciodată.
Obiectul complet al profilului pacientului, inclus în fiecare răspuns pentru o comandă de kit de testare la domiciliu.
Panelul atașat comenzii de kit de testare la domiciliu — întotdeauna exact o intrare de forma
{ panel_id, added_at },
deoarece un kit de testare la domiciliu corespunde 1:1 unui produs fizic de kit. Verifică panel_id în
Listare paneluri.Biomarkerii atașați comenzii de kit de testare la domiciliu în afara panelului acesteia. Fiecare intrare are forma
{ biomarker_id, added_at }. Verifică fiecare biomarker_id în
Listare biomarkeri cu home_kit=true. Pentru o comandă obișnuită, acestea sunt teste à la carte
în plus față de panel; pentru un kit de înlocuire, sunt ceea ce laboratorul
reia.Comanda de kit de testare la domiciliu pe care o înlocuiește aceasta, când este un kit de înlocuire.
null pentru
o comandă obișnuită.Motivul pentru care a fost trimisă înlocuirea, într-o singură propoziție.
null pentru o comandă obișnuită.Adresele care primesc fiecare câte un e-mail odată ce toate rezultatele de laborator sunt finale, scrise cu litere mici. Întotdeauna prezent —
gol când este dezactivat. Setează-l la Creare sau
Actualizare. Vezi
E-mailuri pentru rezultate gata.
Propriile tale perechi cheie/valoare, returnate exact așa cum au fost trimise și niciodată interpretate de Aniva. Întotdeauna prezent la
citire —
{} când nu setezi niciuna. Cel mult 20 de chei; cheile respectă [A-Za-z0-9_-] și au cel mult 40 de
caractere; valorile sunt un șir de caractere, un număr sau o valoare booleană, cu șiruri de cel mult 500 de caractere; 16.384 de
bytes serializați în total. Cheile care încep cu aniva_ sunt rezervate. La
Actualizare, metadatele sunt îmbinate: cheile pe care le omiți se păstrează, o
cheie trimisă ca null este ștearsă, iar {} șterge totul. Validarea este de tip totul sau nimic. Nu pune niciodată
date personale sau clinice în metadata — acestea nu sunt tratate ca date ale pacientului.Codul de probă al laboratorului. Un singur cod, trei roluri: codul sub care sunt raportate rezultatele de laborator, codul tipărit
pe kitul fizic și codul pe care pacientul îl citește de pe cutie drept cod de activare. Alocat când
kitul este ambalat —
null cât timp comanda are status pending, cu excepția cazului în care Aniva a reexpediat un kit (vezi
Ciclu de viață). Întotdeauna doar pentru citire. Identifică comanda corespunzătoare unui kit pe care îl ai
la îndemână cu GET /api/v1/home-kit-orders?lab_code=….Marcajul temporal al recoltării raportat prin Activare — momentul în care
pacientul și-a recoltat efectiv proba, ca moment UTC.
null până când kitul este activat.
Aceasta este ora recoltării care apare în raportul de laborator.Coletele asociate acestei comenzi, începând cu cea mai veche asociere, fiecare de forma
{ id, added_at } — kitul aflat în
drum spre pacient și, pentru kiturile al căror retur este urmărit, proba aflată în drum înapoi spre
laborator, care apar în momentul în care etichetele sunt tipărite. Gol cât timp comanda este
pending, cu excepția cazului în care Aniva a reexpediat un kit. Citește
coletele complete într-un singur apel cu GET /api/v1/shipments?home_kit_order_id={id} — vezi
Expedieri.Ciclul de viață
Comenzile de kituri de testare la domiciliu expun patru stări din ciclul de viață:
Când Aniva retrimite un kit pierdut, comanda revine la
pending, dar își păstrează lab_code și
coletele anterioare în shipments. Noul kit poartă același cod. În noua cutie se pune o etichetă de retur
nefolosită. Doar Aniva face aceste două tranziții; API-ul nu le oferă. Fiecare tranziție trimite un
webhook home_kit_order.pending sau home_kit_order.cancelled.
Statusurile comenzii de kit de testare la domiciliu sunt intenționat generale. Progresul livrării către și de la
pacient este urmărit pe expedierile comenzii —
dispatched înseamnă că kitul
are o etichetă și un cod de laborator, nu că a plecat; câmpul status al expedierii către pacient îți spune dacă
a plecat. Procesarea rezultatelor de laborator are loc la nivelul trimiterilor. Finalizarea rezultatelor de laborator (in_progress față de
completed) este expusă prin Obține rezultate — câmpul status
de nivel superior este in_progress până când fiecare trimitere se închide, apoi completed — sau fault când
fiecare trimitere a eșuat fără să raporteze.Urmărirea coletelor
destination fiind laboratorul), asociate prin paired_with.
Coletul de retur rămâne pending — cu numărul de urmărire deja cunoscut — până când pacientul îl
trimite. Un kit de microbiom intestinal apare ca o singură expediere: kitul către pacient. Plicul său de retur este
preplătit și fără urmărire, deci nu se rezervă nimic pentru drumul înapoi. booked_by indică cine a rezervat
eticheta: "aniva" sau "external". Aici poate fi modificat doar un colet "aniva", și doar câmpul său
notes odată ce eticheta este tipărită. Fiecare colet include toate status_updates de la curier,
inclusiv detail_code de la DHL pentru o redirecționare către un oficiu poștal.
home_kit_orders de pe expediere listează doar comenzile din contextul tău de acces. Vezi
Acces.
Listarea comenzilor de kituri de testare la domiciliu
Preia toate comenzile de kituri de testare la domiciliu accesibile cheii tale API:?profile_id={uuid} pentru a filtra după un anumit profil, sau ?lab_code={code} pentru a
identifica comanda unui kit fizic pe care îl ai la îndemână — primul pas firesc într-un flux de activare.
Crearea unei comenzi de kit de testare la domiciliu
Solicită o comandă de kit de testare la domiciliu pentru profilul unui pacient:profile_id, o adresă delivery_address și un singur panel_id. Comanda este creată în statusul pending.
Trimite opțional header-ul Idempotency-Key pentru ca o reîncercare să nu comande un al doilea kit — vezi Idempotență.
Exact un panel, deoarece un kit de testare la domiciliu corespunde 1:1 unui produs fizic — panelul este kitul. Pot fi comandate doar panelurile pe care Aniva le-a configurat ca kituri de testare la domiciliu; orice alt panel este respins cu 422. Este obligatoriu la creare, deoarece comanda intră imediat în coada de ambalare, iar ambalarea poate începe pe loc. Cât timp comanda este pending, poți schimba panelul prin Actualizare.
Pentru a trimite un al doilea kit în locul unuia care nu a putut oferi rezultatele, trimite replaces_home_kit_order_id în loc să alegi un panel — vezi Kituri de înlocuire.
Kituri de înlocuire
Uneori, un kit nu poate oferi rezultatele: pacientul nu a reușit să umple tubul, proba a ajuns cu prea puțin material sau laboratorul nu a putut analiza o parte din ea. Comandă o înlocuire pentru el:replaces_home_kit_order_id.
Comanda pe care o înlocuiești nu este modificată. Își păstrează statusul, codul de laborator și orice rezultate deja înregistrate sub ea, astfel încât un pacient care trimite totuși primul kit primește tot ce poate citi laboratorul din el.
Panelul este moștenit. Omite panel_id, iar înlocuirea preia panelul comenzii pe care o înlocuiește — asta a cumpărat pacientul și așa este personalizată cutia. Trimite un alt panel doar pentru înlocuirea unui panel întreg; un panel și un subset de markeri împreună sunt respinse cu 422, deoarece un subset are sens doar în cadrul panelului din care a fost ales. Nici panelul unei înlocuiri nu poate fi schimbat ulterior.
Tu alegi ce se reanalizează. Trimite biomarker_ids cu markerii care au eșuat, iar laboratorul îi reanalizează doar pe aceia, astfel încât kitul conține doar tuburile necesare pentru ei. Omite acest câmp pentru a reanaliza întregul panel — alegerea potrivită când nu s-a analizat nimic. Acest lucru nu necesită un scope suplimentar: reanalizarea markerilor pe care pacientul i-a plătit deja nu este o selecție à la carte. Acei markeri nu pot fi eliminați ulterior, deoarece ei reprezintă întreaga solicitare.
Markerii sunt reanalizați ca grupuri ale panelului, nu unul câte unul. Menționarea unui singur marker dintr-un grup reanalizează
întregul grup, deoarece nu poate fi plasată o comandă de laborator care să raporteze mai mult decât s-a cerut.
O înlocuire pentru un singur marker poate reveni, prin urmare, cu mai multe rezultate, iar
numărul de tuburi poate fi mai mare decât sugerează lista de markeri.
pending sau dispatched, o a doua cerere de creare pentru aceeași comandă returnează 409, indicând-o. Rezultatele ajung sub propriul lab_code al înlocuirii, prin propriul său Obține rezultate.
O înlocuire nu este modul în care gestionezi un colet care nu a ajuns niciodată. Anunță Aniva în schimb: aceea este o retrimitere a aceleiași comenzi sub același cod de laborator, nu o comandă nouă.
Actualizarea unei comenzi de kit de testare la domiciliu
Schimbă adresa de livrare, înlocuiește panelul, actualizează-ți metadatele sau înlocuiește adresele de e-mail pentru notificarea rezultatelor:panel_id înlocuiește panelul atașat — având exact un panel pe kit, schimbarea este singura operațiune cu sens pentru panel, motiv pentru care nu există endpoint-uri de adăugare sau eliminare de paneluri. Adresa și panelul pot fi modificate doar cât timp comanda este pending; metadata rămâne modificabil pe toată durata de viață a comenzii. results_ready_emails rămâne modificabil până când comanda este cancelled.
Anularea unei comenzi de kit de testare la domiciliu
Anulează o comandă de kit de testare la domiciliu care nu mai este necesară:cancelled. Comanda de kit de testare la domiciliu anulată este returnată în răspuns.
Doar o comandă pending poate fi anulată. De la dispatched încolo, kitul a fost ambalat și etichetat — nu există o retragere automată — iar apelul returnează 409. Dacă un kit deja expediat trebuie oprit, contactează direct Aniva.
Anularea unei comenzi pending al cărei kit a fost deja comandat la centrul de expediere îl anulează și acolo, iar apelul reușește doar dacă centrul de expediere acceptă:
409— kitul a fost deja ambalat și etichetat, așa că nu mai poate fi retras, chiar dacă comanda apare încăpending.502— centrul de expediere a refuzat anularea (eroarea include motivul lor) sau nu a putut fi contactat. Nimic nu a fost modificat — comanda este încă activă și poate fi anulată din nou.
200 este singura confirmare că nu va veni niciun kit.
Anularea unei comenzi care este deja cancelled returnează același 200, indiferent din ce status a fost anulată.
Activarea unei comenzi de kit de testare la domiciliu
Când pacientul și-a recoltat proba, raportează acest lucru:activated_at — momentul exact în care pacientul a recoltat proba, ca marcaj temporal UTC. Acesta este momentul recoltării care va apărea pe raportul de laborator, așa că trimite momentul real al recoltării, nu momentul procesării tale. Activarea este finală: comanda trece în activated și nu mai poate fi anulată sau modificată. Echivalentul pentru kitul de testare la domiciliu al Confirmă recoltarea de sânge, fără cod de bare — codul kitului este aplicat la ambalare, deci nu trebuie să îl cunoști niciodată. Comanda trebuie să aibă deja lab_code până atunci; o comandă fără acesta returnează 409.
Activarea este și cea care plasează comanda de laborator: panelul kitului este comandat la laborator sub lab_code-ul său, astfel încât proba returnată este așteptată, iar rezultatele se atașează pe măsură ce laboratorul le raportează. Acest proces rulează după răspuns, iar o problemă din partea laboratorului este gestionată de Aniva, nu afișată în cererea ta.
Biomarkeri individuali
Poți atașa biomarkeri individuali la o comandă de kit de testare la domiciliu ca teste à la carte, în afara panelului. Acest lucru este util când vrei o selecție personalizată pe lângă kit. Biomarkerii atașați apar în răspunsul comenzii de kit de testare la domiciliu ca un arrayindividual_biomarkers (la același nivel cu panels).
Ambele endpoint-uri pentru biomarkeri necesită scope-ul de capabilitate home_kit_orders_individual_biomarker_selection pe lângă home_kit_orders_manage — kiturile de testare la domiciliu se comandă pe bază de panel, așa că markerii à la carte sunt activați pentru fiecare partener. Întreabă Aniva dacă integrarea ta are nevoie de asta.
Adaugă biomarkeri (idempotent — biomarkerii deja atașați sunt păstrați):
biomarker_ids. Folosește Listează biomarkeri cu home_kit=true pentru a descoperi ID-urile biomarkerilor. Biomarkerii pot fi modificați doar cât timp kitul este pending (vezi Ciclul de viață).
Preluarea rezultatelor de laborator
După ce laboratorul a procesat proba returnată, preia rezultatele clinice și genetice:planned) alături de rezultatele primite, astfel încât să poți urmări ce este încă în așteptare. Rezultatele sunt înregistrate sub lab_code-ul comenzii și sosesc marker cu marker pe măsură ce laboratorul le analizează, așa că payload-urile parțiale sunt normale. Câmpul status de la nivelul principal este in_progress până la raportul final, apoi completed (sau fault când fiecare comandă de laborator a eșuat fără a raporta) — folosește acest câmp pentru a determina dacă analiza de laborator pentru comanda de kit de testare la domiciliu este gata. Un webhook home_kit_order.results.completed te anunță când se întâmplă asta, așa că nu trebuie să faci polling. PDF-urile rapoartelor de laborator sunt referențiate în array-ul documents — folosește GET /api/v1/documents/{id} pentru a le descărca.