Siirry pääsisältöön
Ajanvaraus on potilasprofiilille varattu verinäytteenotto fyysisessä testitoimipisteessä, ja sen tekee terveydenhuollon ammattilainen. Potilaalle postitettavat testipakkaukset eivät ole ajanvarauksia – katso Kotitestipakkausten tilaukset.

Kentät

string
vaadittu
Anivan automaattisesti luoma UUID. Käytä tätä paneelien lisäämiseen, verinäytteenoton vahvistamiseen ja tulosten hakemiseen.
string
vaadittu
Sen profiilin UUID, johon tämä ajanvaraus kuuluu.
string
Sen testitoimipisteen UUID, jossa verinäytteenotto tehdään. Kotitestipakkaukset eivät ole ajanvarauksia – katso Kotitestipakkausten tilaukset.
string
Verinäytteenoton varattu ajankohta ISO 8601 -muodossa. Palautetaan aina UTC-aikaleimana Z-päätteellä (esim. 2026-04-15T08:30:00Z). Luonnin ja päivityksen yhteydessä arvon on sisällettävä aikavyöhykemerkintä (joko Z tai täsmällinen siirtymä kuten +02:00) – aikavyöhykkeettömät ajankohdat hylätään. Ajankohdan on oltava tulevaisuudessa, ja Anivan ylläpitämissä toimipisteissä vähintään 12 tunnin päässä (vähimmäisennakkoaika).
string
vaadittu
Nykyinen elinkaaren tila. Yksi arvoista pending, confirmed, blood_drawn tai cancelled. Katso Elinkaari alla. Laboratoriotulosten valmistumistila (in_progress vs. completed) saadaan päätepisteestä Hae tulokset, ja lähetyksen tarkempi eteneminen (kuljetuksessa, toimitettu jne.) saadaan seuraamalla kutakin ajanvarauksen shipments-taulukon merkintää päätepisteessä Hae lähetys.
string
Vapaamuotoinen syy, joka kirjattiin ajanvarauksen perumisen yhteydessä (esim. saapumatta jääminen, myöhäinen peruminen, “Epäonnistui. Uusinta tarvitaan”). null, ellei status ole cancelled.
string[]
vaadittu
Osoitteet pienillä kirjaimilla, joista jokainen saa yhden sähköpostin kaikkien laboratoriotulosten valmistuttua. Tyhjä, kun toiminto on pois päältä. Katso Tulokset valmiit -sähköpostit.
string
vaadittu
Verinäytteenottotapa: capillary (sormenpäästä tai olkavarresta mikroputkiin) tai venous (laskimosta putkiin). Se on ajanvaraukselle asetettu tapa tai muutoin sen toimipisteen default_draw_method. Verinäytteenoton jälkeen se on käytetty tapa.
string
vaadittu
ISO 8601 -aikaleima ajanvarauksen luontihetkestä.
string
Viimeisimmän päivityksen ISO 8601 -aikaleima. Null, jos ajanvarausta ei ole koskaan päivitetty.
string[]
vaadittu
Päätepisteessä Vahvista verinäytteenotto kirjatut laboratoriokoodit (putkien viivakoodit) skannausjärjestyksessä. Tyhjä, kunnes verinäytteenotto on vahvistettu. Laskimoverinäytteenotossa jokaiseen putkeen on painettu yksi ja sama koodi; kapillaarinäytteenotossa jokaisella mikronäyteputkella on oma koodinsa. Tulokset ja asiakirjat viittaavat näihin lab_code-kentällä.
object[]
vaadittu
Tähän ajanvaraukseen liitetyt paneelit { panel_id, added_at }-merkintöinä. Katso Paneelien lisääminen.
object[]
vaadittu
Tähän ajanvaraukseen liitetyt yksittäiset biomarkkerit { biomarker_id, added_at }-merkintöinä. Katso Yksittäiset biomarkkerit.
object[]
vaadittu
Tähän ajanvaraukseen liitetyt lähetykset { id, added_at }-merkintöinä, vanhin liitos ensin. Katso Lähetysten liittäminen.
object
vaadittu
Potilaan täydellinen profiiliobjekti, joka sisältyy jokaiseen ajanvarausvastaukseen. Alla olevat kentät ovat vain osajoukko. Hae ajanvaraus listaa ne kaikki.

Elinkaari

Ajanvarauksilla on neljä elinkaaren tilaa:
Ajanvarauksen tilamalli on tarkoituksella karkea – tarkempi eteneminen on saatavilla omien päätepisteidensä kautta:
  • Laboratoriotulosten valmistuminen → Hae tulokset – ylätason status-kenttä on in_progress tai completed.
  • Lähetyksen eteneminen (kuljetuksessa, toimitettu jne.) → seuraa kutakin ajanvarauksen shipments-taulukon merkintää päätepisteessä Hae lähetys – jokaisella lähetyksellä on oma status-kenttänsä ja status_updates-tapahtumalokinsa.
