Generelt

Det er en fordel å ha litt kunnskap om FHIR og hvordan FHIR-APIer er ment å fungerer. Her er noen nyttige lenker:

Autentisering og autorisering

For å kunne hente ut og/eller sende inn informasjon til en mottaker må følgende være på plass:

  • Man må ha en HelseID-klient med korrekte scopes og claims

  • Kommunen man ønsker å hente ut/skrive inn informasjon til må ha gitt deg tilgang

HelseID

Vi bruker HelseID til autentisering inn mot VKP. For å kunne få en HelseID-klient må man være en godkjent 3.tredjepart hos NHN. Token legges i Authorization-headeren på følgende format (Bearer Authentication):

Authorization: Bearer [jwt-token-from-HelseID]

HelseID har en del god informasjon som en bør ta en titt på for å få en overordnet forståelse av hva HelseID er.

HelseID-klienter

VKP krever at en HelseID-klient skal identifisere en (1) unik systeminstans. Dette betyr at en VFT-leverandør vil kunne ha flere klienter hvis leverandøren har sitt system i ulike kommuner. I bildet under er VFT-leverandør 2 koblet til to kommuner og har derfor da to HelseID-klienter (VFT2_Bodø og VFT2_Oslo).

Scopes

Vi bruker scopes for å bestemme hvilke API-endepunkter en avsender har tilgang til. Hvert endepunkt har et eget scope og varierer basert på om man skal lese eller skrive samt hvilken FHIR-ressurs som utveksles.

Formatet på scopet er som følger:

nhn:vkp/api/user/[FHIR-ressurs].[read|write]

For eksempel vil scopet for endepunktet for uthenting av pasientinformasjon være

nhn:vkp/api/user/patient.read

Hvis man er usikker på hvilke scope man skal bruke så finner man dette på de ulike API-operasjonene, se API-dokumentasjonen

Claims

nhn:vkp/client/claims/vkp-id

Når man får opprettet en HelseID-klient vil VKP tilegne denne klienten en intern VKP-id. Dette er for å kunne identifisere systeminstansen.

client_amr

Spesifiserer hvordan klienten ble autentisert. Denne genereres av HelseID. Må ha verdien private_key_jwt.

Tilgang til kommune

VKP har et eget autorisasjonsregister der vi har informasjon om hvilke avsendere (verdien fra nhn:vkp/client/claims/vkp-id) som har lov til å gjøre kall til hvilke mottakere (org.nr oppgitt i URL).

Adressering

Avsender

Avsender identifiseres ved hjelp av et VKP-spesifikt claim knyttet til HelseID-klienten til avsender. ID-en skal identifisere VFT-en og hvilken kommune VFT-en henter ut/sender inn informasjon på vegne av. Formatet på denne ID-en som følgende: Leverandør_System_Kommune.

Siden det er en knytning mellom system og kommune betyr det at hvis en leverandør lever en tjeneste til to kommuner må leverandøren også ha to HelseID-klienter. Se Claims under HelseID for mer informasjon.

Mottaker

Mottaker av forespørsel identifiseres ved help av [org.nr] segmentet i URLen. Organisasjonsnummer kan man finne ved hjelp av f.eks. Enhetsregisteret.

https://api.test.vkpnorge.no/epj/r4/[org.nr]/[FHIR-ressurs]

Hvis man f.eks. ønsker å hente ut pasientinformasjon fra en kommune med organsisasjonsnummer 888134574 så vil URLen se slik ut:

https://api.test.vkpnorge.no/epj/r4/888134574/patient/_search

Uthenting av informasjon fra EPJ

Søkeparametre

Av sikkerhetshensyn må alle søk gjøres ved hjelp av et POST-kall der body inneholder søkeparametre. Dette er for å redusere sannsynligheten for at personsensitiv informasjon havner i serverlogger. Parameteren må være application/x-www-form-urlencoded.

Eksempel på søkeparameter:

patient.identifier=13116900216&_include=EpisodeOfCare:Patient

Tjenestlig behov (ServiceCodes)

Ved uthenting av informasjon fra EPJ, må man definere sitt tjenstlige behov. Det vil si at man må oppgi hvilke tjenestlige behov pasientene man ønsker å hente informasjon om har. Man oppgir det tjenstlig behovet ved å oppgi en eller flere koder i ServiceCodes-headeren i forespørselen man sender. Gyldige verdier finner man her. Mottaker må også ha godkjent at du som leverandør faktisk har det tjenstlige behovet du har oppgitt. Hvis ikke vil man få en feilmelding om dette.

Journalføring

FHIR-ressursen(e) som sendes inn må være JSON-formatert. Når man sender inn en melding vil VKP validere meldingen for å sikre at den inneholder gyldig og nødvending informasjon. Hvis dette skulle feile vil man få tilbake en 400 Bad Request der bodyen inneholder en Operation Outcome med mer informasjon om hva som var feil.

For informasjon om hvordan FHIR-ressursene skal brukes, se her.

Nice-to-know

API-definisjoner

Hvis man går til på API-dokumentasjonen så kan kan man laste ned Open API-definisjoner for APIet.

Kodeeksempler

Hvis man trykker "Try it" inne på en av API-operasjonene så kan man både teste og få generert kodesnutter for operasjonen.

Vil du vite mer om Velferdsteknologisk knutepunkt, send oss en e-post.