Hopp til hovedinnhold
En time er en planlagt blodprøvetaking for en pasientprofil på et fysisk teststed, utført av helsepersonell. Testsett som sendes i posten til en pasient, er ikke timer — se Bestillinger av hjemmetestsett.

Felter

string
påkrevd
UUID automatisk generert av Aniva. Bruk denne for å legge til paneler, bekrefte blodprøvetakingen og hente resultater.
string
påkrevd
UUID-en til profilen denne timen tilhører.
string
UUID-en til teststedet der blodprøvetakingen skal finne sted. Hjemmetestsett er ikke timer — se Bestillinger av hjemmetestsett.
string
Planlagt tidspunkt for blodprøvetaking i ISO 8601-format. Returneres alltid som et UTC-tidspunkt med Z-suffiks (f.eks. 2026-04-15T08:30:00Z). Ved opprettelse / oppdatering må verdien inkludere en tidssoneangivelse (enten Z eller en eksplisitt forskyvning som +02:00) — tidspunkter uten tidssone avvises. Må være i fremtiden, og på Aniva-drevne steder minst 12 timer frem i tid (minstefrist).
string
påkrevd
Gjeldende livssyklusstatus. En av pending, confirmed, blood_drawn eller cancelled. Se Livssyklus nedenfor. Detaljert status for labresultater (in_progress vs. completed) hentes fra Hent resultater; mer detaljert forsendelsesfremdrift (underveis, levert osv.) får du ved å følge hvert element i den innebygde shipments-listen til Hent forsendelse.
string
Fritekstårsak som ble registrert da timen ble avbestilt (f.eks. manglende oppmøte, sen avbestilling, «Mislyktes. Må gjentas»). null med mindre status er cancelled.
string[]
påkrevd
Adresser som hver får én e-post når alle labresultater er endelige, i små bokstaver. Tom når den er slått av. Se E-poster om klare resultater.
string
påkrevd
Hvordan blodprøven tas: capillary (fingertupp eller overarm, i mikrorør) eller venous (fra vene, i prøverør). Det er metoden som er satt på timen, ellers default_draw_method for stedet. Etter blodprøvetakingen er det metoden som ble brukt.
string
påkrevd
ISO 8601-tidsstempel for når timen ble opprettet.
string
ISO 8601-tidsstempel for den siste oppdateringen. Null hvis timen aldri har blitt oppdatert.
string[]
påkrevd
Labkoder (strekkoder på prøverør) registrert ved Bekreft blodprøvetaking, i skannerekkefølge. Tom til blodprøvetakingen er bekreftet. En venøs blodprøvetaking har én kode trykket på hvert prøverør; en kapillær blodprøvetaking har én kode per mikrorør. Resultater og dokumenter viser til disse via lab_code.
object[]
påkrevd
Paneler knyttet til denne timen, som { panel_id, added_at }-elementer. Se Legge til paneler.
object[]
påkrevd
Enkeltbiomarkører knyttet til denne timen, som { biomarker_id, added_at }-elementer. Se Enkeltbiomarkører.
object[]
påkrevd
Forsendelser knyttet til denne timen, som { id, added_at }-elementer, med eldste kobling først. Se Knytte forsendelser.
object
påkrevd
Hele profilobjektet for pasienten, innebygd i hvert svar for en time. Feltene nedenfor er et utvalg. Hent time viser alle.

Livssyklus

Timer har fire livssyklustilstander:
Statusen på timen er bevisst overordnet — mer detaljert fremdrift vises via egne endepunkter:
  • Ferdigstillelse av labresultater → Hent resultater — toppnivåfeltet status er in_progress eller completed.
  • Forsendelsesfremdrift (underveis, levert osv.) → følg hvert element i den innebygde shipments-listen på timen til Hent forsendelse — hver forsendelse har sin egen status og en status_updates-hendelseslogg.
Hver statusendring sender en appointment.*-webhook, for eksempel appointment.confirmed. Et nytt tidspunkt eller sted sender appointment.rescheduled.
Å bekrefte en time (flytte den til blood_drawn) er irreversibelt. Når du sender inn labkoden(e), startes labbestillingsprosessen og kan ikke angres. Oppdateringer og avbestillinger er bare tillatt mens timen har status pending eller confirmed.

Liste opp timer

Hent alle timer som API-nøkkelen din har tilgang til:
Du kan eventuelt sende med ?profile_id={uuid} for å filtrere på en bestemt profil. Uten denne parameteren brukes et standard tidsvindu (de siste 2 månedene til 1 måned frem i tid).

Oppdatere en time

Før blodprøvetakingen er bekreftet, kan du endre tidspunktet eller bytte teststed:
Send med en hvilken som helst kombinasjon av scheduled_at, location_id, draw_method og results_ready_emails for å oppdatere. Ta bare med feltene du vil endre.

