1 API'ets formål
2 Hvordan benytte API'et
- 2.1 Type API
- 2.2 Autorisasjon
- 2.3 Miljøer
- 2.4 Metoder og parametre til endepunktet
  - 2.4.1 PUT
  - 2.4.2 Eksempel Request
  - 2.4.3 Eksempel Response
- 2.5 Swagger
- 2.6 Autentisering
- 2.7 Autorisering
- 2.8 Terms and Conditions
- 2.9 Begrensninger
- 2.10 Quick Start på å jobbe mot endepunktet
3 Responskoder
- 3.1 Valideringer
  - 3.1.1 Sjekk av innhold
  - 3.1.2 Sjekk av kildesystem
4 Versjonering og endringer

API-navn	FHIR timenotifikasjon
Funksjonelt område	Timeavtaler
API-versjon og dato publisert	v1 Mar 10, 2021
Status	I Drift
API-dokumentasjon sist endret	Jul 4, 2022
Teknologi	REST FHIR

API'ets formål

Timenotifikasjon gir mulighet til å sende innbygger en notifikasjon om ny eller endret avtale. Eksterne aktører kan anvende Helsenorge's FHIR-endepunkt for å levere/synkronisere basisinformasjon om avtaler til innbyggere som er aktive på Helsenorge.

Helsenorge er ikke kildesystem for disse timene og i første omgang vil ikke Helsenorge tilby et endepunkt som støtter spørring/uthenting av timeinformasjonen som er lagret. Avsender/kildesystemet må dermed holde status på oversendte timer, og eventuelt overføre timenotifikasjoner på nytt hvis det er tvil om timer er synkronisert eller en innbygger blir digitalt aktiv. Helsenorge sitt endepunkt vil vite om innslaget er ny time (ikke sett før), en allerede overført time som har blitt endret siden sist overføring, eller identisk time (ingen endringer siden sist overføring), og vil kun varsle innbygger om relevante endringer.

Hvordan benytte API'et

Type API

REST

Autorisasjon

To metoder for tilgang er tilgjengelige:

HelseId sin autoriseringstjeneste for maskin-til-maskin kan benyttes:
1. Velg Helsenorge Ekstern API i HelseId sin selvbetjeningsløsning
2. Velg deretter scope “Avtaler”
3. Når tilgangen er godkjent av Helsenorge, kan aksesstoken hentes ut fra HelseId
API-klienten kan alternativt autentisere seg mot Helsenorge Sikkerhetstjeneste.
1. API-klienten må forhåndskonfigureres på Helsenorge med sin public key
2. API-et skal benyttes i system-til-system kontekst: 01 - System til System
3. Deretter kan API-klienten få utsedt et AksessToken fra Helsenorge STS.

AksessToken som mottas fra HelseId eller Helsenorge STS skal deretter være med i Authorization header i alle HTTP-requestene. Se: 02 - Kall til Helsenorge og PVK API'er og bruk av AccessToken

Miljøer

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

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

Metoder og parametre til endepunktet

En liste over hvilke metoder som kan brukes til endepunktet, samt tabeller som sier hvilke parametre med tilhørende gyldige verdier som kan brukes pr metode. Beskriv også hva den enkelte metode generelt vil gi i respons når den brukes på endepunktet og når den brukes med ulike parametre.

PUT

Innholdet (body) må være av typen FHIR Appointment.

Dette er FHIR-profilene som benyttes på Helsenorge:

Timenotifikasjon - FHIR v0.9 : Brukes ifm integrasjon mot Helseplattformen/Epic

Headeren If-None-Exist, sammen med en søkeparameter, må legges ved PUT-kallet. Dette sikrer støtte for både opprettelse og endring av timer. Vi støtter ikke PUT uten denne headeren eller POST.

identifier=no-citizenportal-client|klientnavn&identifier=no-citizenportal-sourcesystem|systemnavn&identifier=no-citizenportal-instanceidentifier|timeidentifikator&participant.actor:Patient=urn:oid:2.16.578.1.12.4.1.4.1|fødselsnummer

Eksempel Request

