/
REST Timenotifikasjon / Timer

REST Timenotifikasjon / Timer

 

Eksterne aktører sender timenotifikasjoner til Helsenorge som FHIR Appointment basert på profilen FHIR Appointment - hn-basis-appointment. Når en Appointment mottas, vurderer Helsenorge automatisk om den er ny, endret eller uendret, og innbygger varsles kun ved relevante endringer. Når innbygger åpner timen, henter Helsenorge detaljer om avtalen fra kildesystemet ved å gjøre et GET‑kall. GET returnerer alltid en FHIR Bundle som inneholder de underliggende timeavtalene (serie, paralleller eller andre relaterte avtaler) og eventuelle «contained»-ressurser, slik at Helsenorge kan vise komplett og oppdatert informasjon. Hvis innbygger bekrefter eller avbestiller timen, sender Helsenorge dette tilbake som en AppointmentResponse, som peker på den aktuelle timen og angir hvilken handling innbygger har gjort. Kildesystemet må motta og prosessere denne responsen og oppdatere timeboken deretter.

API-navn

FHIR timenotifikasjon

Funksjonelt område

Timeavtaler

API-versjon og dato publisert

v1.0.1 Dec 2, 2025

Status

I Drift

API-dokumentasjon sist endret

Jan 9, 2026

Teknologi

REST FHIR HelseId.jpg

Innholdsfortegnelse

 

Hvordan benytte API'et

Autorisasjon

API’et bruker maskin‑til‑maskin‑autorisasjon via HelseID:

  1. Velg Helsenorge Ekstern API i HelseID sin selvbetjeningsløsning.

  2. Velg scope “Avtaler”.

  3. Når tilgang er godkjent av Helsenorge, kan aksesstoken hentes fra HelseID.

  4. Token skal sendes i Authorization‑header i alle HTTP‑kall.

Mer informasjon:

Miljøer

Struktur på URL'er: https://<miljø>/timeavtaler-fhir/api/<versjon>/Appointment

Oversikt over tilgjengelige miljøer finnes her: Testmiljøer og endepunkter

Endepunkt og metoder

PUT Appointment

Brukes for innsending / oppdatering av timenotifikasjon.

Krav:

  • Body må være FHIR Appointment

  • meta.profile må være
    http://helsenorge.no/fhir/StructureDefinition/hn-basis-appointment

FHIR-profil: FHIR Appointment - hn-basis-appointment

Eksempel Request

Eksempel på Appointment

Eksempel Response

Se Responskoder: https://helsenorge.atlassian.net/wiki/x/PIDISg

GET

GET brukes av Helsenorge når innbygger åpner timen.
Formålet er å hente mer detaljer om timen fra EPJ.

Spørring er på identifer for timenotifikasjonen og benytter _revinclude https://hl7.org/fhir/R4B/search.html#revinclude

GET returnerer en FHIR Bundle som inneholder:

  • den underliggende avtalen (selve kliniske timen / paralleltimer / serieelementer)

  • eventuelle contained resources

Eksempel Request

GET {FHIR endepunkt}/Appointment?_revinclude=Appointment:ApartOf&_profile=StructureDefinition-hn-basis-appointment&identifier={identifier.system}/{identifier.value}/{identifier.assigner}

Eksempel Response

Legg spesielt merke til bruk av ‘contained’ ressurser: https://helsenorge.atlassian.net/wiki/x/AYBQv

Autentisering

Token: Uthenting av token gjøres fra STS, for informasjon se: 3. Ekstern applikasjon kaller Helsenorge API i systemkontekst . For bruk av aksesstoken i etterfølgende kall se: 2. Ekstern innbyggerløsning kaller Helsenorge API i innbyggerkontekst

Offentlig sertifikat kan anvendes for avsender til å validere tokenet fra Helsenorge sin STS-tjeneste.
Eksempel for mas-02: https://eksternapi-hn-mas-02.int-hn.nhn.no/sts/oidcprov/v3/jwk

Endepunktet har krav om at aktøren som utfører spørringen har sikkerhetsbillett/token utstedt fra Helsenorge sin STS-tjeneste.  

Legg inn eksempel på kode for hvordan man gjør autentiseringen

Autorisering

For å kunne kalle endepunktet så behøves et token utstedt fra vår STS, med scope "avtaler".

  • Token mangler eller ikke er gyldig

    • lagres ikke på Helsenorge

    • HTTP 401 (unauthorized) og OperationOutcome 

      • issue.severity = fatal

      • issue.Code = forbidden

      • issue.details.text = beskrivelse av feilen

<OperationOutcome> <issue> <severity value="fatal"/> <code value="forbidden"/> <details> <text value="Not authorized to access this end point"/> </details> </issue> </OperationOutcome>

Terms and Conditions

Vilkår og betingelser for bruk av API'et kan finnes her: Vilkår og betingelser for bruk av APIer og kommunikasjonsprosesserarchived

Forutsetning:
Kildesystemets FHIR‑endepunkt må være registrert i Adresseregisteret.

Responskoder

Beskriv her hvilke feilmeldinger brukeren kan få og hva de betyr

Kode

Beskrivelse

Kode

Beskrivelse

200

OK. Oppdatert

201

OK. Opprettet

4xx

Feilkode i henhold til FHIR spesifikasjon. Legg spesielt merke til bruk av 409  ved konflikt der eldre versjon av ressursen er mottatt

Valideringer

Innholdsvalidering

Helsenorge verifiserer:

Validering av kildesystem

  • Kildesystemet må ha lov til å lagre timenotifikasjon

  • GET krever registrert FHIR‑endepunkt i adresseregisteret