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.

Fordeler med API'et

Alternativet til å bruke dette API'et er at man ikke har noen integrasjon mellom EPJ/Timeløsning og Helsenorge for pasientens timer.

Hvordan benytte API'et

Type API

REST

Miljøer

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

Oversikt over tilgjengelige miljøer finnes her: Miljøer

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 (som også inneholder støtteinformasjonen som behøves for kalenderobjektet til timen).

Appointment-attributt

Beskrivelse

Eksempel

Påkrevd

Logikk

Extension

Cancel
_{Valgfritt felt i FHIR-extension communicationoptions, som kan anvendes på timen.}

True

Nei

Et ja her gir funksjonalitet/knapp for å kansellere timen.

CancelTimeUntil
^{(krever at Cancel er true)}
NB: ikke i bruk enda

_{Valgfritt felt i FHIR-extension communicationoptions, som kan anvendes på timen.}

2019-06-02T08:30:00.000+01:00

Nei

Sjekkes først hvis Cancel er true. Gir tidspunktet for når timen ikke lengre skal være mulig å kansellere (for eksempel en dag før timen).

Identifier

Timeidentifikator i avsenders system
(no-citizenportal-instanceidentifier)
_{Anvendes for å unikt identifisere timer}
^{Anvendes i spørringer}

3546c8f7-3cd3-4693-929e-66501642504c

Ja

Identifier

Id for underliggende system/tjeneste som
leverer timeavtalen
(no-citizenportal-sourcesystem)
^{Anvendes i spørringer}

1 15-3fb9c0f4-1d9b-44b6-8d64-d36820115274

Ja

Identifier

Id for aktør som leverer dataene
(no-citizenportal-client)
^{Anvendes i spørringer
Kan anvendes for å finne endepunkt
dersom ytterligere detaljer om timen skal hentes.}

Opus

Ja

Ved mottak valideres denne verdien (timens aktør/kilde) opp mot systemet som kaller APIet (hentes fra token)

Status

Status på timen

"booked", "cancelled", "entered-in-error"

Ja

Mapper alle statusene vi får over til AvtaleStatusId (sjekk også AppointmentStatus)
booked = 2 (ReservertBekreftet) 
cancelled = 5 (AvbestiltBekreftet)
entered-in-error = 14 (Feilregistrering)

serviceCategory

Timens tjenestekategori

10 (Dental)
27 (Specialist Medical)
17 (General Practice)
7 (Community Health Care)

Nei

Mappes over til motparttype-verdien.
10 (Dental) mappes over til motparttype 11 (Primarhelsetjeneste).
Defaulter til "Primarhelsetjeneste".

appointmentType

Timetype fra kodeverk 7617 - "Timetype innbyggerportal"

"Ordinær", "Hastetime", "Video"

Nei

Mappe appointmentType til AvtaleTypeId.
Ordinær = NULL (ingen verdi gir GUI-verdi "Time")
Hastetime = 11 (Hastetime)
Video = 10 (Video).
Defaulter til "Ordinær".

description

Beskrivelse av timen/timen gjelder

"Oppfølging av kontrolltime"

Nei

supportingInformation

Contained ressurs av type Organization. Definerer tjenesten, og har referanse til organisasjonen.

Identifier definerer HerId-nivå 2
Name definerer tjenestenavnet

partOf.reference.identifier definerer Organisasjonsnummeret
partOf.reference.display definerer organisasjonsnavnet

supportingInformation.type: "Organization"
supportingInformation.reference: #54321

Ja

identifier.system: "urn:oid:2.16.578.1.12.4.1.2"
identifier.value: "140890"

Nei

name: "Allmen tannhelse"

Ja

partOf.reference.type: "Organization"

Ja

Autorisasjon

To metoder for tilgang er tilgjengelige:

1. 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

2. 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: https://helsenorge.atlassian.net/wiki/spaces/HELSENORGE/pages/23789578/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

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

Nei

Nei

Nei

FHIR-profiler

<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.