|
Digital postkasse vil ikke gis som respons som formidlingskanal etter 9.4.2025. Se Pause bruk av digital postkasse for brevtjenesten for detaljer |
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 (gjelder også for barn) og innstillinger innbygger har gjort i Kontakt- 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 FinnFormidlingskanal for å finne ut hvilken kanal innbygger kan nås i.
Hvordan benytte API'et
Type API
REST
HTTP-metode POST
Autorisasjon og aksesstoken
HelseId sin autoriseringstjeneste for maskin-til-maskin skal 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
Se ytterligere detaljer her: 3. Ekstern applikasjon kaller Helsenorge API i systemkontekst
AksessToken som mottas fra HelseId eller Helsenorge STS skal deretter være med i Authorization header i alle HTTP-requestene. Se: 2. Ekstern innbyggerløsning kaller Helsenorge API i innbyggerkontekst
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
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": "SEC-110000",
"message": "Token is expired or invalid : Fault code: SEC-110017",
"errorCategory": 2
} |
{
"code": "FFK-010002",
"message": "Feil meldingsinnhold i request : Fault code: FFK-010002",
"errorCategory": 4
} |
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 APIet: Vilkår og betingelser for bruk av APIer og kommunikasjonsprosesser
Begrensninger
Ingen.
Testing
Oppsett av API-klient i testmiljø(er) avtales som en del av kundeoppkoplingen
Versjonering og endringer
Dette er første versjon av APIet.