Versions Compared

Old Version 5

changes.mady.by.user Frank Bråthen

Saved on

compared with

New Version 6

changes.mady.by.user Frank Bråthen

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
Page Properties

API-navn

FHIR timenotifikasjon

Funksjonelt område

Timeavtaler

API-versjon og dato publisert

v1

Status

Status
colourGreen
titleI Drift

API-dokumentasjon sist endret

Teknologi

Status
colourRed
titleFHIR

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

Expand
titleMapping Appointment

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

partOf.reference.identifier.system: "urn:oid:2.16.578.1.12.4.1.4.101"
partOf.reference.identifier.value: "948554062"

Ja

Behøves for å ha en unik referanse til organisasjonsressursen, men anvendes ikke (lagres ikke).

partOf.reference.display: "SiO Helse"

Ja

supportingInformation

Contained ressurs av type Location som gir oppmøtested.

supportingInformation.type: "Location"
supportingInformation.reference: #12345

Nei

address.text: "Skiringssalveien 20, Sandefjord"

Start

Start-tidspunktet

2019-06-03T08:00:00.000+01:00

Ja

End

Slutt-tidspunktet

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

Ja

Slot

Referanse til innslaget i timebok.

type: "Slot"

Nei

identifier:system: "urn:ietf:rfc:3986"
identifier.value: "c12cc3a3-56cd-4c1d-afbe-24620f6c2a94"

patientInstruction

Beskrivelse om timen som vil vises i detaljvisningen.

"Husk å utføre forberedelsene til timen før oppmøtet."

Nei

participant.actor

Logisk ressursreferanse av type Patient. Identifikatoren er fødselsnummer/d-nummer.

actor.type: "Patient"

Ja

identifier.system: "urn:oid:2.16.578.1.12.4.1.4.1"
identifier.value: "13116900216"

Ja

Slår opp ArkivId basert på fødselsnummer/d-nummer

participant.actor

Contained ressurs av typen Practitioner.

actor.type: Practitioner

Nei

name:family "Adam"

name:given: "Careful"

FHIR-profiler

Image Removed
Image AddedImage ModifiedImage Modified

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.

Code Block
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

Expand
titleExample request
Code Block
<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 https://helsenorge.atlassian.net/wiki/spaces/HELSENORGE/pages/23789578/02+-+Kall+til+Helsenorge+API+er+og+bruk+av+AcessToken

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/helsenorge-oidc-provider/v1/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.

Code Block
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

Code Block
<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 som regulerer datadeling

Begrensninger

Hvis API'et har begrensninger, feks på antall kall totalt, pr sekund, etc, så bør dette beskrives her.

Beskriv også hva som evt skjer når begrensningene nås, feks om brukeren vil få en feilmelding når den har nådd kvoten sin, samt hva brukeren da kan gjøre for å løse problemet.

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:

  1. Kontakt NHN og få autentisering

  2. Last ned Postman

  3. Send request som vist under

Code Block
Request

  1. Motta respons som vist under

Code Block
Response

  1. Du er tilkoblet endepunktet.

FAQ

  • Beskriv gjerne også vanlige problemer brukeren kan oppleve, med evt referanse til aktuelt kapittel (slik som autorisering og autentisering).

  • Hvis det er forskjeller mellom testmiljø og produksjon, utover hvilket endepunkt som benyttes, bør det også beskrives. Feks hvis det kreves ulike sertifikater, ulik type sikkerhet, etc.

Responskoder

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

Kode

Beskrivelse

200

OK. Oppdatert

201

OK. Opprettet

4xx

Feilkode i henhold til FHIR spesifikasjon 

Valideringer

Sjekk av innhold

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

Expand
titleUnable to parse content
Code Block
<OperationOutcome>
    <issue>
        <severity value="fatal"/>
        <code value="structure"/>
        <details>
            <text value="Unable to parse the content"/>
        </details>
    </issue>
</OperationOutcome>
Expand
titleRequired elements are missing
Code Block
<OperationOutcome>
    <issue>
        <severity value="fatal"/>
        <code value="required"/>
        <details>
            <text value="Required element(s) are missing"/>
        </details>
    </issue>
</OperationOutcome>
Expand
titleA content validation rule failed
Code Block
<OperationOutcome>
    <issue>
        <severity value="fatal"/>
        <code value="invariant"/>
        <details>
            <text value="A content validation rule failed"/>
        </details>
    </issue>
</OperationOutcome>

Sjekk av kildesystem

Expand
titleSjekk av kildesystem

Avsendersystem får kun lagre timenotifikasjoner som tilhører sitt kildesystem. Kildesystem er definert av Appointment.identifier-verdien no-citizenportal-client, som må matche med klientnavnet (client_name) som aktøren er registrert med i Helsenorge STS.

  • Kildesystem matcher ikke registrert systemnavn

    • lagres ikke på Helsenorge

    • HTTP 403 (forbidden) og OperationOutcome 

      • issue.severity = fatal

      • issue.Code = forbidden

      • issue.details.text = beskrivelse av feilen

Expand
titleNot allowed to generate appointments
Code Block
<OperationOutcome>
    <issue>
        <severity value="fatal"/>
        <code value="forbidden"/>
        <details>
            <text value="Not allowed to generate appointments for the defined no-citizenportal-client"/>
        </details>
    </issue>
</OperationOutcome>

Versjonering og endringer

Beskriv hvordan versjonering håndteres for API'et. Noen punkter som bør med:

  • Har de ulike versjonene forskjellig namespace? Feks blalbalba/v1/detteeretendepunkt

  • Hvor mange versjoner vil vedlikeholdes samtidig?

  • Hvor lenge vedlikeholdes gamle versjoner av API'et?

  • Hvordan varsles brukerne om endringer, nye versjoner og frafall av støtte til gamle versjoner?

Dokumentasjon av tidligere versjoner

Det gjeldende dokumentet er dokumentasjon av den nyeste versjonen av API'et. I dette avsnittet bør det ligge lenke til dokumentasjon av eventuelle tidligere versjoner av API'et.

Alternativt kan det ligge en beskrivelse av hvordan man kan se på sidehistorikk i Confluence for å finne dokumentasjon av tidligere versjoner. Det kan også være lenker her til denne sidehistorikken.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.