Câmpuri
UUID generat automat de Aniva. Folosește-l pentru a adăuga paneluri, a confirma recoltarea și a prelua rezultatele.
UUID-ul locației de testare unde va avea loc recoltarea. Kiturile de testare la domiciliu nu sunt programări — vezi
Comenzi de kituri de testare la domiciliu.
Data și ora programate pentru recoltarea de sânge, în format ISO 8601. Se returnează întotdeauna ca moment UTC cu sufix
Z
(de ex. 2026-04-15T08:30:00Z). La creare / actualizare, valoarea trebuie să includă un indicator de fus
orar (fie Z, fie un decalaj explicit precum +02:00) — valorile fără fus orar sunt respinse. Trebuie
să fie în viitor, iar în locațiile operate de Aniva cu cel puțin 12 ore în avans (preaviz
minim).Statusul curent din ciclul de viață. Una dintre valorile
pending, confirmed, blood_drawn sau cancelled. Vezi
Ciclul de viață mai jos. Detaliile privind finalizarea rezultatelor de laborator (in_progress față de completed) se
obțin din Obținere rezultate; evoluția detaliată a expedierii (în
tranzit, livrată etc.) se obține urmărind fiecare intrare din array-ul inline shipments în
Obținere expediere.Motivul în text liber înregistrat la anularea programării (de ex. neprezentare, anulare tardivă,
„Eșuat. Necesită repetare”). Este
null dacă status nu este cancelled.Adresele care primesc fiecare câte un e-mail când toate rezultatele de laborator sunt finale, cu
litere mici. Gol când este dezactivat. Vezi
E-mailuri pentru rezultate gata.
Cum se face recoltarea de sânge:
capillary (din vârful degetului sau partea superioară a brațului, în
microtainere) sau venous (din venă, în eprubete). Este metoda setată pe programare sau
default_draw_method al locației acesteia. După recoltarea de sânge, este
metoda care a fost folosită.Marcajul temporal ISO 8601 al celei mai recente actualizări. Null dacă programarea nu a fost actualizată niciodată.
Coduri de laborator (coduri de bare ale eprubetelor) înregistrate la Confirmare recoltare de sânge,
în ordinea scanării. Gol până la confirmarea recoltării. O recoltare venoasă are un singur cod tipărit pe fiecare
eprubetă; o recoltare capilară are un cod pentru fiecare microtub. Rezultatele și documentele fac referire la acestea prin
lab_code.Panelurile asociate acestei programări, ca intrări
{ panel_id, added_at }. Vezi
Adăugarea panelurilor.Biomarkerii aleși individual asociați acestei programări, ca intrări
{ biomarker_id, added_at }. Vezi
Biomarkeri individuali.Expedierile asociate acestei programări, ca intrări
{ id, added_at }, începând cu cea mai veche asociere. Vezi
Asocierea expedierilor.Obiectul complet de profil al pacientului, inclus în fiecare răspuns de programare. Câmpurile de mai jos
reprezintă un subset. Obținere programare le enumeră pe toate.
Ciclul de viață
Programările expun patru stări ale ciclului de viață:Statusul programării este intenționat general — evoluția mai detaliată este expusă
prin endpoint-uri dedicate:
- Finalizarea rezultatelor de laborator →
Obținere rezultate — câmpul
statusde nivel superior estein_progresssaucompleted. - Evoluția expedierii (în tranzit, livrată etc.) → urmărește fiecare intrare din array-ul inline
shipmentsal programării în Obținere expediere — fiecare expediere are propriulstatusși un jurnal de evenimentestatus_updates.
appointment.*, de exemplu
appointment.confirmed. O oră sau o locație nouă trimite appointment.rescheduled.Listarea programărilor
Preia toate programările accesibile cheii tale API:?profile_id={uuid} pentru a filtra după un anumit profil. Fără acest parametru, se aplică un interval de timp implicit (ultimele 2 luni până la luna următoare).
Actualizarea unei programări
Înainte de confirmarea recoltării de sânge, poți reprograma sau schimba locația de testare:scheduled_at, location_id, draw_method și results_ready_emails pentru actualizare. Include doar câmpurile pe care vrei să le modifici.
Metoda de recoltare
Fiecare programare are undraw_method: capillary (din vârful degetului sau din partea superioară a brațului, în microtuburi) sau
venous (din venă, în eprubete). Se aplică doar recoltării de sânge. Probele de urină, cele recoltate cu tampon și alte
probe care nu sunt de sânge se colectează la fel, indiferent de metodă.
Implicit, acesta este default_draw_method al locației. Setează draw_method la creare sau actualizare pentru
a folosi o altă metodă sau setează-l la null pentru a reveni la valoarea implicită a locației. Locația trebuie să includă
metoda în draw_methods, iar testele programate trebuie să fie posibile cu aceasta, altfel cererea
returnează 400. Nu îl poți modifica după recoltarea de sânge. După recoltare, draw_method reprezintă
metoda care a fost folosită.
O singură programare per profil, locație și oră
Un profil poate avea cel mult o programare neanulată pentru fiecare pereche(location_id, scheduled_at) — unei
persoane nu i se poate recolta sânge de două ori în același loc și în același moment, indiferent câte programări paralele
acceptă locația.
Atât Creare programare, cât și
Actualizare programare impun această regulă, returnând 409 cu un
appointment_id care indică programarea deja existentă. Tratează acel răspuns ca pe o programare deja
făcută, nu ca pe o eroare de reîncercat: preia, reprogramează sau anulează programarea indicată.
Efectul practic este că cererile repetate de creare sunt sigure. O creare pe care o retrimiți după un timeout de rețea,
sau una pe care un utilizator o declanșează de două ori, duce la o singură programare în loc de două — ceea ce înseamnă și că nu
trebuie niciodată să reconciliezi ulterior programări duplicate pentru același pacient.
Actualizările sunt permise doar înainte de recoltarea de sânge — adică cât timp programarea are statusul
pending sau
confirmed. După ce programarea trece în blood_drawn sau a fost cancelled, nu mai poate
fi modificată. Singura excepție este results_ready_emails: îl poți modifica separat și după
recoltarea de sânge.Anularea unei programări
Anulează o programare care nu mai este necesară:cancelled. Programarea anulată este returnată în răspuns.
Opțional, trimite un cancellation_reason (până la 500 de caractere) în corpul cererii pentru a înregistra motivul. Acesta este
stocat în programare și returnat ca cancellation_reason la citirile ulterioare.
Anularea este permisă doar înainte de recoltarea de sânge — adică cât timp programarea are statusul
pending sau
confirmed. Programările care au trecut deja în blood_drawn nu pot fi anulate.Adăugarea panelurilor
Înainte de a confirma recoltarea de sânge, adaugă panelurile de analize de sânge pe care vrei să le efectuezi apelând:panel_ids. ID-urile panelurilor sunt furnizate de Aniva pentru contul tău de partener.
Panelurile trebuie adăugate înainte de recoltarea de sânge — adică cât timp programarea are statusul
pending sau
confirmed. Nu poți adăuga sau modifica paneluri după ce programarea a trecut în
blood_drawn.Eliminarea panelurilor
Dacă trebuie să elimini paneluri înainte de recoltarea de sânge, apelează:panel_ids. Eliminarea este idempotentă: un panel care nu este atașat este ignorat.
La fel ca adăugarea panelurilor, eliminarea este permisă doar înainte de recoltarea de sânge — adică cât timp programarea are
statusul
pending sau confirmed. Panelurile nu mai pot fi eliminate după ce programarea a trecut în
blood_drawn.Biomarkeri individuali
Poți atașa biomarkeri individuali la o programare ca teste à la carte, în afara oricărui panel predefinit. Acest lucru este util când un practician dorește o selecție personalizată în locul unui pachet prestabilit. Biomarkerii atașați apar în răspunsul programării ca un arrayindividual_biomarkers (la același nivel cu panels). Deciziile de rutare sunt luate ulterior de pipeline-ul de logistică a comenzilor, pe baza mapărilor per laborator ale fiecărui biomarker.
Adaugă biomarkeri (idempotent — biomarkerii deja atașați sunt păstrați):
biomarker_ids și validează setul rezultat conform regulilor de închidere ale fiecărui laborator — o comandă care nu poate fi plasată corect (de ex. un raport CRP/HDL fără CRP și HDL) returnează 400 cu biomarkerii pe care ar trebui să îi adaugi și nu salvează nimic. Folosește Listează biomarkerii pentru a afla ID-urile biomarkerilor.
La fel ca modificările de paneluri, biomarkerii individuali pot fi adăugați sau eliminați doar înainte de recoltarea de sânge
— adică cât timp programarea are statusul
pending sau confirmed. Odată ce programarea trece în
blood_drawn, snapshot-ul personalizat este blocat.Previzualizarea necesarului de recipiente
După adăugarea panelurilor sau a biomarkerilor individuali, previzualizează recipientele fizice de recoltare care vor fi necesare pentru prelevarea probelor:containers din răspuns include tipul, numele, culoarea capacului, volumul, codul de articol al producătorului și numărul de bucăți pentru fiecare recipient necesar. Acest lucru îi ajută pe practicieni să pregătească materialele corecte înainte de recoltarea de sânge. Răspunsul conține și un obiect pricing — nota de plată pentru întregul coș al programării (pozițiile aplicate, panelurile atașate și câte un rând pentru fiecare biomarker livrat, cu tariful din grila ta alături de prețul de retail; vezi Prețuri), populat când programarea are analize atașate și cheia ta are scope-ul prices_view, altfel null. În mod intenționat, routing nu este expus niciodată și este întotdeauna null.
Previzualizarea reflectă panelurile și biomarkerii atașați în prezent. Dacă adaugi sau elimini paneluri
după previzualizare, apelează din nou endpoint-ul de previzualizare pentru a obține necesarul actualizat de recipiente.
Confirmarea recoltării de sânge
După recoltarea de sânge, trimite codurile de laborator (codurile de bare ale eprubetelor) pentru a declanșa pipeline-ul de comenzi de laborator:lab_code când același cod este tipărit pe fiecare eprubetă (recoltare venoasă) sau lab_codes cu câte o intrare
pentru fiecare cod — fiecare cu panel_ids pe care le acoperă — când fiecare panel este recoltat în propriile eprubete, cu
propriul cod (recoltare capilară). Fiecare panel devine apoi propria cerere de laborator sub codul său. Codurile
sunt returnate ca lab_codes în programare.
La o recoltare capilară, recoltarea de sânge este repartizată în microtainere. Panelurile intră primele, în ordinea rezervării. Biomarkerii
individuali ocupă apoi spațiul liber din microtainerele panelurilor. Când au nevoie de mai mult spațiu, deschid
microtainere noi. Îi distribuim uniform. Fiecare microtainer conține cel mult 150 µl de biomarkeri
individuali. Apelurile care modifică paneluri sau biomarkeri răspund cu 400 când setul rezultat încalcă
această regulă.
Aceasta trece statusul programării în blood_drawn și inițiază procesarea în laborator. Această acțiune este ireversibilă.
Preluarea expedierii
Pentru a urmări evoluția după recoltarea de sânge, accesează fiecare intrare din array-ul inlineshipments
al programării prin Obține expedierea — fiecare expediere are propriul status
și un istoric status_updates.
Asocierea expedierilor
O programare poate fi asociată cu una sau mai multe expedieri (și invers — relația este many-to-many). Setul curent de asocieri apare inline pe ambele părți:- în programare, ca un array
shipmentscu intrări{ id, added_at }; - în expediere, ca un array
appointmentscu intrări{ id, added_at }.
id face trimitere la endpoint-ul canonic de detalii
(Obține expedierea /
Obține programarea) pentru payload-ul complet.
Expedierile sunt asociate la creare prin câmpul appointment_id din
Creează expediere. După creare, gestionează asocierile din expediere
cu Atașează programări la expediere și
Detașează programări de la expediere; fiecare returnează
lista actualizată de programări pentru expedierea respectivă. Pentru a citi integral coletele unei programări,
folosește Listează expedierile cu ?appointment_id=.
Regula de modificare este: asocierile pot fi create sau eliminate când FIE
- programarea a trecut de recoltarea de sânge (
blood_drawn), fie - expedierea a fost creată acum mai puțin de 24 de ore.
Preluarea rezultatelor de laborator
După ce laboratorul a procesat probele de sânge, preia rezultatele clinice și genetice:planned) alături de rezultatele primite, astfel încât poți
urmări ce este încă în așteptare. Câmpul status de la nivel superior este in_progress până când fiecare trimitere
se închide, apoi completed (sau fault când niciuna nu a raportat) — folosește-l pentru a determina dacă
analizele de laborator ale programării sunt gata. Un webhook appointment.results.completed
îți spune când se întâmplă acest lucru, deci nu trebuie să interoghezi periodic. Lista
submissions detaliază acest lucru pe fiecare solicitare de laborator, fiecare cu propriul lab_code. Fiecare
rezultat și document primit include lab_code sub care a fost înregistrat. Rapoartele de laborator în format PDF sunt
referențiate în lista documents — folosește GET /api/v1/documents/{id} pentru a le descărca.