Ugrás a fő tartalomhoz
Az időpont egy páciensprofilhoz ütemezett, fizikai vizsgálati helyszínen, egészségügyi szakember által végzett vérvétel. A páciensnek postázott tesztkészletek nem számítanak időpontnak — lásd: Otthoni tesztkészlet-rendelések.

Mezők

string
kötelező
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.
string
kötelező
Annak a profilnak az UUID-je, amelyhez ez az időpont tartozik.
string
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.
string
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ő).
string
kötelező
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.
string
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.
string[]
kötelező
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.
string
kötelező
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.
string
kötelező
Az időpont létrehozásának ISO 8601 időbélyege.
string
A legutóbbi frissítés ISO 8601 időbélyege. Null, ha az időpontot még soha nem frissítették.
string[]
kötelező
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.
object[]
kötelező
Az időponthoz rendelt panelek { panel_id, added_at } elemekként. Lásd: Panelek hozzáadása.
object[]
kötelező
Az időponthoz egyedileg rendelt biomarkerek { biomarker_id, added_at } elemekként. Lásd: Egyedi biomarkerek.
object[]
kötelező
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.
object
kötelező
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ű status mező értéke in_progress vagy completed.
  • Szállítmány előrehaladása (úton, kézbesítve stb.) → kövesd az időpont beágyazott shipments tömbjének elemeit a Szállítmány lekérése végponton — minden szállítmány saját status mezővel és status_updates eseménynaplóval rendelkezik.
Minden állapotváltozás küld egy appointment.* webhookot, például appointment.confirmed. Új időpont vagy helyszín esetén appointment.rescheduled eseményt küld.
Az időpont megerősítése (átállítása blood_drawn állapotba) visszafordíthatatlan. Amint beküldöd a laborkódo(ka)t, elindul a laborrendelési folyamat, amelyet már nem lehet visszavonni. Frissítés és lemondás csak akkor engedélyezett, amíg az időpont pending vagy confirmed állapotban van.

Időpontok listázása

Kérd le az API-kulcsod számára elérhető összes időpontot:
Opcionálisan megadhatod a ?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:
A frissítéshez add meg a 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 egy draw_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:
Ez az időpont státuszát 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:
Adj meg egy panel-UUID-kból álló tömböt a 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:
Adj meg egy panel-UUID-kból álló tömböt a 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 az individual_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):
Biomarkerek eltávolítása (idempotens – a nem csatolt biomarkerek figyelmen kívül maradnak):
Mindkét végpont egy 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:
A válasz 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:
Küldd a 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 POST /api/v1/appointments/pickup végpontot eltávolítottuk, a shipment_picked_up időpontstátusszal együtt. Most 405 Method Not Allowed választ ad, mert az útvonal az azonosító szerinti időpont-útvonalra esik át. A végpont az utolsó időszakában már no-op volt, amely elfogadta a hívást és nem tett semmit, így az eltávolítása nem változtat meg semmilyen működést, amire támaszkodtál.
A vérvétel utáni folyamat nyomon követéséhez kövesd az időpont beágyazott shipments 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ó shipments tömbként;
  • a küldeményen { id, added_at } elemekből álló appointments tömbként.
Mindkét tömbben a legrégebbi kapcsolat áll elöl. Minden 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.
Ezen az időablakon kívül a kapcsolat zárolva van, így az előzményadatok stabilak maradnak.

Laboreredmények lekérése

Miután a laboratórium feldolgozta a vérmintákat, kérd le a klinikai és genetikai eredményeket:
A válasz a beérkezett eredmények mellett a tervezett teszteket (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.

Példa időpontra