<Appointment xmlns="http://hl7.org/fhir">
    <meta>
        <profile value="http://ehelse.no/fhir/StructureDefinition/hn-primary-appointment" />
    </meta>
    <contained>
        <Location>
            <meta>
                <profile value="http://ehelse.no/fhir/StructureDefinition/hn-primary-appointment_containedlocation" />
            </meta>
            <id value="containedLocation" />
            <address>
                <!-- Oppmøtested -->
                <text value="Skiringssalveien 20, Sandefjord" />
            </address>
        </Location>
    </contained>
    <contained>
        <Organization>
            <meta>
                <profile value="http://ehelse.no/fhir/StructureDefinition/hn-primary-appointment_containedorganization" />
            </meta>
            <id value="containedOrganization"/>
            <identifier>
                <!-- Tjeneste-identifiaktor - HER-id nivå 2 = -->
                <system value="urn:oid:2.16.578.1.12.4.1.2" />
                <value value="1494" />
            </identifier>
            <!-- Visningsnavn tjeneste -->
            <name value="Allmen tannlege"/>
            <partOf>
                <type value="Organization" />
                <identifier>
                    <!-- Organisasjonsnummer -->
                    <system value="urn:oid:2.16.578.1.12.4.1.4.101" />
                    <value value="948554062" />
                </identifier>
                <!-- Visningsnavn organisasjon -->
                <display value="Sio Helse"/>
            </partOf>
        </Organization>
    </contained>
    <contained>
        <Practitioner>
            <meta>
                <profile value="http://ehelse.no/fhir/StructureDefinition/hn-primary-appointment_containedpractitioner" />
            </meta>
            <id value="containedPractitioner"/>
            <name>
                <family value="Careful"/>
                <given value="Adam"/>
                <prefix value="Dr"/>
            </name>
        </Practitioner>
    </contained>
    <extension url="http://ehelse.no/fhir/StructureDefinition/hn-primary-appointment_extension-communicationoptions">
        <extension url="Cancel">
            <valueBoolean value="true" />
        </extension>
        <extension url="CancelTimeUntil">
            <valueDateTime value="2019-08-01T08:00:00+02:00" />
        </extension>
    </extension>
    <identifier>
        <system value="http://ehelse.no/fhir/CodeSystem/no-citizenportal-instanceidentifier" />
        <value value="203" />
    </identifier>
    <identifier>
        <system value="http://ehelse.no/fhir/CodeSystem/no-citizenportal-sourcesystem" />
        <value value="16-3fb9c0f4-1d9b-44b6-8d64-d36820115274" />
    </identifier>
    <identifier>
        <system value="http://ehelse.no/fhir/CodeSystem/no-citizenportal-client" />
        <value value="Opus" />
    </identifier>
    <!-- booked/cancelled/entered-in-error -->
    <status value="booked" />
    <serviceCategory>
        <coding>
            <system value="http://hl7.org/fhir/ValueSet/service-category" />
            <code value="10" />
            <display value="Dental" />
        </coding>
    </serviceCategory>
    <appointmentType>
        <coding>
            <system value="urn:oid:2.16.578.1.12.4.1.1.7617" />
            <code value="Ordinær" />
            <display value="Ordinær time" />
        </coding>
    </appointmentType>
    <!-- Timens emne/subject -->
    <description value="Oppfølging av kontrolltime" />
    <supportingInformation>
        <type value="Organization" />
        <reference value="#containedOrganization" />
    </supportingInformation>
    <supportingInformation>
        <type value="Location" />
        <reference value="#containedLocation" />
    </supportingInformation>
    <start value="2019-08-03T08:00:00+02:00" />
    <end value="2019-08-03T08:30:00+02:00" />
    <!-- Timens beskrivelse -->
    <patientInstruction value="Husk å utføre forberedelsene til timen før oppmøtet." />
    <slot>
        <type value="Slot" />
        <identifier>
            <system value="urn:ietf:rfc:3986" />
            <value value="c12cc3a3-56cd-4c1d-afbe-24620f6c2a94" />
        </identifier>
    </slot>
    <participant>
        <actor>
            <type value="Patient" />
            <identifier>
                <!-- FNR/d-nummer -->
                <system value="urn:oid:2.16.578.1.12.4.1.4.1" />
                <value value="13116900216" />
            </identifier>
        </actor>
        <required value="required" />
        <status value="accepted" />
    </participant>
    <participant>
        <actor>
            <type value="Practitioner" />
            <reference value="#containedPractitioner" />
        </actor>
        <required value="required" />
        <status value="accepted" />
    </participant>
</Appointment>

Eksempel Response

Se Responskoder.

Swagger

Sett inn link til Swagger-dokumentasjon.

Autentisering

Token: Uthenting av token gjøres fra STS, for informasjon se: 01 - System til System . For bruk av aksesstoken i etterfølgende kall se: 02 - Kall til Helsenorge og PVK API'er og bruk av AccessToken

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. I tillegg må timens verdi for identifikator no-citizenportal-client stemme overens med client_name i sikkerhetsbilletten (client_name-verdien settes når tilgangen opprettes i STS), se kapittel "Respons fra helsenorge.no" - "Sjekk av kildesystem" under.

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

Terms and Conditions

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

Begrensninger

Ved behov for større datamigreringer skal Helsenorge varsles i forkant og tidspunkt avtales via kundesenter@nhn.no

Quick Start på å jobbe mot endepunktet

Eksempel på hvordan raskt komme i gang med bruk av API'et, feks med Postman eller lignende. Inkluder også eksempel på en enkel request og response:

Kontakt NHN og få autentisering
Last ned Postman
Send request som vist under

Motta respons som vist under

Du er tilkoblet endepunktet.

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

Valideringer

Sjekk av innhold

Ved mottak av timenotifikasjoner verifiseres det at at Appointment-objektet inneholder den påkrevde FHIR-informasjonen, timeobjektet må ha status booked, cancelled eller entered-in-error.

Innhold validerer ikke
- lagres ikke på Helsenorge
- HTTP 400 (bad request) og OperationOutcome
  - issue.severity = fatal
  - issue.Code = structure/required/invariant (se issue type)
  - issue.details.text = beskrivelse av feilen

Structure - A structural issue in the content such as wrong namespace, unable to parse the content completely, invalid syntax, etc.

REST Timenotifikasjon