Slik bruker man APIene

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

  • Man må opprette en API-bruker og hente ut en api-nøkkel 

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 må bør ta en titt på for å få en overordnet forståelse om 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 bilde under er VFT-leverandør 2 koblet til to kommuner og har derfor da to HelseID-klienter (VFT2_Bodø og VFT_Oslo).

Picture

Scopes

Vi bruker scopes for å bestemme hvilke APIer en avsender har tilgang til. Hvert endepunkt har et eget scope og varierer basert på om man skal lese eller skrive samt hvilke 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
 eller  
nhn:vkp/api/user/patient.*

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

Picture

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 

Spesifisere hvordan klienten ble autentisert. Denne genereres av HelseID. Må ha verdi private_key_jwt. Les mer her.

e-helse/claims/her_id - brukes kun i STU3-apiene

VKP krever at man presenter et claim som inneholder HER-iden som er knyttet opp mot klienten din.

Tilgang til kommune

VKP har et eget autorisasjonsregister der vi har informasjon om hvilke avsender (Verdien fra e-helse/claims/her_id(STU3) eller nhn:vkp/client/claims/vkp-id) som får lov til å gjøre kall til hvilke mottakere (Verdien fra URL, HER-id(STU3) og org.nr(R4)). 

Adressering

Vi har gjort endring på hvordan adresseringen fungerer for R4-APIene. Dette var for å prøve å gjøre ting mer forståelig og redusere det administrative arbeidet.

For R4-API-ene

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 orgNr 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 ø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

FOR STU3-APIene

Avsender

Avsender identifiseres ved hjelp av et HER-id claim knyttet til HelseID-klienten til avsender. HER-iden skal identifisere VFTen og hvilke kommune VFTen henter ut/sender inn informasjon på vegne av. Det vil si at hvis en leverandør lever en tjeneste til to kommuner må han også ha to HelseID-klienter. Se Claims under HelseID for mer informasjon.

Mottaker 

Mottaker av forespørsel identifiseres ved help av HER-id segmentet i URLen. 

https://api.test.vkpnorge.no/v1/epj/[HER-id]/[FHIR-ressurs]

Hvis man ønsker å hente ut pasientinformasjon fra HER-id 8134574 så vil URLen se slik ut:

https://api.test.vkpnorge.no/v1/epj/8134574/patient/_search

Uthenting av EPJ-informasjon

Søkeparametere

Av sikkerhetshensyn så må alle søk gjøres ved hjelp av et POST-kall der body inneholder søkeparametere. Dette er for å minske sannsynligheten for at personsensitiv informasjon vil havne i serverlogger. Parmateren må være application/x-www-form-urlencoded formatert

Eksempel på søkparamter:

patient.identifier=13116900216&_include=EpisodeOfCare:Patient

Tjenstlig behov (ServiceCodes)

Ved uthenting av epj-informasjon må man definere sitt tjenstlig behov. De vil si at man må oppgi hvilke tjenestlig behov pasientene man ønsker å henter har. Man oppgir det tjenstlig behovet ved å oppgi en eller flere koder i ServiceCodes-headeren i forespørselen man sender. Gyldige verdier finner man under ServiceCodes i hovedmenyen. 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.

Picture

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 for R4 og her for STU3.

Nice-to-know

API-definisjoner

Hvis man går inn på API-ene(STU3 / R4) så kan kan man laste ned Open API-definisjoner for APIet.

Picture

Kodeeksempler

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

Picture