Jokainen tilamuutos lähettää appointment.*-webhookin, esimerkiksi appointment.confirmed. Uusi ajankohta tai toimipiste lähettää tapahtuman appointment.rescheduled.
Ajanvarauksen vahvistaminen (siirtäminen tilaan blood_drawn) on peruuttamatonta. Kun lähetät laboratoriokoodin tai -koodit, laboratoriotilausprosessi käynnistyy eikä sitä voi kumota. Päivitykset ja peruutukset ovat sallittuja vain, kun ajanvaraus on tilassa pending tai confirmed.

Ajanvarausten listaaminen

Hae kaikki API-avaimesi käytettävissä olevat ajanvaraukset:
Voit halutessasi antaa parametrin ?profile_id={uuid} suodattaaksesi tietyn profiilin mukaan. Ilman tätä parametria käytetään oletusaikaväliä (viimeiset 2 kuukautta ja seuraava 1 kuukausi).

Ajanvarauksen päivittäminen

Ennen kuin verinäytteenotto on vahvistettu, voit siirtää aikaa tai vaihtaa testitoimipistettä:
Anna päivitystä varten mikä tahansa yhdistelmä kentistä scheduled_at, location_id, draw_method ja results_ready_emails. Sisällytä vain kentät, joita haluat muuttaa.

Näytteenottotapa

Jokaisella ajanvarauksella on draw_method: capillary (sormenpäästä tai olkavarresta mikronäyteputkiin) tai venous (laskimosta näyteputkiin). Se koskee vain verinäytteenottoa. Virtsa-, vanupuikko- ja muut ei-verinäytteet kerätään samalla tavalla kummassakin tapauksessa. Oletuksena se on toimipisteen default_draw_method. Aseta draw_method luonnin tai päivityksen yhteydessä käyttääksesi toista tapaa, tai aseta se arvoon null palataksesi toimipisteen oletukseen. Toimipisteen on listattava tapa draw_methods-kentässään, ja varatut testit on pystyttävä tekemään sillä, muuten pyyntö palauttaa tilakoodin 400. Et voi muuttaa sitä verinäytteenoton jälkeen. Näytteenoton jälkeen draw_method kertoo käytetyn näytteenottotavan.

Yksi ajanvaraus profiilia, toimipistettä ja ajankohtaa kohti

Profiililla voi olla enintään yksi perumaton ajanvaraus kutakin (location_id, scheduled_at)-paria kohti – yhdeltä henkilöltä ei voi ottaa verinäytettä kahdesti samassa paikassa samana hetkenä riippumatta siitä, kuinka monta rinnakkaista varausta toimipiste hyväksyy. Sekä Luo ajanvaraus että Päivitä ajanvaraus valvovat tätä ja palauttavat tilakoodin 409 sekä appointment_id-tunnisteen, joka viittaa jo olemassa olevaan ajanvaraukseen. Käsittele vastausta jo varattuna aikana äläkä virheenä, jota pitäisi yrittää uudelleen: hae, siirrä tai peru vastauksessa mainittu ajanvaraus. Käytännössä toistuvat luontipyynnöt ovat turvallisia. Verkon aikakatkaisun jälkeen uudelleen lähetetty tai käyttäjän kahdesti käynnistämä luonti päätyy yhteen ajanvaraukseen kahden sijaan — joten sinun ei koskaan tarvitse selvitellä saman potilaan kaksoisvarauksia jälkikäteen.
Päivitykset ovat sallittuja vain ennen verinäytteenottoa — eli kun ajanvaraus on tilassa pending tai confirmed. Kun ajanvaraus siirtyy tilaan blood_drawn tai on tilassa cancelled, sitä ei voi enää muokata. Ainoa poikkeus on results_ready_emails: voit edelleen muuttaa sen yksinään verinäytteenoton jälkeen.

Ajanvarauksen peruminen

Peru ajanvaraus, jota ei enää tarvita:
Tämä asettaa ajanvarauksen tilaksi cancelled. Peruttu ajanvaraus palautetaan vastauksessa. Voit halutessasi lähettää pyynnön rungossa kentän cancellation_reason (enintään 500 merkkiä) syyn tallentamiseksi. Se tallennetaan ajanvaraukseen ja palautetaan kenttänä cancellation_reason myöhemmissä lukupyynnöissä.
Peruminen on sallittua vain ennen verinäytteenottoa — eli kun ajanvaraus on tilassa pending tai confirmed. Ajanvarauksia, jotka ovat jo siirtyneet tilaan blood_drawn, ei voi perua.

