Mezők
Az Aniva által automatikusan generált UUID. Ezzel adhatsz hozzá paneleket, erősítheted meg a vérvételt, és kérheted le az eredményeket.
Annak a vizsgálati helyszínnek az UUID-je, ahol a vérvétel történik. Az otthoni tesztkészletek nem számítanak időpontnak — lásd:
Otthoni tesztkészlet-rendelések.
A vérvétel ütemezett időpontja ISO 8601 formátumban. Mindig UTC időpontként,
Z
utótaggal tér vissza (pl. 2026-04-15T08:30:00Z). Létrehozáskor és frissítéskor az értéknek tartalmaznia kell időzóna-jelölést
(vagy Z, vagy explicit eltolás, pl. +02:00) — az időzóna nélküli értékeket a rendszer elutasítja. Jövőbeli időpontnak kell lennie,
az Aniva által üzemeltetett helyszíneken pedig legalább 12 órával későbbinek (minimális
foglalási határidő).Az aktuális életciklus-állapot. Lehetséges értékei:
pending, confirmed, blood_drawn vagy cancelled. Lásd az
Életciklus szakaszt alább. A laboreredmények készültségi szintje (in_progress vagy completed)
az Eredmények lekérése végpontból kérhető le; a szállítmány részletesebb állapotát (úton,
kézbesítve stb.) a beágyazott shipments tömb elemeit követve a
Szállítmány lekérése végpont adja meg.Az időpont lemondásakor rögzített szabadszöveges ok (pl. meg nem jelenés, késői lemondás,
„Sikertelen. Ismétlés szükséges”).
null, kivéve, ha a status értéke cancelled.Címek, amelyek mindegyike egy-egy e-mailt kap, amint minden laboreredmény végleges, kisbetűvel. Kikapcsolva üres. Lásd:
Eredmények elkészültéről szóló e-mailek.
A vérvétel módja:
capillary (ujjbegyből vagy felkarból, mikrocsövekbe) vagy venous (vénából,
csövekbe). Az időpontnál beállított módszer, ennek hiányában a
helyszín default_draw_method értéke. A vérvétel után a ténylegesen használt módszer.A Vérvétel megerősítése során rögzített laborkódok (csővonalkódok),
a beolvasás sorrendjében. Üres, amíg a vérvételt meg nem erősítették. Vénás vérvételnél minden csőre ugyanaz a kód kerül;
kapilláris vérvételnél minden mikrocső saját kódot kap. Az eredmények és dokumentumok a
lab_code mezőn keresztül hivatkoznak ezekre.Az időponthoz rendelt panelek
{ panel_id, added_at } elemekként. Lásd:
Panelek hozzáadása.Az időponthoz egyedileg rendelt biomarkerek
{ biomarker_id, added_at } elemekként. Lásd:
Egyedi biomarkerek.Az időponthoz kapcsolt szállítmányok
{ id, added_at } elemekként, a legrégebbi kapcsolattal kezdve. Lásd:
Szállítmányok összekapcsolása.A páciens teljes profilobjektuma, minden időpontválaszba beágyazva. Az alábbi mezők csak egy
részhalmazt mutatnak. Az Időpont lekérése végpont mindegyiket felsorolja.
Életciklus
Az időpontoknak négy életciklus-állapotuk van:Az időpont állapota szándékosan nagy vonalakban követhető — a részletesebb előrehaladást
külön végpontok adják meg:
- Laboreredmények készültsége →
Eredmények lekérése — a legfelső szintű
statusmező értékein_progressvagycompleted. - Szállítmány előrehaladása (úton, kézbesítve stb.) → kövesd az időpont beágyazott
shipmentstömbjének elemeit a Szállítmány lekérése végponton — minden szállítmány sajátstatusmezővel ésstatus_updateseseménynaplóval rendelkezik.
appointment.* webhookot, például
appointment.confirmed. Új időpont vagy helyszín esetén appointment.rescheduled eseményt küld.Időpontok listázása
Kérd le az API-kulcsod számára elérhető összes időpontot:?profile_id={uuid} paramétert egy adott profil szerinti szűréshez. E paraméter nélkül az alapértelmezett időablak (az elmúlt 2 hónaptól a következő 1 hónapig) érvényes.
Időpont frissítése
A vérvétel megerősítése előtt átütemezheted az időpontot, vagy módosíthatod a vizsgálati helyszínt:scheduled_at, location_id, draw_method és results_ready_emails mezők tetszőleges kombinációját. Csak azokat a mezőket add meg, amelyeket módosítani szeretnél.
Vérvételi mód
Minden időponthoz tartozik egydraw_method: capillary (ujjbegyből vagy felkarból, mikrocsövekbe) vagy
venous (vénából, csövekbe). Ez kizárólag a vérvételre vonatkozik. A vizelet-, kenet- és egyéb,
nem vérminták levétele mindkét módnál ugyanúgy történik.
Alapértelmezés szerint a helyszín default_draw_method értékét veszi fel. Létrehozáskor vagy frissítéskor állítsd be a draw_method mezőt
másik mód használatához, vagy állítsd null értékre a helyszín alapértelmezésének visszaállításához. A helyszínnek szerepeltetnie kell
a módot a draw_methods listájában, és a lefoglalt teszteknek elvégezhetőnek kell lenniük vele, különben a kérés
400 hibával tér vissza. A vérvétel után már nem módosíthatod. A vérvétel után a draw_method mező a ténylegesen
használt módot mutatja.
Profilonként, helyszínenként és időpontonként egy foglalás
Egy profilhoz legfeljebb egy nem lemondott időpont tartozhat(location_id, scheduled_at) páronként — egy
személynél nem lehet ugyanott és ugyanabban a pillanatban kétszer vért venni, függetlenül attól, hány párhuzamos foglalást fogad el a
helyszín.
Mind az Időpont létrehozása, mind az
Időpont frissítése végpont kikényszeríti ezt: 409 kóddal és a már létező időpontra mutató
appointment_id értékkel tér vissza. Kezeld ezt a választ már lefoglalt időpontként,
ne újrapróbálandó hibaként: kérd le, ütemezd át vagy mondd le a megadott időpontot.
A gyakorlatban ez azt jelenti, hogy az ismételt létrehozások biztonságosak. Egy hálózati időtúllépés
után újraküldött vagy egy felhasználó által kétszer elindított létrehozás két időpont helyett egyetlen
időpontot eredményez – így utólag sosem kell összeegyeztetned ugyanannak a páciensnek a duplikált foglalásait.
A módosítás csak a vérvétel előtt engedélyezett – vagyis amíg az időpont
pending vagy
confirmed státuszban van. Miután az időpont blood_drawn vagy cancelled státuszba került, már
nem módosítható. Az egyetlen kivétel a results_ready_emails: ezt önmagában a vérvétel után is
megváltoztathatod.Időpont lemondása
Mondj le egy már nem szükséges időpontot:cancelled értékre állítja. A válasz a lemondott időpontot adja vissza.
Opcionálisan megadhatsz egy cancellation_reason mezőt (legfeljebb 500 karakter) a kérés törzsében
az ok rögzítéséhez. Ezt az időpontnál tároljuk, és a későbbi lekérdezések cancellation_reason néven adják vissza.
A lemondás csak a vérvétel előtt engedélyezett – vagyis amíg az időpont
pending vagy
confirmed státuszban van. A már blood_drawn státuszba került időpontok nem mondhatók le.Panelek hozzáadása
A vérvétel megerősítése előtt add hozzá az elvégzendő vérvizsgálati paneleket ezzel a hívással:panel_ids mezőben. A panelazonosítókat az Aniva biztosítja a partnerfiókodhoz.
A paneleket a vérvétel előtt kell hozzáadni – vagyis amíg az időpont
pending vagy confirmed
státuszban van. Miután az időpont blood_drawn státuszba került, már nem adhatsz hozzá és nem
módosíthatsz paneleket.Panelek eltávolítása
Ha a vérvétel előtt paneleket kell eltávolítanod, hívd ezt:panel_ids mezőben. Az eltávolítás idempotens: egy nem csatolt panel figyelmen kívül marad.
A panelek hozzáadásához hasonlóan az eltávolítás is csak a vérvétel előtt engedélyezett – vagyis
amíg az időpont
pending vagy confirmed státuszban van. Miután az időpont blood_drawn
státuszba került, a panelek már nem távolíthatók el.Egyedi biomarkerek
Előre összeállított paneleken kívül egyedi biomarkereket is csatolhatsz egy időponthoz, à la carte vizsgálatokként. Ez akkor hasznos, ha a szakember egy előre meghatározott csomag helyett személyre szabott összeállítást szeretne. A csatolt biomarkerek az időpont válaszában azindividual_biomarkers tömbben jelennek meg (a panels mező mellett). Az útválasztási döntéseket a későbbi szakaszban a rendeléslogisztikai folyamat hozza meg az egyes biomarkerek laboratóriumonkénti hozzárendelései alapján.
Biomarkerek hozzáadása (idempotens – a már csatolt biomarkerek megmaradnak):
biomarker_ids tömböt vár, és ellenőrzi az így létrejövő készletet az egyes laboratóriumok zártsági szabályai alapján – egy nem tisztán leadható rendelés (pl. CRP/HDL-arány CRP és HDL nélkül) 400-as választ ad a hozzáadandó biomarkerekkel együtt, és nem ment el semmit. A biomarker-azonosítók megkereséséhez használd a Biomarkerek listázása végpontot.
A panelek módosításához hasonlóan az egyedi biomarkerek is csak a vérvétel előtt adhatók hozzá
vagy távolíthatók el – vagyis amíg az időpont
pending vagy confirmed státuszban van. Miután
az időpont blood_drawn státuszba került, az egyedi összeállítás rögzítődik.Szükséges mintavevő edények előnézete
Panelek vagy egyedi biomarkerek hozzáadása után tekintsd meg a mintavételhez szükséges fizikai mintavevő edények előnézetét:containers tömbje minden szükséges edényhez tartalmazza a típust, a nevet, a kupak színét, a térfogatot, a gyártói cikkszámot és a darabszámot. Ez segít a szakembereknek a megfelelő eszközök előkészítésében a vérvétel előtt. A válasz tartalmaz egy pricing objektumot is – ez az időpont teljes kosár-elszámolása (az aktiválódott tételek, a csatolt panelek, valamint minden teljesített biomarkerhez egy-egy sor a te árlistád szerinti árral és mellette a fogyasztói árral; lásd: Árazás), amely akkor töltődik ki, ha az időponthoz vannak csatolt vizsgálatok és a kulcsod rendelkezik a prices_view scope-pal, különben null. A routing szándékosan sosem érhető el, és mindig null.
Az előnézet az aktuálisan csatolt paneleket és biomarkereket tükrözi. Ha az előnézet után
paneleket adsz hozzá vagy távolítasz el, hívd meg újra az előnézeti végpontot a frissített
edényigények lekéréséhez.
Vérvétel megerősítése
A vérvétel után küldd be a laborkódokat (a csövek vonalkódjait) a laboratóriumi rendelési folyamat elindításához:lab_code mezőt, ha ugyanaz a kód van nyomtatva minden csőre (vénás vérvétel), vagy a
lab_codes mezőt kódonként egy-egy bejegyzéssel – mindegyikben a hozzá tartozó panel_ids
értékekkel –, ha minden panelt saját csövekbe, saját kóddal vesznek le (kapilláris vérvétel).
Ilyenkor minden panel külön laboratóriumi megrendelés a saját kódja alatt. A kódokat az időpont
lab_codes mezője adja vissza.
Kapilláris vérvételnél a levett vér mikrotainerekbe kerül. A panelek mennek először, foglalási
sorrendben. Az egyedi biomarkerek ezután a panelek mikrotainereinek szabad helyét töltik ki. Ha több
helyre van szükségük, új mikrotainereket nyitnak. Egyenletesen osztjuk el őket. Egy mikrotainer
legfeljebb 150 µl egyedi biomarkert fogad be. A paneleket vagy biomarkereket módosító hívások
400-zal válaszolnak, ha az így létrejövő összeállítás megsérti ezt a szabályt.
Ez az időpont státuszát blood_drawn értékre állítja, és elindítja a laboratóriumi feldolgozást. Ez a művelet nem vonható vissza.
Küldemény felvétele
A vérvétel utáni folyamat nyomon követéséhez kövesd az időpont beágyazottshipments tömbjének
elemeit a Küldemény lekérése végponton – minden küldemény saját
status értékkel és status_updates előzményekkel rendelkezik.
Küldemények összekapcsolása
Egy időpont egy vagy több küldeményhez kapcsolható (és fordítva – a kapcsolat több a többhöz típusú). Az aktuális kapcsolatok mindkét oldalon beágyazva jelennek meg:- az időponton
{ id, added_at }elemekből állóshipmentstömbként; - a küldeményen
{ id, added_at }elemekből állóappointmentstömbként.
id a kanonikus részletező végpontra
(Küldemény lekérése /
Időpont lekérése) hivatkozik a teljes adattartalomhoz.
A küldeményeket létrehozáskor a Küldemény létrehozása végpont
appointment_id mezőjével kapcsolhatod össze. Létrehozás után a kapcsolatokat a küldemény oldaláról
kezelheted az Időpontok csatolása küldeményhez és az
Időpontok leválasztása küldeményről végpontokkal;
mindkettő az adott küldemény módosítás utáni időpontlistáját adja vissza. Egy időpont csomagjainak
teljes lekéréséhez használd a Küldemények listázása végpontot a
?appointment_id= paraméterrel.
A módosítási szabály: kapcsolatok akkor hozhatók létre vagy távolíthatók el, ha VAGY
- az időpont túl van a vérvételen (
blood_drawn), vagy - a küldemény kevesebb mint 24 órája jött létre.
Laboreredmények lekérése
Miután a laboratórium feldolgozta a vérmintákat, kérd le a klinikai és genetikai eredményeket:planned státusszal) is tartalmazza, így nyomon
követheted, mi van még függőben. A legfelső szintű status mező értéke in_progress, amíg az összes beküldés
le nem zárul, utána pedig completed (vagy fault, ha egyikről sem érkezett jelentés) — ebből állapíthatod meg,
hogy elkészült-e az időponthoz tartozó laboratóriumi munka. Egy appointment.results.completed webhook
értesít, amikor ez megtörténik, így nincs szükség ismételt lekérdezésre. A
submissions tömb ezt laboratóriumi igénylésenként bontja le, mindegyiket a saját lab_code kódjával. Minden
beérkezett eredmény és dokumentum tartalmazza azt a lab_code kódot, amely alatt iktatták. A PDF laborjelentésekre
a documents tömb hivatkozik — a letöltésükhöz használd a GET /api/v1/documents/{id} végpontot.