Meldingstjener API
Her beskrives underlaget for å ta i bruk Meldingstjener API, inkludert forberedelser i Adresseregisteret og HelseID selvbetjening, referanser til HelseID kode-eksempler og utvidede beskrivelser av de tilgjengelige API-endepunktene.
Overordnet beskrivelse
Meldingstjener REST API-et tilbyr endepunkter for sending, mottak, kvitering og statussjekk for standardiserte meldinger.
API-definisjonen finnes også her.
Forberedelser i Adresse-registeret
For å sende meldinger gjennom API-et må Meldingstjeneren ta over meldingstjener-ansvaret fra API-brukeren. Det vil si at Meldingstjeneren må kunne hente meldinger fra og sende meldinger til EDI på vegne av API-brukeren. For å unngå en uhåndterlig mengde EDI-adresser, vil derfor EDI-adressen til API-brukere byttes ut med Meldingstjenerens. Det samme gjelder krypterings- og signeringssertifikater.
EDI-addresser og sertifikater varierer per miljø. Ulike innslag i addresseregisteret knyttet til ulike miljøer, må i utgangspunktet endres på en slik måte at hver av dem knyttes til den korresponderende Meldingstjener-instansen i riktig miljø. Meldingstjenerens test-miljø er lagt opp til å kommunisere over test-EDI, mens prod-miljøet kommuniserer over "vanlig" EDI.
| Miljø | Adresseregister-miljø | Adresse |
|---|---|---|
| Test | https://register-web.test.nhn.no/ar | meldingstjener-api@testedi.nhn.no |
| Produksjon | https://register.nhn.no/Ar | meldingstjener-api@edi.nhn.no |
Eksempel på endringer i (test-)Adresseregisteret knyttet til vårt testmiljø per 14. oktober 2024.
Forberedelser i HelseID selvbetjening
For å kunne sende og motta meldinger (/Messages-endepunktene) må klienten autentisere seg med HelseID. Man må derfor opprette et klientsystem med HelseIDs selvbetjening (under "dine klientsystemer" i sidemenyen). Det må hukes av for å tillate "API-kall" under siden "Autentiseringsvalg". Etter at klientsystemet har blitt opprettet, må "Meldingstjener REST API" (med audience "msh:nhn") legges til under "Støttede API-er og scopes".
API-kall må være aktivert i klientsystemet som skal benytte Meldingstjener ved API (brukerpålogging kan også være aktivert).
Eksempel som viser et klientsystem med Meldingstjener konfigurert som et støttet API.
Det må så opprettes en klientkonfigurasjon fra klientsystemet. Når en klientkonfigurasjon opprettes, må det oppgis en eller flere Her-ID-er i et api-spesifikt claim. Her-ID-ene som oppgis må være underenheter av organisasjonen som claimet tilhører, og dette valideres som en del av autentiseringen rundt API-et. Hvis man ikke ønsker å avgrense til bestemte Her-ID-er, kan man oppgi 0 i feltet, som vil tolkes som "tilgang til alt virksomheten har tilgang til" basert på organisasjonsnummeret som automatisk er en del av claimet.
Eksempel på en klientkonfigurasjon i HelseID selvbetjening, som benytter Meldingstjener SHP REST Test klient som klientsystem. Denne klientkonfigurasjonen er scopet til HerId 8142092 gjennom et api-spesifikt claim.
Denne konfigurasjonen vil gi API-brukeren de delene med informasjon som trengs for å be om et accesstoken. I hovedsak en klient-Id og en nøkkel som kan lastes ned. For å be om et accesstoken har HelseID tilgjengeliggjort en del eksempel-kode. Denne kan nås her: https://github.com/NorskHelsenett/HelseID.Samples.
API-et bruker client credentials, som betyr at det er klienten som autentiseres, og ikke en pålogget bruker.
Klientsystemer i HelseID opprettes i testmiljøet for selvbetjening, og produksjonssettes fra en meny på den siden.
Eksempel som viser menyen for produksjonssetting av en klientkonfigurasjon i HelseID selvbetjening testmiljø.
> Merk at det kreves sikkerhetsdokumentasjon og kodegjennomgang med HelseID-representanter som en del av løpet for produksjonssetting av et klientsystem. Det må påregnes noe ventetid for planlegging og gjennomføring av kodegjennomgang. Vårt beste og høyst uoffisielle estimat er 2-4 uker.