Table of Contents |
---|
Page Properties | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
APIets formål
FinnFormidlingskanal er et API som gir informasjon om hvilke "kanaler" innbygger kan/vil motta meldinger i.
Helsenorge har støtte for å motta meldinger som skal gå til innbygger og så fordele den til rett "kanal" (Helsenorge.no, digital postkasse eller fysisk post). Logikken for å finne ut hvilken kanal meldinger kan nå innbygger i, avhenger av innbyggers innstillinger og egenskapene til meldingen som avsender vil sende. Tjenesten slår opp i flere kilder for å finne gyldig kanal, ; blant annet sjekkes aktiv-status for det aktuelle samtykkenivået på Helsenorge, status i folkeregisteret Folkeregisteret (gjelder også for barn) og innstillinger innbygger har gjort i kontaktKontakt- og - reservasjonsregisteret (reservasjonsstatus og evt. digital postkasse-adresse). Logikken er nøyere forklart her: Formidling av melding til innbygger.
For enkelte UseCases kan det være nødvendig for avsender å vite hvor meldingen vil havne før utsending, og eksterne aktører kan anvende FinnKanalvalg for å på-forhånd se hvilke kanaler "meldinger med videreformidling" ville sendt tilFinnFormidlingskanal for å finne ut hvilken kanal innbygger kan nås i.
Hvordan benytte API'et
Type API
REST
HTTP-metode POST
Autorisasjon og aksesstoken
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 “Finnformidlingskanal”
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
Finnformidlingskanal 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
Requestbody
Alle parametere er påkrevd.
Navn | Type | Lovlige verdier | Kommentar | |
---|---|---|---|---|
fodselsnummer | string | Innbyggers fødselsnummer el. d-nummer (11 siffer/tall) | Gyldig fødselsnummer eller d-nummer. | |
innholdOmfattetAvReservasjonsrett | bool | true | false | Innholdet i meldingen som skal sendes til innbygger omfattes av reservasjonsrett og må behandles deretter. Avsender må angi om innholdet de skal sende (som de gjør finn kanalvalg-kallet for) er omfattet av reservasjonsretten. I eForvaltningsforskriften §9 er beskrivelsen følgende:
FinnKanalvalg sjekker kontakt- og reservasjonsregisteret for om innbygger har reservert seg mot kommunikasjon på nett for vedtak og viktig informasjon. | |
tjenesteOmraade | int |
Volven kodeverk 7618: Her benyttes en av verdiene |
1- |
6. 1 = |
Rettigheter og selvhjelp 2 = Pasientjournal 3 = Helsehjelp 4 = Forvaltning 5 = Sekundaerbruk 6 = Ungdom | Dette representerer en logisk gruppering av tjenestene på Helsenorge. Utgangspunktet er at den eksterne klient som benytter API'et vet hvilket tjeneste område den tjeneste man selv etterpå ønsker å benytte tilhører. Dersom man er usikker må man spørre sin kontaktperson på Helsenorge |
. Beskrivelse av områdene - hva skal brukes når: |
|
|
|
|
|
|
|
|
|
Eksempler på Request
|
Respons-parametere
Alle parametere returneres alltid etter vellykket utført funksjon
Navn | Type | Lovlige verdier | Kommentar | ||
---|---|---|---|---|---|
kanalInfo | Informasjon om hvor melding vil havne hvis man sender den, gitt innbygger og innholdsegenskapene som ble definert i requesten. | ||||
primarKanal | Primærkanal er kanalen der man treffer innbygger. Hvis det ikke finnes noen gyldige kanaler der innbygger kan nås i så blir kanalen "ingen". | ||||
type | int | 0 "IN" "Ingen" | primarKanal vil inneholde en stk. av kanalene definert under lovlige verdier og vises på tre måter;
| ||
verdi | string | ||||
beskrivelse | string | ||||
sekundarKanal | Primarkanal er kanalen der innbygger nås, men i noen tilfeller kan også en "kopi" kan lagres på Helsenorge. Dette kan f.eks. skje hvis innbygger har reservert seg mot å motta informasjonen digitalt, men likevel er aktiv på Helsenorge innenfor tjenesteområdet som requesten definerer; da vil primarKanal være "fysisk post" mens sekundarKanal være "Helsenorge". Presiseringer: sekundarKanal vil alltid være "ingen" hvis primarKanal er "ingen". Hvis primarKanal er "Helsenorge" så vil sekundarKanal alltid være "ingen". | ||||
type | int | 0 "IN" "Ingen" | sekundarKanal vil inneholde en stk. av kanalene definert under lovlige verdier og vises på tre måter;
| ||
verdi | string | ||||
beskrivelse | string | ||||
httpStatusCode | int | 200 | Fast verdi, bekrefter at funksjonen kunne utføres. |
Eksempler på vellykket respons
Code Block |
---|
Eks 1: { "kanalInfo": { "primarKanal": { "type": 1, "verdi": "HN", "beskrivelse": "Helsenorge" }, "sekundarKanal": { "type": 0, "verdi": "IN", "beskrivelse": "Ingen" } }, "httpStatusCode": 200 } Eks 2: { "kanalInfo": { "primarKanal": { "type": 4, "verdi": "FP", "beskrivelse": "Fysisk post" }, "sekundarKanal": { "type": 1, "verdi": "HN", "beskrivelse": "Helsenorge" } }, "httpStatusCode": 200 } Eks 3: { "kanalInfo": { "primarKanal": { "type": 0, "verdi": "IN", "beskrivelse": "Ingen" }, "sekundarKanal": { "type": 0, "verdi": "IN", "beskrivelse": "Ingen" } }, "httpStatusCode": 200 } |
Respons ved feil
Respons ved feil
Code Block |
---|
{ "code": "SEC-110000", "message": "Token is expired or invalid : Fault code: SEC-110017", "errorCategory": 2 } |
Code Block |
---|
{ "code": "FFK-010002", "message": "Feil meldingsinnhold i request : Fault code: FFK-010002", "errorCategory": 4 } |
Autorisasjon og aksesstoken
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 (i Authorizatin header) til det enkelte API. FinnFormidlingskanal-tjenesten benyttes UseCase 1 (system-til-system) beskrevet i Sikkerhetsmodell og Helsenorge STS.
Deretter må dette AksessToken sendes med i API-kallet: https://helsenorge.atlassian.net/wiki/spaces/HELSENORGE/pages/23789578/02+-+Kall+til+Helsenorge+og+PVK+API+er+og+bruk+av+AccessToken
URL og Miljøer
<BaseUrl>/videreformidling/v1/FinnFormidlingskanal
For oversikt over BaseUrl i de forskjellige miljøer se her: Testmiljøer og endepunkter
Terms and Conditions
Vilkår og betingelser for bruk av API'etAPIet: Vilkår og betingelser for bruk av APIer og kommunikasjonsprosesser
Begrensninger
Ingen.
Testing
Oppsett av API-kliet klient i test-miljøtestmiljø(er) avtales som en del av kundeoppkoplingen
Versjonering og endringer
Dett Dette er første versjon av API’etAPIet.