Table of Contents |
---|
Page Properties | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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).
title | Mapping 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
Autorisasjon
To metoder for tilgang er tilgjengelige:
HelseId sin autoriseringstjeneste for maskin-til-maskin kan benyttes:
Velg Helsenorge Ekstern API i HelseId sin selvbetjeningsløsning
Velg deretter scope “Avtaler”
Når tilgangen er godkjent av Helsenorge, kan aksesstoken hentes ut fra HelseId
API-klienten kan alternativt autentisere seg mot Helsenorge Sikkerhetstjeneste.
API-klienten må forhåndskonfigureres på Helsenorge med sin public key
API-et skal benyttes i system-til-system kontekst: 01 - System til System
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.
|
Eksempel Request
Expand | ||
---|---|---|
|
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 | |||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||
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" 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" 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" 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 |
Code Block |
|
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: 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/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.
|
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
|
|
|
|
|
|
|
|
|
|
|
|
|
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:
Kontakt NHN og få autentisering
Last ned Postman
Send request som vist under
Code Block |
---|
Request |
Motta respons som vist under
Code Block |
---|
Response |
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
title | 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.
title | Unable to parse content |
---|
Code Block |
---|
<OperationOutcome>
<issue>
<severity value="fatal"/>
<code value="structure"/>
<details>
<text value="Unable to parse the content"/>
</details>
</issue>
</OperationOutcome> |
title | Required elements are missing |
---|
Code Block |
---|
<OperationOutcome>
<issue>
<severity value="fatal"/>
<code value="required"/>
<details>
<text value="Required element(s) are missing"/>
</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 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 |
---|---|
200 | OK. Oppdatert |
201 | OK. Opprettet |
4xx | Feilkode i henhold til FHIR spesifikasjon |
Valideringer
Sjekk av innhold
Expand | ||
---|---|---|
| ||
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.
Structure - A structural issue in the content such as wrong namespace, unable to parse the content completely, invalid syntax, etc. |
Expand | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||
|
|
Expand | |||
---|---|---|---|
| |||
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.
| |||
Expand | |||
| |||
|
Expand | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||
|
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.
|
Sjekk av kildesystem
Expand | ||
---|---|---|
| ||
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.
|
Expand | |||
---|---|---|---|
| |||
|