1 APIets formål
2 Hvordan benytte API'et
- 2.1 Type API
3 Autorisasjon og aksesstoken
- 3.1 Requestbody
  - 3.1.1 Eksempler på Request
- 3.2 Respons-parametere
  - 3.2.1 Eksempler på vellykket respons
  - 3.2.2 Respons ved feil
  - 3.2.3 Respons ved feil
- 3.3 URL og Miljøer
- 3.4 Terms and Conditions
- 3.5 Begrensninger
- 3.6 Testing
4 Versjonering og endringer

API-navn	FinnFormidlingskanal
Funksjonelt område	Formidling av melding/brev til innbygger
API-versjon og dato publisert	v1 May 10, 2022
Status	I Drift
API-dokumentasjon sist endret	Mar 14, 2024
Teknologi	REST

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

To metoder for tilgang er tilgjengelige:

HelseId sin autoriseringstjeneste for maskin-til-maskin kan benyttes:
1. Velg Helsenorge Ekstern API i HelseId sin selvbetjeningsløsning
2. Velg deretter scope “Finnformidlingskanal”
3. Når tilgangen er godkjent av Helsenorge, kan aksesstoken hentes ut fra HelseId
API-klienten kan alternativt autentisere seg mot Helsenorge Sikkerhetstjeneste.
1. API-klienten må forhåndskonfigureres på Helsenorge med sin public key
2. Finnformidlingskanal skal benyttes i system-til-system kontekst: 01 - System til System
3. 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: 02 - Kall til Helsenorge og PVK API'er og bruk av AccessToken

Requestbody

Alle parametere er påkrevd.

Navn		Type	Lovlige verdier	Kommentar

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:

enkeltvedtak
forhåndsvarsel etter forvaltningsloven § 16
andre meldinger som har betydning for vedkommendes rettsstilling eller for behandlingen av saken, og
meldinger som det av andre grunner er av særlig betydning å sikre at vedkommende mottar

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:

Rettigheter og selvhjelp – Brukes for informasjon og tjenester knyttet til selvhjelp samt de rettigheter innbyggere har knyttet til personvern, for eksempel innsyn og øvrige personverntjenester i ulike registre mm.
Pasientjournal – brukes for informasjon og tjenester knyttet til innbyggers personvernrettigheter i pasientjournal
eks: besvare innsynsforespørsler
Helsehjelp – brukes for informasjon og tjenester knyttet til innbyggers direkte behandling, helsehjelp og forebygging og hvordan videre behandlingsløp, oppfølging og informasjon skal håndteres eks: sende oppgaver, timeavtaler eller annet til innbygger ifm. pasientforløp
Forvaltning – brukes for informasjon og tjenester knyttet til helseforvaltning og helseøkonomiforvaltning
eks: sende ut vedtak
Sekundærbruk – brukes for informasjon og tjenester knyttet til forskning, helseundersøkelser og annen sekundærbruk eks: invitere til deltakelse og sende ut informasjon fra forskningsprosjekter og helseundersøkelser. Det tas hensyn til eventuell reservasjon innbygger har gjort mot at Helsenorge benyttes som kanal for slike henvendelser.
Ungdom - brukes for informasjon og tjenester som ungdommen selv kan velge å ta i bruk, uten at foreldre må samtykke til det, ut i fra GDPR og helselovgivningen eks: gi informasjon til ungdom om skolehelsetjenesten.

Eksempler på Request

{ "fodselsnummer": "13116900216", "innholdOmfattetAvReservasjonsrett": true, "tjenesteOmraade": 1 }

{
  "fodselsnummer": "13116900216",
  "innholdOmfattetAvReservasjonsrett": false,
  "tjenesteOmraade": 5
}

Respons-parametere

Alle parametere returneres alltid etter vellykket utført funksjon

Navn			Type	Lovlige verdier	Kommentar

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" 1 "HN" "Helsenorge" 2 "EB" "eboks" 3 "DP" "Digipost" 4 "FP" "Fysiskpost"	primarKanal vil inneholde en stk. av kanalene definert under lovlige verdier og vises på tre måter; type - enum/int verdi verdi - verdi fra Volven-kodeverket 7616, som er anvendt i meldingstypen "Leveringsrapport" "beskrivelse" - menneskelig lesbar verdi
		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" 1 "HN" "Helsenorge"	sekundarKanal vil inneholde en stk. av kanalene definert under lovlige verdier og vises på tre måter; type - enum/int verdi verdi - verdi fra Volven-kodeverket 7616, som er anvendt i meldingstypen "Leveringsrapport" "beskrivelse" - menneskelig lesbar verdi
		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

{
  "code": "SEC-110000",
   "message": "Token is expired or invalid : Fault code: SEC-110017",
   "errorCategory": 2
}

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.

Finn formidlingskanal

APIets formål

Hvordan benytte API'et

Type API

Autorisasjon og aksesstoken

Requestbody

Eksempler på Request

Respons-parametere

Eksempler på vellykket respons

Respons ved feil

Respons ved feil

URL og Miljøer

Terms and Conditions

Begrensninger

Testing

Versjonering og endringer