Tjenesteoversikt
TjenesteNavn | HttpVerb | Beskrivelse |
---|---|---|
SjekkInnbyggersPiStatus | POST <system url>/personvern/v2/Personverninnstillinger/SjekkInnbyggersPiStatus | Returnerer status på en bestemt Personverninnstilling for en gitt innbygger. |
HentInnbyggersPiForPart | POST <system url>/personvern/v2/Personverninnstillinger/HentInnbyggersPiForPart | Returnerer en liste over personverninnstillinger for en bestemt innbygger som tilhører en bestemt aktør inklusiv innstillingenes status. Merk! Denne returnerer kun status på de Personverninnstillinger der det finnes en instans hos aktuell innbygger og der denne har status "Aktiv", dvs. at den er virksom. Historikk vises derfor ikke. |
HentInnbyggereAktivePiForDefinisjon | POST <system url>/personvern/v2/Personverninnstillinger/HentInnbyggereAktivePiForDefinisjon | Returnerer en liste med fødselsnummer for alle innbyggere som har en aktiv personverninnstilling for en bestemt Personverninnstillingdefinisjon. Kan benyttes for å:
|
Autorisasjon og aksesstoken
Alle API’er krever at klienten på forhånd har autentisert seg mot vår Sikkerhetstjeneste og fått utstedt et aksesstoken som skal være med i tjenestekallene til det enkelte API. DigitalAktiv tjenesten krever ikke at kallet utføres i context av en innlogget bruker dvs. at det benyttes UseCase 1 (system-til-system) beskrevet her: 01 - System til System
Felles objekter benyttet i respons fra tjenestene
Personverninnstilling definisjoner kan være utformet slik at de har metadata. Slike metadata har tre formål:
De angir i kodeverk personverninnstillingens generelle virkeområde, slik at dette kan tolkes maskinelt (uten å på forhånd vite hva en bestemt innstilling betyr).
Dersom en personverninnstillingdefinisjon tillater at innbygger selv kan sette en eller flere tidsperioder det innstillingen skal være gjeldende, er innbyggers valg med som metadata
For tilgangsbegrensninger er det alltid med metadata. Noen av disse er valg innbygger selv kan gjøre. (F.eks. blokkere tilgang til navngitt helsepersonell).
Metadata for samtykker og reservasjoner
Hovedstruktur
SaMetadata eller ReMetadata | Type | Kommentar |
---|---|---|
SaFasteMetadata eller ReFasteMetadata (conditional) | Se under. | Er med kun dersom det er definerte faste metadata på definisjonen. Normalt med i alle nyere definisjoner. |
SaInnbyggerMetadata eller ReInnbyggerMetadata (conditinal) | Se under | Er kun med dersom definisjonen tillater at innbygger setter tidsbegrensninger og innbygger har satt slike. |
Faste metadata for en definisjon
Dette er metadata som beskriver innstillingens virkeområde/omfang og som gjelder alle innbyggere.
SaFasteMetadata eller ReFasteMetadata | Type | Lovlige verdier | Kommentar |
---|---|---|---|
fastTidsbegrensning | element (conditional) | Kun med hvis det er en fast tidsbegrensning for innstillingens virkeområde. | |
tidsbegrensetFra | string | Dato | Fra og med |
tidsbegrensetTil | string | Dato | Til og med |
omfangElement | Liste | Det kan være flere enn et slikt element (eventuelt ingen) | |
omfang (mandatory) | string (kodeverdi) | Omfanget av samtykke/reservasjon: kodeverk fra Volven 7608. Følgende verdier er aktuelle for Samtykke eller Reservasjon: DT: Digital tilgang OF: Oppføring UO: Utlevering av helseopplysninger IO: Innhenting av helseopplysninger DO: Deltagelse i ordning eller tjeneste | |
logiskOmfang (optional) | string | Kan ha en av følgende tre verdier:
| |
presisering (optional) | string | Fritekstfelt: Bilateralt avtalt mellom Register og NHN | Presisering ift. Omfang, benyttes hvis nødvendig |
Metadata som innbygger kan sette selv
Dette er metadata som innbygger kan settes selv, dersom definisjonen tillater det, og som er individuelle pr. innbygger.
SaInnbyggerMetadata eller ReInnbyggerMetadata | Type | Lovlige verdier | Kommentar |
---|---|---|---|
innbyggerTidsbergensninger | element (conditional) | Kun med dersom definisjonen har gitt innbygger slik mulighet og innbygger har angitt en eller flere tidsperioder. | |
periode | liste | ||
fraTidspunkt | string | Dato | Fra og med |
tilTidspukt | string | Dato | til og med |
Metadata for tilgangsbegrensninger
Hovedstruktur
SaMetadata eller ReMetadata | Type | Kommentar |
---|---|---|
TbFasteMetadata (mandatory) | Se under. | Er med kun dersom det er definerte faste metadata på definisjonen. Normalt med i alle nyere definisjoner. |
TbInnbyggerMetadata (conditional) | Se under | Er med dersom definisjonen tillater at innbygger setter tidsbegrensninger eller definisjonen tilsier at innbygger selv må angi sperringen eller blokkeringens virkeområde. |
Faste metadata for en definisjon
Dette er metadata som beskriver innstillingens virkeområde/omfang og som gjelder alle innbyggere.
TbFasteMetadata | Type | Lovlige verdier |
---|---|---|
fastTidsbegrensning (conditional) | element (conditional) | |
tidsbegrensetFra | string | Dato |
tidsbegrensetTil | string | Dato |
omfang (mandatory) | string | Omfanget av tilgangsbegrensningen: kodeverk fra Volven 7608. Følgende verdier er aktuelle for tilgangsbegrensning: SP: Sperre tilgang til helseopplysninger BL: Blokkere tilgang til helseopplysninger |
logiskOmfang (mandatory) | string | Kan ha en av følgende tre verdier:
|
typeAngivelse (mandatory) | string | Angir hvilken type angivelse som benyttes for å beskrive hva/hvem tilgangsbegrensningen gjelder for. Kan ha en av følgende 4 verdier:
|
fastDetaljertAngivelse (conditional) | element | |
(liste av) kategoriOpplysninger (conditional) | string | Foreløpig ikke etablert kodeverk. Må avtales bilateralt mellom register og NHN. |
(liste av) rolleTilPasient (conditional) | string | Volven kodeverk 9034. Feltet inneholder kodeverkets verdi. Eksempel: “Fastlege”. |
Metadata som innbygger kan sette selv
Dette er metadata som beskriver innstillingens virkeområde/omfang og som gjelder alle innbyggere.
TbInnbyggerMetadata | Type | Lovlige verdier | Kommentar |
---|---|---|---|
innbyggerTidsbergensninger (conditional) | element | Kun med dersom definisjonen har gitt innbygger slik mulighet og innbygger har angitt en eller flere tidsperioder. | |
periode | liste | ||
fraTidspunkt | string | Dato | Fra og med |
tilTidspukt | string | Dato | til og med |
innbyggerDetaljertAngivelse (conditional) | element | Er med dersom definisjonen er utformet slik at innbygger selv kan velge hva/hvem tilgangsbegrensningen gjelder for. | |
(liste av) kategoriOpplysninger (conditional) | element | Foreløpig ikke etablert kodeverk. Må avtales bilateralt mellom register og NHN. | Er med dersom “typeAngivelse = Kategori opplysninger” i den faste delen av definisjonen. |
(liste av) rolleTilPasient (conditional) | string | Volven kodeverk 9034. Feltet inneholder kodeverkets verdi. Eksempel: “rolle”: “Fastlege”. | Er med dersom “typeAngivelse = Rolle til pasient” i den faste delen av definisjonen. |
(liste av) navngittHelseperson (conditional) | element | Er med dersom “typeAngivelse = Helsepersonell” i den faste delen av definisjonen. | |
nummer (manadatory) | string | Helsepersonens HPR-nummer | |
navn (mandatory) | string | Helsepersonenes Navn | |
(liste av) helseforetak (conditional) | element | Er med dersom “typeAngivelse = Ansatte i organisasjon” i den faste delen av definisjonen. | |
nummer (manadatory) | string | Helseforetakets organisasjonsnummer | |
navn (mandatory) | string | Helseforetakets Navn |
SjekkInnbyggersPiStatus
Input parametere
Navn | Type | Lovlige verdier | Kommentar |
---|---|---|---|
innbyggerFnr | string | fødselsnummer (11 siffer) | Dette er fødselsnummer til innbygger det spørres på. |
definisjonGuid | string | Forhåndskjent verdi | GUID som referer til en bestemt personverninnstilling. Må være kjent på forhånd av kallende system. |
definisjonNavn | string | Navn på innstillingen | Beskrivende kortnavn på den forespurte personverndefinisjon. Må være kjent på forhånd av kallende system. (Denne er egentlig overflødig da GUID uansett er unik, vi har likevel valgt å ta denne med.) |
partKode | string | Forhåndsavtalt verdi | Kortnavn som identifisere det aktuelle register/screeningprogram/forskningsprosjekt som eier den aktuelle personverninnstilling. Må være kjent på forhånd av kallende system. (Denne er egentlig overflødig da GUID uansett er unik, vi har likevel valgt å ta denne med.) |
Eks:
{
"innbyggerFnr":"12048645510",
"definisjonGuid":"3FE2A80A-4200-42E2-817B-DA8A6236708A",
"definisjonNavn":"Samtykke til oppbevaring av biomateriale",
"partKode":"NFS"
}
Responsparametre
Navn | Type | Lovlige verdier | Kommentar |
---|---|---|---|
innbyggerFnr | string | fødselsnummer (11 siffer) | Dette er fødselsnummer til innbygger det ble spurt på (og som svaret gjelder). |
definisjonGuid | string | GUID | GUID for den personverninnstilling definisjon det ble spurt på. |
definisjonNavn | string | Navn på innstillingen | Beskrivende kortnavn på den forespurte personverndefinisjon. |
partKode | string | Forhåndsavtalt verdi | Kortnavn som identifisere det aktuelle register/screeningprogram/forskningsprosjekt som eier den aktuelle personverninnstilling. |
typePi | string | Type personverninnstilling | Kan ha en av følgende verdier:
|
aktiv | bool | Kan ha en av følgende verdier:
MERK! En innstilling er markert som aktiv selv om den eventuelt ikke er virksom ut fra metadata som kan tillate tidsbegrensninger (se under) | |
SaMetadata (element)
ReMetadata (element)
TbMetadata (element)
| JSON | Struktur med metadata knyttet til aktuell personverninnstilling. Kan både være faste metadata for definisjonen, og metadata som innbygger selv kan sette, dersom dette er tillatt/nødvendig for den aktuelle definisjon | (C=Conditional). Er med dersom definisjonen har faste metadata eller har metadata som innbygger setter.
|
Eksempler
Samtykker
Samtykke uten metadata
{ "innbyggerFnr":"12048645510", "definisjonGuid":"3FE2A80A-4200-42E2-817B-DA8A6236708A", "definisjonNavn":"Samtykke til oppbevaring av biomateriale", "partKode":"NFS", "typePi": “samtykke”, "aktiv": true }
Samtykke med fast tidsbegrensning og metadata
Her er det en fat tidsbegrensning for hvilken periode samtykket gjelder for. Videre er det i eksemplet to stk. omfangElement:
OF (oppføring)
IO (innhenting av helseopplysninger, med tilhørende presisering)
{ "innbyggerFnr": "12048645510", "definisjonGuid":"3FE2A80A-4200-42E2-817B-DA8A6236708A", "definisjonNavn":"Samtykke til oppbevaring av biomateriale", "partKode":"NFS", "typePi":"samtykke", "aktiv": true, "SaMetadata": { "SaFasteMetadata": { "fastTidsbegrensning": { "tidsbegrensetFra": "2022-01-01", "tidsbegrensetTil": "2023-12-31" }, "omfangElement": [ { "omfang": "OF" }, { "omfang": "IO", "logiskOmfang": "Angitte", "presisering": "Blodprøver" } ] } } }
Reservasjon
Reservasjon uten metadata
{ "innbyggerFnr":"12048645510", "definisjonGuid":"3FE2A80A-4200-42E2-817B-DA8A6236708A", "definisjonNavn":"Reservasjon mot lagring av helseopplysninger", "partKode":"PDMR", "typePi": "reservasjon", "aktiv": false }
Reservasjon med innbygger satt tidsbegrensning og metadata
Her har reservasjonen metadata som forklarer i kodeverk hva den gjelder (utlevering av direkte personidentifiserbare opplysninger). Videre har innbygger satt 2 tidsperioder der reservasjonen gjelder.
{ "innbyggerFnr":"12048645510", "definisjonGuid":"3FE2A80A-4200-42E2-817B-DA8A6236708A", "definisjonNavn":"Reservasjon mot utlevering av helseopplysninger", "partKode":"PDMR", "typePi": "reservasjon", "aktiv": true, "ReMetadata": { "SaFasteMetadata": { "omfangElement": [ { "omfang": "UO", "logiskOmfang": "Angitte", "presisering": "Direkte personidentifiserbare opplysninger" } ] }, "SaInnbyggerMetadata": { "innbyggerTidsbegrensninger": { "periode": [ { "fraTidspunkt":"2022-01-01", "tilTidspunkt":"2022-06-01" }, { "fraTidspunkt": "2022-09-01", "tilTidspunkt": "2022-12-31" } ] } } } }
Tilgangsbegrensning
Tilgangsbegrensning av type sperre som gjelder alt helsepersonell
I dette eksemplet har vi også lagt på en tidsperiode som innbygger har satt der denne sperren gjelder.
{ "innbyggerFnr":"12048645510", "definisjonGuid":"9c869253-ed40-4447-abdb-9e2024a88af0", "definisjonNavn":"Sperre tilgang for alt helsepersonell", "partKode":"nilar", "typePi": "tilgangsbegrensning", "aktiv": true, "TbMetadata": { "TbFasteMetadata": { "omfang": "SP", "logiskOmfang": "Alle", "typeAngivelse": "Helsepersonell" }, "TbInnbyggerMetadata": { "innbyggerTidsbegrensninger": { "periode": [ { "fraTidspunkt":"2022-01-01", "tilTidspunkt":"2022-06-01" } ] } } } }
Tilgangsbegrensning av type blokkering som gjelder alt helsepersonell unntatt fastlegen
Dette er fast for definisjonen g kan ikke velges av innbygger). Vi har lagt på en innbygger satt tidsbegrensning i dette eksemplet.
{ "innbyggerFnr":"12048645510", "definisjonGuid":"a3c17c59-d197-47fd-aa51-64cdfdf847db", "definisjonNavn":"Blokkere tilgang for alt helsepersonell unntatt fastlege", "partKode":"RF", "typePi": "tilgangsbegrensning", "aktiv": true, "TbMetadata": { "TbFasteMetadata": { "omfang": "BL", "logiskOmfang": "Angitte", "typeAngivelse": "Rolle til Pasient", "fastDetaljertAngivelse": { "rolleTilPasient": [ { "rolle": "Fastlege" } ] } }, "TbInnbyggerMetadata": { "innbyggerTidsbegrensninger": { "periode": [ { "fraTidspunkt":"2022-01-01", "tilTidspunkt":"2022-06-01" } ] } } } }
Tilgangsbegrensning av type blokkering som gjelder angitt helsepersonell
Innbygger angir hvilket helsepersonell som det ska blokkeres tilgang for (vi har også her lagt på en innbygger bestemt tidsperiode).
{ "innbyggerFnr":"12048645510", "definisjonGuid":"61d0da0d-1e08-425f-b0c6-2a01019cc181", "definisjonNavn":"Blokkere tilgang for angitt helsepersonell", "partKode":"nilar", "typePi": "tilgangsbegrensning", "aktiv": true, "TbMetadata": { "TbFasteMetadata": { "omfang": "BL", "logiskOmfang": "Angitte", "typeAngivelse": "Helsepersonell" }, "TbInnbyggerMetadata": { "innbyggerTidsbegrensninger": { "periode": [ { "fraTidspunkt":"2022-01-01", "tilTidspunkt":"2022-06-01" } ] }, "innbyggerDetaljertAngivelse": { "navngittHelseperson": [ { "nummer": "4128168", "navn": "Linda Ingrid Telle" }, { "nummer":"1234567", "navn":"Per Olsen" } ] } } } }
HentInnbyggersPiForPart
Dette tjenestekallet returnerer kun innstillinger aktuell innbygger har aktiv hos aktøren. Merk! EN innstilling anses aktiv selv om tidsperiode angitt for innstillingens virkeområde ikke er “aktiv”.
Input parametere
Navn | Type | Lovlige verdier | Kommentar |
---|---|---|---|
innbyggerFnr | string | fødselsnummer (11 siffer) | Dette er fødselsnummer til innbygger det spørres på. |
partKode | string | Forhåndskjent verdi | Kortnavn som identifisere det aktuelle register/screeningprogram/forskningsprosjekt som eier den aktuelle personverninnstilling. |
Eks:
{
"innbyggerFnr":"12048645510",
"partKode":"NFS"
}
Responsparametre
Navn | Type | Kommentar | |
---|---|---|---|
funnet | boolean | Denne vil alltid være med i retur. | "true" dersom minst en aktiv personverninnstilling ble funnet for innbygger tilhørende den parten det forespørres på. |
personvernInnstillinger | liste | JSON-struktur | En liste med de aktive personverninnstillinger som finnes for aktuell innbygger knyttet til den aktuelle part. Disse har eksakt samme struktur som i respons for andre tjenestekall som gjelder kun en enkelt innstilling. Derav dublering av innbyggers fødselsnummer og PartKode i hver returnert aktiv innstilling. |
|
|
|
|
SaMetadata ReMetadata TbMetadata | JSON | Struktur med metadata knyttet til aktuell personverninnstilling. Kan både være faste metadata for definisjonen, og metadata som innbygger selv kan sette, dersom dette er tillatt/nødvendig for den aktuelle definisjon | (C=Conditional). Er med dersom definisjonen har faste metadata eller har metadata som innbygger setter.
|
Eksempel
Eksemplet viser innbygger som har et aktivt samtykke med innbygger bestet tidsperiode, samt en tilgangsbegrensning for angitt helsepersonell.
{ "funnet": true, "personverninnstillinger": [ { "innbyggerFnr": "12048645510", "definisjonGuid":"3FE2A80A-4200-42E2-817B-DA8A6236708A", "definisjonNavn":"Samtykke til oppbevaring av biomateriale", "partKode":"NFS", "typePi":"samtykke", "aktiv": true, "SaMetadata": { "SaFasteMetadata": { "fastTidsbegrensning": { "tidsbegrensetFra": "2022-01-01", "tidsbegrensetTil": "2023-12-31" }, "omfangElement": [ { "omfang": "OF" }, { "omfang": "IO", "logiskOmfang": "Angitte", "presisering": "Blodprøver" } ] } } }, { "innbyggerFnr": "12048645510", "definisjonGuid":"61d0da0d-1e08-425f-b0c6-2a01019cc181", "definisjonNavn":"Blokkere tilgang for angitt helsepersonell", "partKode":"NFS", "typePi": "tilgangsbegrensning", "aktiv": true, "TbMetadata": { "TbFasteMetadata": { "omfang": "BL", "logiskOmfang": "Angitte", "typeAngivelse": "Helsepersonell" }, "TbInnbyggerMetadata": { "innbyggerTidsbegrensninger": { "periode": [ { "fraTidspunkt":"2022-01-01", "tilTidspunkt":"2022-06-01" } ] }, "innbyggerDetaljertAngivelse": { "navngittHelseperson": [ { "nummer": "4128168", "navn": "Linda Ingrid Telle" }, { "nummer":"1234567", "navn":"Per Olsen" } ] } } } } ] }
HentInnbyggereAktivePiForDefinisjon
Fordi denne tjenesten kan returnere et meget stort antall objekter i responsen (dvs. et stort antall innbyggere) har vi valgt at denne tjenesten ikke returnerer data som er faste for en definisjon. Disse forutsettes kjent fra kallende system, eller kan eventuelt hentes med et etterfølgende kall til tjenesten SjekkInnbyggersPiStatus for en av de innbyggere som returneres. Respons objektet pr innbygger inneholder kun metadata innbygger selv kan sette/velge.
Input parametre
Navn | Type | Lovlige verdier | Kommentar |
---|---|---|---|
definisjonGuid | string | Forhåndskjent verdi | GUID som referer til en bestemt personverninnstilling. Må være kjent på forhånd av kallende system. |
definisjonNavn | string | Navn på innstillingen | Beskrivende kortnavn på den forespurte personverndefinisjon. |
partKode | string | Forhåndsavtalt verdi | Kortnavn som identifisere det aktuelle register/screeningprogram/forskningsprosjekt som eier den aktuelle personverninnstilling. Må være kjent på forhånd av kallende system. |
typePi | string | Type personverninnstilling | Kan ha en av følgende verdier:
|
pagingReference | int | Verdi fås i respons. | Skal være med i request i etterfølgende kall dersom det er behov for paging, og kan være med i første request, men må da ha verdien 0. |
Eks (første kall):
{ "definisjonGuid":"3FE2A80A-4200-42E2-817B-DA8A6236708A", "partKode":"NFS" }
eller
{ "definisjonGuid":"3FE2A80A-4200-42E2-817B-DA8A6236708A", "partKode":"NFS", "pagingReference": 0 }
Responsparametre
Navn | Type | Lovlige verdier | Kommentar |
---|---|---|---|
definisjonGuid | string | GUID | GUID for den personverninnstilling definisjon det ble spurt på. |
definisjonNavn | string | Navn på innstillingen | Beskrivende kortnavn på den forespurte personverndefinisjon. |
partKode | string | Forhåndsavtalt verdi | Kortnavn som identifisere det aktuelle register/screeningprogram/forskningsprosjekt som eier den aktuelle personverninnstilling. |
typePi | string | Type personverninnstilling | Kan ha en av følgende verdier:
|
pagingReference | int | Dersom den har verdien 0, trenger det ikke å gjøres flere kall. Dersom annen verdi, må det gjøres etterfølgende kall med angitt pagingReference. | Nytt kall må gjøres med pagingReference så lenge denne er større enn verdien “0”. |
personvernInnstillinger
| Element (liste)
|
| En liste med alle de innbygger som har en aktiv instans (aktiv reservasjon, samtykke eller tilgangsbegrensning) |
Eks (samtykke evt. reservasjon):
{ "definisjonGuid":"3FE2A80A-4200-42E2-817B-DA8A6236708A", "definisjonNavn":"Samtykke til oppbevaring av biomateriale", "partKode":"NFS", "typePi": "samtykke", "pagingReference": 0, "personvernInnstillinger": [ { "innbyggerFnr":"12048645510" }, { "innbyggerFnr":"11059643310" } ] }
Eks (tilgangsbegrensning):
{ "definisjonGuid":"91b682e1-6a6d-4f3d-ad25-233dfddbe490", "definisjonNavn":"Sperring mot innsyn i prøvesvar", "partKode":"NFS", "typePi": "tilgangsbegrensning", "pagingReference": 0, "personvernInnstillinger": [ { "innbyggerFnr":"12048645510", "innbyggerTbMetadata":[ { "type":"helsepersonell", "nummer":"1234567", "navn":"Per Olsen" }, { "type":"helsepersonell", "nummer":"9876543", "navn":"Lisa Elin Kultvedt" }] }, { "innbyggerFnr":"11059643310", "innbyggerTbMetadata":[ { "type":"helsepersonell", "nummer":"1234599", "navn":"Kim Hansen" }, { "type":"helsepersonell", "nummer":"9876599", "navn":"Nina Petersen" }] }] }
Respons ved feil
Alle tjenester i API'ene har følgende logikk for HTTP-respons:
Statuskode når kallet er utført ok: 200
Statuskode ved feil internt på Helsenorge: 500
Statuskode ved feil i request: 400
Statuskode ved manglende tilganger: 403
Statuskode ved feil eller manglende autorisasjon: 401
Ved HTTP-statuskoder som tilsier at det har oppstått en feil returneres også en respons med feilkode og feilmelding.
Eks:
{
"Code": "SEC-110000",
"Message": "Token is expired or invalid"
}