Paneelien lisääminen

Lisää haluamasi verikoepaneelit ennen verinäytteenoton vahvistamista kutsumalla:
Anna paneelien UUID-tunnusten taulukko panel_ids-kentässä. Aniva toimittaa paneelitunnukset kumppanitilillesi.
Paneelit on lisättävä ennen verinäytteenottoa — eli kun ajanvaraus on tilassa pending tai confirmed. Et voi lisätä tai muuttaa paneeleja enää sen jälkeen, kun ajanvaraus on siirtynyt tilaan blood_drawn.

Paneelien poistaminen

Jos sinun täytyy poistaa paneeleja ennen verinäytteenottoa, kutsu:
Anna paneelien UUID-tunnusten taulukko panel_ids-kentässä. Poisto on idempotentti: paneeli, jota ei ole liitetty, ohitetaan.
Kuten paneelien lisääminen, myös niiden poistaminen on sallittua vain ennen verinäytteenottoa — eli kun ajanvaraus on tilassa pending tai confirmed. Paneeleja ei voi poistaa enää sen jälkeen, kun ajanvaraus on siirtynyt tilaan blood_drawn.

Yksittäiset biomarkkerit

Voit liittää ajanvaraukseen yksittäisiä biomarkkereita erillisinä testeinä valmiiden paneelien ulkopuolelta. Tämä on hyödyllistä, kun ammattilainen haluaa räätälöidyn valikoiman ennalta määritellyn paketin sijaan. Liitetyt biomarkkerit näkyvät ajanvarauksen vastauksessa individual_biomarkers-taulukkona (panels-kentän rinnalla). Reitityspäätökset tehdään myöhemmin tilauslogistiikkaputkessa kunkin biomarkkerin laboratoriokohtaisten vastaavuuksien perusteella. Lisää biomarkkereita (idempotentti — jo liitetyt biomarkkerit säilytetään):
Poista biomarkkereita (idempotentti — biomarkkerit, joita ei ole liitetty, ohitetaan):
Molemmat päätepisteet ottavat biomarker_ids-taulukon ja validoivat muodostuvan joukon kunkin laboratorion riippuvuussääntöjä vasten — tilaus, jota ei voi tehdä virheettömästi (esim. CRP/HDL-suhde ilman CRP:tä ja HDL:ää), palauttaa koodin 400 sekä biomarkkerit, jotka sinun pitäisi lisätä, eikä tallenna mitään. Käytä päätepistettä Listaa biomarkkerit biomarkkeritunnusten hakemiseen.
Kuten paneelimuutokset, myös yksittäiset biomarkkerit voidaan lisätä tai poistaa vain ennen verinäytteenottoa — eli kun ajanvaraus on tilassa pending tai confirmed. Kun ajanvaraus siirtyy tilaan blood_drawn, mukautettu tilannevedos jäädytetään.

Tarvittavien näyteastioiden esikatselu

Kun olet lisännyt paneeleja tai yksittäisiä biomarkkereita, esikatsele näytteenotossa tarvittavat fyysiset näyteastiat:
Vastauksen containers-taulukko sisältää jokaisen tarvittavan näyteastian tyypin, nimen, korkin värin, tilavuuden, valmistajan tuotenumeron ja kappalemäärän. Tämä auttaa ammattilaisia valmistelemaan oikeat tarvikkeet ennen verinäytteenottoa. Vastauksessa on myös pricing-objekti — ajanvarauksen koko ostoskorin lasku (toteutuneet rivit, liitetyt paneelit ja yksi rivi kutakin toimitettua biomarkkeria kohti hinnastosi mukaan hinnoiteltuna vähittäishinta rinnalla; katso Hinnoittelu), joka täytetään, kun ajanvaraukseen on liitetty testejä ja avaimellasi on prices_view-oikeus, muuten null. routing-kenttää ei tarkoituksella näytetä koskaan, ja se on aina null.
Esikatselu vastaa tällä hetkellä liitettyjä paneeleja ja biomarkkereita. Jos lisäät tai poistat paneeleja esikatselun jälkeen, kutsu esikatselupäätepistettä uudelleen saadaksesi päivitetyt näyteastiavaatimukset.

Verinäytteenoton vahvistaminen