Prøvetakingsmetode

Hver time har en draw_method: capillary (fingertupp eller overarm, i mikrorør) eller venous (fra venen, i prøverør). Den gjelder bare for blodprøvetakingen. Urin-, vattpinne- og andre prøver som ikke er blod, tas på samme måte uansett metode. Som standard er den satt til stedets default_draw_method. Angi draw_method ved opprettelse eller oppdatering for å bruke en annen metode, eller sett den til null for å gå tilbake til stedets standard. Stedet må ha metoden oppført i draw_methods, og de bestilte testene må være mulige å ta med den, ellers returnerer forespørselen 400. Du kan ikke endre den etter blodprøvetakingen. Etter blodprøvetakingen er draw_method metoden som ble brukt.

Én time per profil, sted og tidspunkt

En profil kan høyst ha én ikke-avbestilt time per (location_id, scheduled_at)-par — én person kan ikke ta blodprøve to ganger på samme sted på samme tidspunkt, uavhengig av hvor mange samtidige bestillinger stedet godtar. Både Opprett time og Oppdater time håndhever dette, og returnerer 409 med en appointment_id som peker på timen som allerede finnes. Behandle det svaret som at timen allerede er bestilt, i stedet for en feil du skal prøve på nytt: hent, flytt eller avbestill timen som oppgis. Den praktiske effekten er at gjentatte opprettelser er trygge. En opprettelse du sender på nytt etter et tidsavbrudd i nettverket, eller som en bruker utløser to ganger, blir til én time i stedet for to – noe som også betyr at du aldri trenger å rydde opp i duplikate bestillinger for samme pasient i etterkant.
Oppdateringer er kun tillatt før blodprøvetakingen – dvs. mens timen har status pending eller confirmed. Når timen går over til blood_drawn eller er cancelled, kan den ikke endres. Det eneste unntaket er results_ready_emails: den kan du fortsatt endre alene etter blodprøvetakingen.

Avbestille en time

Avbestill en time som ikke lenger trengs:
Dette setter statusen på timen til cancelled. Den avbestilte timen returneres i svaret. Du kan valgfritt sende cancellation_reason (opptil 500 tegn) i forespørselen for å registrere årsaken. Den lagres på timen og returneres som cancellation_reason ved senere oppslag.
Avbestilling er kun tillatt før blodprøvetakingen – dvs. mens timen har status pending eller confirmed. Timer som allerede har gått over til blood_drawn, kan ikke avbestilles.

Legge til paneler

Før du bekrefter blodprøvetakingen, legger du til blodprøvepanelene du vil kjøre ved å kalle:
Send en array med panel-UUID-er i feltet panel_ids. Panel-ID-er oppgis av Aniva for partnerkontoen din.
Paneler må legges til før blodprøvetakingen – dvs. mens timen har status pending eller confirmed. Du kan ikke legge til eller endre paneler når timen har gått over til blood_drawn.

Fjerne paneler

Hvis du trenger å fjerne paneler før blodprøvetakingen, kaller du:
Send en array med panel-UUID-er i feltet panel_ids. Fjerning er idempotent: et panel som ikke er tilknyttet, ignoreres.
På samme måte som å legge til paneler er fjerning kun tillatt før blodprøvetakingen – dvs. mens timen har status pending eller confirmed. Paneler kan ikke fjernes når timen har gått over til blood_drawn.

Individuelle biomarkører

Du kan knytte individuelle biomarkører til en time som à la carte-tester, utenom ferdige paneler. Dette er nyttig når en behandler ønsker et skreddersydd utvalg i stedet for en forhåndsdefinert pakke. De tilknyttede biomarkørene vises i svaret for timen som arrayen individual_biomarkers (på samme nivå som panels). Rutingsbeslutninger tas nedstrøms av pipelinen for ordrelogistikk basert på hver biomarkørs tilordninger per laboratorium. Legg til biomarkører (idempotent – biomarkører som allerede er tilknyttet, beholdes):
Fjern biomarkører (idempotent – biomarkører som ikke er tilknyttet, ignoreres):
Begge endepunktene tar arrayen biomarker_ids og validerer det resulterende settet mot hvert laboratoriums avhengighetsregler – en bestilling som ikke kan legges inn uten mangler (f.eks. CRP/HDL-forhold uten CRP og HDL), returnerer 400 med biomarkørene du må legge til, og lagrer ingenting. Bruk List opp biomarkører for å finne biomarkør-ID-er.
På samme måte som panelendringer kan individuelle biomarkører kun legges til eller fjernes før blodprøvetakingen – dvs. mens timen har status pending eller confirmed. Når timen går over til blood_drawn, fryses det tilpassede øyeblikksbildet.

Forhåndsvise beholderkrav

