Salt la conținutul principal
O programare este o recoltare de sânge planificată pentru un profil de pacient la o locație fizică de testare, efectuată de un cadru medical. Kiturile trimise prin poștă unui pacient nu sunt programări — vezi Comenzi de kituri de testare la domiciliu.

Câmpuri

string
obligatoriu
UUID generat automat de Aniva. Folosește-l pentru a adăuga paneluri, a confirma recoltarea și a prelua rezultatele.
string
obligatoriu
UUID-ul profilului căruia îi aparține această programare.
string
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.
string
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).
string
obligatoriu
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.
string
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.
string[]
obligatoriu
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.
string
obligatoriu
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ă.
string
obligatoriu
Timestamp ISO 8601 al creării programării.
string
Marcajul temporal ISO 8601 al celei mai recente actualizări. Null dacă programarea nu a fost actualizată niciodată.
string[]
obligatoriu
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.
object[]
obligatoriu
Panelurile asociate acestei programări, ca intrări { panel_id, added_at }. Vezi Adăugarea panelurilor.
object[]
obligatoriu
Biomarkerii aleși individual asociați acestei programări, ca intrări { biomarker_id, added_at }. Vezi Biomarkeri individuali.
object[]
obligatoriu
Expedierile asociate acestei programări, ca intrări { id, added_at }, începând cu cea mai veche asociere. Vezi Asocierea expedierilor.
object
obligatoriu
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 status de nivel superior este in_progress sau completed.
  • Evoluția expedierii (în tranzit, livrată etc.) → urmărește fiecare intrare din array-ul inline shipments al programării în Obținere expediere — fiecare expediere are propriul status și un jurnal de evenimente status_updates.
Fiecare schimbare de status trimite un webhook appointment.*, de exemplu appointment.confirmed. O oră sau o locație nouă trimite appointment.rescheduled.
Confirmarea unei programări (trecerea ei în blood_drawn) este ireversibilă. După ce trimiți codul sau codurile de laborator, fluxul de comandă către laborator este declanșat și nu poate fi anulat. Actualizările și anulările sunt permise doar cât timp programarea are statusul pending sau confirmed.

Listarea programărilor

Preia toate programările accesibile cheii tale API:
Poți transmite opțional ?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:
Transmite orice combinație de 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 un draw_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ă:
Aceasta setează statusul programării la 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:
Trimite un array cu UUID-urile panelurilor în câmpul 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ă:
Trimite un array cu UUID-urile panelurilor în câmpul 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 array individual_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):
Elimină biomarkeri (idempotent — biomarkerii care nu sunt atașați sunt ignorați):
Ambele endpoint-uri primesc un array 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:
Array-ul 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:
Trimite 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

POST /api/v1/appointments/pickup a fost eliminat, împreună cu statusul de programare shipment_picked_up. Acum răspunde cu 405 Method Not Allowed, deoarece calea ajunge în ruta pentru programare după ID. În ultima sa fază, endpoint-ul a funcționat ca un no-op care accepta apelul și nu făcea nimic, deci eliminarea lui nu modifică niciun comportament pe care te bazai.
Pentru a urmări evoluția după recoltarea de sânge, accesează fiecare intrare din array-ul inline shipments 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 shipments cu intrări { id, added_at };
  • în expediere, ca un array appointments cu intrări { id, added_at }.
Ambele array-uri sunt ordonate de la cea mai veche asociere. Fiecare 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.
În afara acestui interval, asocierea este blocată pentru ca înregistrările istorice să rămână stabile.

Preluarea rezultatelor de laborator

După ce laboratorul a procesat probele de sânge, preia rezultatele clinice și genetice:
Răspunsul include testele planificate (cu status 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.

Exemplu de programare