Registrering i PVK av eksternt avgitte personverninnstillinger

Owned by sven.christiansen, created
Last updated: Oct 08, 2024
3 min read

API-navn

PVK- registrering av eksternt avgitte personverninnstillinger

Funksjonelt område

Personvernkomponenten

API-versjon og dato publisert

V2 Oct 4, 2024

Status

I Drift

API-dokumentasjon sist endret

Oct 8, 2024

Teknologi

REST HelseId.jpg

API'ets formål

API’et kan benyttes av eksterne aktører for å registrere en personverninnstilling i PVK på vegne av innbygger. Hver personverninnstilling er beskrevet gjennom en “personverninnstillingdefinisjon” som identifiseres av en Guid. Hver Personverninnstillingdefinisjon eies av en datansvarlig (Part) som identifiseres gjennom en partKode. For å benytte API’et må man kjenne Personverninnstillingdefinisjonens Guid samt eiers partkode.

API-klienten må eksplisitt gis rettigheter til å registerere personverninnstillinger for den aktuelle PersonverninnstillingDefinisjon.

Tjenesteoversikt

TjenesteNavn

Http

Beskrivelse

TjenesteNavn

Http

Beskrivelse

SettInnbyggersPersonvernInnstilling

POST <system url>/personvern/Personverninnstillinger/SettInnbyggersPersonvernInnstilling/v2

Nyregistrerer en innbyggers instans av en bestemt personverninnstilling eller endre status på en allerede satt innstilling. 

Autorisasjon og aksesstoken

To metoder for tilgang er tilgjengelige:

  1. HelseId sin autoriseringstjeneste for maskin-til-maskin kan benyttes:

    1. Velg Helsenorge Ekstern API i HelseId sin selvbetjeningsløsning

    2. Velg deretter scope “Personverninnstillinger_skriv”

    3. Når tilgangen er godkjent av Helsenorge, kan aksesstoken hentes ut fra HelseId

  2. API-klienten kan alternativt autentisere seg mot Helsenorge Sikkerhetstjeneste.

    1. API-klienten må forhåndskonfigureres på Helsenorge med sin public key

    2. API-et skal benyttes i system-til-system kontekst:

    3. Deretter kan API-klienten få utsedt et AksessToken fra Helsenorge STS.

AksessToken som mottas fra HelseId eller Helsenorge STS skal deretter være med i Authorization header i alle HTTP-requestene. Se:

SettInnbyggersPersonvernInnstilling

Input parametre

Merk! At Innstillingens faste metadata ikke er med i dette grensesnittet.

Navn

Type

Lovlige verdier

Kommentar

Navn

Type

Lovlige verdier

Kommentar

innbyggerFnr

string

fødselsnummer (11 siffer)

Dette er fødselsnummer til innbygger hvis personverninnstilling skal registreres eller endres

definisjonGuid

string

GUID

GUID for den personverninnstilling definisjon det gjelder

definisjonNavn

string

Navn på innstillingen

Beskrivende kortnavn på personverninnstilling definisjonen. (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.)

typePi

string

Type personverninnstilling

Kan ha en av følgende verdier:

  • samtykke

  • reservasjon

  • tilgangsbegrensning

aktiv

boolean

Innstillingens nye Status

Kan ha en av følgende verdier:

  • false

    • Samtykke: Ikke samtykket

    • Reservasjon: Ingen Reservasjon satt

    • Tilgangsbegrensning: Ingen tilgangsbegrensning satt

  • true

    • Samtykke: Har samtykket

    • Reservasjon: Reservasjon satt

    • Tilgangsbegrensning: Tilgangsbegrensning satt.

tidspunkt (ny)

String

Tidspunkt for når aktuell verdi for innstillingen ble satt. Frivillig felt.
Skal være ISO8601 format på UTC tid.

Eks: 2023-12-07T08:05:39Z

Benyttes dersom registreringen til PVK skjer senere enn innstillingen ble satt i eksternt system.

Avhengig av typePi:

  • SaInnbyggerMetadata

  • ReInnbyggerMetadata

  • TbInnbyggerMetadata

JSON

Struktur med metadata for aktuell type personverninnstilling

Se:

(C=Conditional). Er kun med dersom definisjonen er av type tilgangsbegrensning eller innstillingen er av type Samtykke elle reservasjon og innbygger har satt egne tidsbegrensninger.

 

Eks: Sette et nytt samtykke:

{
   "innbyggerFnr":"12048645510",
   "definisjonGuid":"3FE2A80A-4200-42E2-817B-DA8A6236708A",
   "definisjonNavn":"Samtykke til oppbevaring av biomateriale",
   "partKode":"NFS",
   "typePi": “samtykke”,
   "aktiv": true,
}

Eks: Slette et tidligere gitt samtykke:

{
   "innbyggerFnr":"12048645510",
   "definisjonGuid":"3FE2A80A-4200-42E2-817B-DA8A6236708A",
   "definisjonNavn":"Samtykke til oppbevaring av biomateriale",
   "partKode":"NFS",
   "typePi": “samtykke”,
   "aktiv": false
}

Eks: Sette en ny reservasjon:

{
   "innbyggerFnr":"12048645510",
   "definisjonGuid":"ecc56090-124b-4405-8137-2a616c683ffc",
   "definisjonNavn":"Reservasjon mot registrering av helseopplysninger",
   "partKode":"PDMR",
   "typePi": “reservasjon”,
   "aktiv": true
}

Eks: Slette en tidligere satt reservasjon:

{
   "innbyggerFnr":"12048645510",
   "definisjonGuid":"ecc56090-124b-4405-8137-2a616c683ffc",
   "definisjonNavn":"Reservasjon mot registrering av helseopplysninger",
   "partKode":"PDMR",
   "typePi": “reservasjon”,
   "aktiv": false
}

Eks: Sette ny tilgangsbegrensning. Enten registrerer ny instans eller oppdatere eksisterende instans med endret helsepersonell:

Merk! Dette blir den nye innstillingen. Eventuelle tidligere satte HPR-nummer blir “overskrevet”.

{    "innbyggerFnr":"12048645510",    "definisjonGuid":"3F7457B8-821C-45A8-AE04-D3E4A0DAC0F0",    "definisjonNavn":"Begrensning av helsepersonells tilgang til legemiddelliste",    "partKode":"RF",    "typePi": “tilgangsbegrensning”,    "aktiv": true, "TbInnbyggerMetadata": { "detaljertAngivelse": { "navngittHelseperson": [ { "nummer": "4128168", "navn": "Linda Ingrid Telle" }, { "nummer":"1234567", "navn":"Per Olsen" } ] } } }

 

Eks: Slette (helt) tidligere satt tilgangsbegrensning:

{
   "innbyggerFnr":"12048645510",
   "definisjonGuid":"3F7457B8-821C-45A8-AE04-D3E4A0DAC0F0",
   "definisjonNavn":"Begrensning av helsepersonells tilgang til legemiddelliste",
   "partKode":"RF",
   "typePi": “tilgangsbegrensning”,
   "aktiv": false
}

Responsparameter (ved HTTP 200)

Navn

Type

Lovlige verdier

Kommentar

Navn

Type

Lovlige verdier

Kommentar

returKode

string

ok

ikkeOk

 

instansEndret

string

endret

ikkeEndret

Dersom retur er "ikkeEndret" betyr dette at aktuell personverninnstilling for denne innbygger allerede hadde angitt verdi eller at et samtykke som trekkes aldri har vært gitt (dvs. det fantes ingen instans).

 

Eks (samtykket var allerede registrert):

{
“returkode”: “ok”,

"instansEndret":"ikkeEndret",
 }

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"
}