Etter at du har lagt til paneler eller individuelle biomarkører, kan du forhåndsvise de fysiske prøvebeholderne som trengs for prøvetakingen:
Arrayen containers i svaret inneholder type, navn, korkfarge, volum, produsentens artikkelnummer og antall for hver nødvendige beholder. Dette hjelper behandlere med å klargjøre riktig utstyr før blodprøvetakingen. Svaret inneholder også objektet pricing – timens samlede regning (postene som ble utløst, de tilknyttede panelene og én rad per levert biomarkør, priset etter din prisliste med utsalgspris ved siden av; se Prising), som fylles ut når timen har tilknyttede tester og nøkkelen din har scope prices_view, ellers null. routing eksponeres bevisst aldri og er alltid null.
Forhåndsvisningen gjenspeiler panelene og biomarkørene som er tilknyttet nå. Hvis du legger til eller fjerner paneler etter forhåndsvisningen, kaller du forhåndsvisningsendepunktet på nytt for å få oppdaterte beholderkrav.

Bekrefte blodprøvetakingen

Etter at blodprøven er tatt, sender du inn labkodene (strekkodene på rørene) for å utløse pipelinen for labbestillinger:
Send lab_code når én kode er trykt på hvert rør (venøs blodprøvetaking), eller lab_codes med én oppføring per kode – hver med panel_ids den dekker – når hvert panel tas i egne rør med egen kode (kapillær blodprøvetaking). Hvert panel blir da sin egen laboratorierekvisisjon under sin kode. Kodene returneres som lab_codes på timen. Ved kapillær blodprøvetaking pakkes blodprøven i mikrotainere. Paneler kommer først, i bestillingsrekkefølge. Individuelle biomarkører fyller deretter den ledige plassen i panelmikrotainerne. Når de trenger mer plass, åpner de nye mikrotainere. Vi fordeler dem jevnt. Hver mikrotainer rommer høyst 150 µl individuelle biomarkører. Kallene som endrer paneler eller biomarkører, svarer 400 når det resulterende settet bryter denne regelen. Dette endrer statusen på timen til blood_drawn og starter behandlingen på laboratoriet. Denne handlingen kan ikke angres.

Henting av forsendelse

POST /api/v1/appointments/pickup er fjernet, sammen med timestatusen shipment_picked_up. Det svarer nå 405 Method Not Allowed, fordi stien faller gjennom til ruten for time etter ID. Endepunktet fungerte i sin siste fase som en no-op som godtok kallet uten å gjøre noe, så fjerningen endrer ingen oppførsel du var avhengig av.
For å følge fremdriften etter blodprøvetakingen, følger du hver oppføring i timens innebygde array shipments til Hent forsendelse – hver forsendelse har sin egen status og en historikk i status_updates.

Koble forsendelser

En time kan være koblet til én eller flere forsendelser (og omvendt – relasjonen er mange-til-mange). De gjeldende koblingene vises direkte på begge sider:
  • på timen, som en shipments-array med { id, added_at }-oppføringer;
  • på forsendelsen, som en appointments-array med { id, added_at }-oppføringer.
Begge arrayene har eldste kobling først. Hver id kryssrefererer til det kanoniske detaljendepunktet (Hent forsendelse / Hent time) for fullstendig payload. Forsendelser kobles ved opprettelse via feltet appointment_id i Opprett forsendelse. Etter opprettelse administrerer du koblinger fra forsendelsen med Koble timer til forsendelse og Koble timer fra forsendelse; hvert endepunkt returnerer timelisten for forsendelsen etter endringen. For å lese alle pakkene til en time i sin helhet, bruker du List opp forsendelser med ?appointment_id=. Endringsregelen er: koblinger kan opprettes eller fjernes når ENTEN
  • timen er forbi blodprøvetaking (blood_drawn), eller
  • forsendelsen ble opprettet for mindre enn 24 timer siden.
Utenfor dette vinduet er koblingen låst slik at historiske oppføringer forblir stabile.

Hente labresultater

Når laboratoriet har behandlet blodprøvene, henter du kliniske og genetiske resultater:
Svaret inkluderer planlagte tester (status planned) sammen med mottatte resultater, slik at du kan følge med på hva som fortsatt gjenstår. status-feltet på toppnivå er in_progress til alle innsendinger er avsluttet, deretter completed (eller fault hvis ingen av dem rapporterte) — bruk dette for å avgjøre om timens labarbeid er ferdig. En appointment.results.completed-webhook gir deg beskjed når det skjer, slik at du ikke trenger å polle. submissions-listen deler dette opp per laboratorierekvisisjon, hver med sin lab_code. Hvert mottatte resultat og dokument har den lab_code det ble registrert under. PDF-er med labrapporter refereres i documents-listen — bruk GET /api/v1/documents/{id} for å laste dem ned.

Eksempel på time