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 |
Figur 5 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".
Figur 6 API-kall må være aktivert i klientsystemet som skal benytte Meldingstjener ved API (brukerpålogging kan også være aktivert).
Figur 7 Eksempel som viser et klientsystem med Meldingstjener konfigurert som et støttet API.
Det må så opprettes en klient_konfigurasjon 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.
Figur 8 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.