Kun verinäyte on otettu, lähetä laboratoriokoodit (putkien viivakoodit) laboratoriotilausputken käynnistämiseksi:
Lähetä lab_code, kun jokaiseen putkeen on tulostettu sama koodi (laskimonäytteenotto), tai lab_codes yhdellä alkiolla koodia kohti — jokaisessa sen kattamat panel_ids-tunnukset — kun jokainen paneeli otetaan omiin putkiinsa omalla koodillaan (kapillaarinäytteenotto). Kukin paneeli on tällöin oma laboratoriotilauksensa koodinsa alla. Koodit palautetaan ajanvarauksessa kenttänä lab_codes. Kapillaarinäytteenotossa näyte pakataan mikroputkiin. Paneelit menevät ensin varausjärjestyksessä. Yksittäiset biomarkkerit täyttävät sitten paneelien mikroputkien vapaan tilan. Kun ne tarvitsevat lisää tilaa, avataan uusia mikroputkia. Jaamme ne tasaisesti. Kuhunkin mikroputkeen mahtuu enintään 150 µl yksittäisiä biomarkkereita. Paneeleja tai biomarkkereita muuttavat kutsut vastaavat koodilla 400, jos muodostuva joukko rikkoo tätä sääntöä. Tämä siirtää ajanvarauksen tilaan blood_drawn ja käynnistää laboratoriokäsittelyn. Toimintoa ei voi perua.

Lähetyksen nouto

POST /api/v1/appointments/pickup on poistettu yhdessä shipment_picked_up-ajanvaraustilan kanssa. Se vastaa nyt 405 Method Not Allowed, koska polku ohjautuu tunnuksella haettavan ajanvarauksen reittiin. Päätepiste toimi viimeisessä vaiheessaan tyhjänä kutsuna, joka hyväksyi pyynnön muttei tehnyt mitään, joten sen poistaminen ei muuta toimintaa, johon olet luottanut.
Voit seurata verinäytteenoton jälkeistä etenemistä hakemalla jokaisen ajanvarauksen sisäisen shipments-taulukon alkion päätepisteestä Hae lähetys — jokaisella lähetyksellä on oma status-kenttänsä ja status_updates-historiansa.

Lähetysten linkittäminen

Ajanvaraus voidaan linkittää yhteen tai useampaan lähetykseen (ja päinvastoin — suhde on monen suhde moneen). Nykyinen linkkijoukko näkyy sisäisenä molemmilla puolilla:
  • ajanvarauksessa shipments-taulukkona, jossa on { id, added_at }-alkioita;
  • lähetyksessä appointments-taulukkona, jossa on { id, added_at }-alkioita.
Molemmissa taulukoissa vanhin linkki on ensin. Jokainen id viittaa kanoniseen yksityiskohtapäätepisteeseen (Hae lähetys / Hae ajanvaraus), josta saat koko tietosisällön. Lähetykset linkitetään luonnin yhteydessä appointment_id-kentällä päätepisteessä Luo lähetys. Luonnin jälkeen hallinnoi linkkejä lähetyksen kautta päätepisteillä Liitä ajanvarauksia lähetykseen ja Irrota ajanvarauksia lähetyksestä; molemmat palauttavat lähetyksen muutetun ajanvarauslistan. Jos haluat lukea ajanvarauksen paketit kokonaisuudessaan, käytä päätepistettä Listaa lähetykset parametrilla ?appointment_id=. Muutossääntö on: linkkejä voidaan luoda tai poistaa, kun JOKO
  • ajanvaraus on ohittanut verinäytteenoton (blood_drawn) tai
  • lähetys on luotu alle 24 tuntia sitten.
Tämän aikaikkunan ulkopuolella linkki on lukittu, jotta historiatiedot pysyvät vakaina.

Laboratoriotulosten hakeminen

Kun laboratorio on käsitellyt verinäytteet, hae kliiniset ja geneettiset tulokset:
Vastaus sisältää suunnitellut testit (tila planned) vastaanotettujen tulosten rinnalla, joten voit seurata, mikä on vielä kesken. Ylätason status-kenttä on in_progress, kunnes jokainen lähetys sulkeutuu, minkä jälkeen se on completed (tai fault, jos yksikään niistä ei raportoinut) — käytä tätä päätelläksesi, ovatko ajanvarauksen laboratoriotutkimukset valmiit. appointment.results.completed-webhook ilmoittaa, kun näin tapahtuu, joten sinun ei tarvitse kysellä tilaa jatkuvasti. submissions-taulukko erittelee tämän laboratoriolähetteittäin, ja jokaisella on oma lab_code-koodinsa. Jokainen vastaanotettu tulos ja asiakirja sisältää sen lab_code-koodin, jolle se on kirjattu. Laboratorioraporttien PDF-tiedostoihin viitataan documents-taulukossa — lataa ne kutsulla GET /api/v1/documents/{id}.

Esimerkkiajanvaraus