Table of Contents |
---|
Page Properties | |||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Metodens formål
Metoden kan brukes av eksterne aktører for å undersøke om en bestemt innbygger er aktiv på Helsenorge eller ikke. Basert på svaret, kan det eksterne systemet vurdere om det kan og bør kommunisere med innbyggeren via Helsenorge og/eller om det må benytte alternative kanaler. Dersom formålet er å lagre innbyggers digitale status i eget system bør metoden bare benyttes etter at metoden DigitaltAktivStatusEndringer først er benyttet.
benytte API'et
Detaljert dokumentasjon av metoden
Autentisering og autorisasjon
Alle API’er krever at klienten på forhånd har autentisert seg mot vår Sikkerhetstjeneste og fått utstedt et aksesstoken som skal være med i tjenestekallene til det enkelte API. DigitalAktiv tjenesten krever ikke at kallet utføres i context av en innlogget bruker dvs. UseCase 1 (system-til-system) beskrevet her kan benyttes: 01 - System til System
Type API
REST
HTTP verb
Det skal benyttes POST og alltid https.
For å unngå at innbyggers fødselsnummer er en del av parameterne i URL’en, og dermed vil vises i browser-historikk, benyttes alltid POST med parametere i requestens body.
Request
Plassering | Navn | Type | Beskrivelse |
---|---|---|---|
Header | Authorization: bearer {access-token} | - | Aksess token som klienten fikk fra Helsenorge sikkerhetstjeneste etter å ha autentisert/autorisert seg mot denne. |
Content-Type | application/json | Parametere i body er JSON | |
Body | fnr | string | Innbyggers fødselsnummer el. d-nummer (11 siffer) |
omraade | int | Lovlige verdier (kun en av verdiene): 1 (Helseregister 2 (Pasientjournal) 3 (Helsehjelp 4 (Forvaltning) 5 (Sekundærbruk) 6 (Ungdom, nytt område for ungdom mellom 12-16 år)) (Disse verdiene |
er registrert i Volven kodeverk, 7618) Beskrivelse: Beskrivelse av områdene - hva skal brukes når:
|
Response
Plassering | Navn | Type | Beskrivelse |
---|---|---|---|
Body | erDigitalAktivSelv | boolean | Denne vil være satt dersom innbygger er digitalt aktiv selv. NB! Et barn < 16 år vil aldri kunne være digital aktiv selv (foreløpig, men dette vil nok komme etter hvert) |
erDigitalAktivViaAndre | boolean | Denne vil være satt dersom innbygger er digitalt aktiv via andre, dvs det finnes minst en annen person som kan representere innbyggeren. Dette kan være ved foreldrerepresentasjon (hvis barn < 16 år) eller ved fullmakt. |
Swagger
https://eksternapi-hn-mas-02.int-hn.nhn.no/digitaltaktiv/swagger/index.html
Miljøer
Standard for hvordan URL’en til API’et vil se ut i alle miljøene: https://<miljø>/DigitaltAktiv/api/<versjon>/DigitaltAktivOmraade
Oversikt over tilgjengelige miljøer finnes her: Miljøer Testmiljøer og endepunkter
Terms and Conditions
Vilkår og betingelser for bruk av API'et. Generell oversikt over alle vilkår finnes her: Vilkår og betingelser som regulerer datadelingfor bruk av APIer
Beskriv eventuelle ytterligere detaljer her.
BegrensningerHvis 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
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:
Code Block |
---|
Request |
Code Block |
---|
Response |
Testing
Beskriv hvordan brukeren kan teste at de kan benytte endepunktet, samt hvilket av miljøene som skal benyttes til dette formålet.
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.Quick Start
Request (eks.)
Header:
Body:
|
Response (eks.)
Body:
|
Feilmeldinger
Beskriv her hvilke feilmeldinger brukeren kan få og hva de betyr
Kode | Beskrivelse |
---|---|
200 | Alt OK |
400 | Validering av request feiler |
401 | Autorisasjon er feil eller mangler |
403 | Tilganger mangler |
422 | Kan aldri bli digital aktiv, fnr finnes ikke i våre registere (fra release august 2021) |
500 | Midlertidig feil, prøv igjen senere (fra release august 2021) |
Ved HTTP-statuskoder som tilsier at det har oppstått en feil returneres også en respons med feilkode og feilmelding.
Eks:
Code Block | ||
---|---|---|
| ||
{ "Code": "SEC-110000", "Message": "Token is expired or invalid"} |
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.