Salt la conținutul principal
O comandă de kit de testare la domiciliu trimite pacientului prin poștă un kit de testare pentru acasă. Aniva expediază kitul, pacientul recoltează singur o probă acasă și o trimite înapoi prin poștă. Aceasta diferă de o programare, care este o recoltare de sânge venos efectuată într-o locație fizică de testare de către un cadru medical.
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

string
obligatoriu
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.
string
obligatoriu
UUID-ul profilului căruia îi aparține această comandă de kit de testare la domiciliu.
string
obligatoriu
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.
object
obligatoriu
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.
string
obligatoriu
Marcajul temporal ISO 8601 al momentului în care a fost creată comanda de kit de testare la domiciliu.
string
Marcaj temporal ISO 8601 al celei mai recente actualizări. Null dacă comanda de kit de testare la domiciliu nu a fost actualizată niciodată.
object
Obiectul complet al profilului pacientului, inclus în fiecare răspuns pentru o comandă de kit de testare la domiciliu.
object[]
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.
object[]
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.
string
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ă.
string
Motivul pentru care a fost trimisă înlocuirea, într-o singură propoziție. null pentru o comandă obișnuită.
string[]
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.
object
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.
string
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=….
string
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.
object[]
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

Ce este returnat depinde de kit. Un kit de sânge apare ca două expedieri după ce Aniva îl ambalează: coletul de la Aniva la pacient și cel de la pacient la laborator (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.
Compoziția unei comenzi de kit de testare la domiciliu poate fi modificată doar cât timp este pending. Odată ce comanda este dispatched (sau mai departe — activated/cancelled), schimbările de panel și endpoint-urile /biomarkers returnează 409 Conflict: kitul fizic este ambalat pe baza panelului selectat, deci conținutul său este blocat în momentul în care pleacă spre pacient. Dacă trebuie neapărat să schimbi testele unei comenzi care este deja blocată, contactează direct Aniva — de obicei este încă posibil și vom face noi modificarea pentru tine, ca să păstrăm conținutul kitului consecvent. Dacă kitul a fost deja folosit și nu a putut oferi rezultatele, comandă în schimb un kit de înlocuire.

Listarea comenzilor de kituri de testare la domiciliu

Preia toate comenzile de kituri de testare la domiciliu accesibile cheii tale API:
Opțional, poți trimite ?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:
Trimite 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:
O înlocuire este o comandă nouă cu un nou cod de laborator, chiar și când primul kit nu a fost niciodată activat: laboratorul are nevoie de o nouă solicitare, iar două probe sub același cod nu pot fi diferențiate. Ambele comenzi rămân accesibile pentru citire, legate prin 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.
Pentru un kit poate fi pe drum o singură înlocuire odată — cât timp o înlocuire este 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:
Include doar câmpurile pe care vrei să le modifici. 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ă:
Aceasta setează statusul comenzii de kit de testare la domiciliu la 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.
O anulare care returnează o eroare lasă comanda exact așa cum era, deci un 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:
Trimite 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 array individual_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):
Elimină biomarkeri (idempotent — un ID care nu este atașat este ignorat):
Ambele endpoint-uri primesc un array 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:
Răspunsul include testele planificate (cu statusul 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.

Exemplu de comandă de kit de testare la domiciliu