1. Introduksjon
Varslingsadresser for enheter er en tjeneste for offentlig forvaltning for å hente varslingsadresser for enheter i Enhetsregisteret. Tjenesten gir mulighet til å sende inn et organisasjonsnummer og få tilbake opplysninger om registrerte varslingsadresser for enheten. Tjenesten gir også mulighet for å søke opp en enkelt varslingsadresse ut fra en unik identifikator i kombinasjon med organisasjonsnummer. Det forutsettes at enhetene en søker på er registrert og er aktive i Enhetsregisteret.
Merk at det er benyttet fiktive eksempler i dokumentasjonen. Reelle svar vil ha samme struktur, men ikke samme innhold. |
Alle eksempler forutsetter at tjenesten er tilgjengelig på https://kofuvi.vcert.brreg.no/api/varslingsadresser.
2. Begrep
- Enhetsregisteret
-
Register over grunndata om juridiske personer og andre enheter. Enhetsregisteret tildeler organisasjonsnummer for entydig identifisering av enheter.
- Organisasjonsnummer
-
Nisifret nummer som entydig identifiserer enheter i Enhetsregisteret.
- Enhet
-
Alle hovedenheter, underenheter og organisasjonsledd som er identifisert med et organisasjonsnummer.
- Varslingsadresse
-
Elektronisk adresse som brukes for å varsle enhet eller person. Les mer om varslingsadresser for enheter.
3. Protokoll og format
Tjenesten er tilgjengelig som REST-tjeneste over HTTP. Data blir returnert i form av JSON på HAL-formatet.
Mediatype | Kommentar |
---|---|
application/json;charset=UTF-8 |
Ikke versjonert. Svar fra siste versjon på HAL-format. |
application/hal+json;charset=UTF-8 |
Ikke versjonert. Svar fra siste versjon på HAL-format. |
application/vnd.brreg.kofuvi.varslingsadresser.v1+json;charset=UTF-8 |
Eksplisitt versjon 1. Svar fra versjon 1 på HAL format. |
Se hvordan autentisering og autorisering gjøres under sikkerhet.
Se mer om versjonering i kapittelet om versjonering.
4. Tjenestene i APIet
4.1. Oversikt
HTTP-METODE | ENDEPUNKT | BESKRIVELSE |
---|---|---|
GET |
Hent varslingsadresser ut fra organisasjonsnummer |
|
GET |
/api/varslingsadresser/{orgnr}/kontaktinformasjon/{identifikator} |
Hent en varslingsadresse ut fra organisasjonsnummer og identifikator |
5. Statuskoder
HTTP-statuskoder i respons fra REST-tjenesten.
Kode | Tilleggsopplysninger |
---|---|
|
Både enhet og varslingsadresser finnes |
|
Forespørsel er sendt i feil format |
|
Enheten har ikke tilgang til å benytte tjenesten |
|
Enheten er ikke registrert i Enhetsregisteret, og/eller enheten har ingen varslingsadresser |
|
Uventet feil |
6. Sikkerhetsmekanismer
Informasjon om nødvendige sikkerhetsmekanismer: autentisering og autorisasjon.
6.1. Autentisering
For å benytte tjenesten trengs et X.509 virksomhetssertifikat fra en registrert tilbyder. Nasjonal kommunikasjonsmyndighet har en oversikt over tilbyderne.
-
En må benytte testvirksomhetssertifikat i test og prodvirksomhetssertifikat i prod
-
En må ha den private nøkkelen som hører til sertifikatet. Den private nøkkelen skal aldri deles med noen
Det er bare hovedenheter som kan få utstedt virksomhetssertifikat. Det betyr at en underenhet som skal gjøre oppslag på varslingsadresser er nødt å bruke virksomhetssertifikatet til hovedenheten. |
6.2. Autorisering
Tjenesten autoriserer tilgang til varslingsadresser ut fra organisasjonsnummeret i virksomhetssertifikatet.
6.2.1. Autorisering med organisasjonsform
Det er bare offentlige myndigheter som kan få tilgang til varslingsadressene. De fem organisasjonsformene innen offentlig forvaltning gis automatisk tilgang:
-
Staten (STAT)
-
Fylkeskommune (FYLK)
-
Kommune (KOMM)
-
Organisasjonsledd (ORGL)
-
Administrativ enhet – offentlig sektor (ADOS)
Hvis enheten din har en av disse organisasjonsformene er det nok å autentisere enheten med virksomhetssertifikat for å bli autorisert for tjenesten. Da trenger du ikke søke om tilgang.
6.2.2. Autorisering etter søknad
Enheter i offentlig forvaltning som ikke har en av organisasjonsformene over må søke Enhetsregisteret om tilgang til varslingsadresser. Det er bare enheter som treffer enkeltvedtak eller utferdiger forskrift som oppfyller kravet for å få tilgang. Enkeltvedtak og forskrift er definert i forvaltningsloven § 2.
Søknaden må inneholde:
-
Navnet til enheten
-
Organisasjonsnummeret til enheten (må være det samme som i virksomhetssertifikatet)
-
Dokumentasjon som viser at enheten treffer enkeltvedtak eller driver myndighetsutøvelse (utferdiger forskrift)
-
Navn og kontaktinformasjon til kontaktperson for søknaden
Søknaden sendes til: ERvarslingsadresser@brreg.no
Når søknaden er behandlet får du svar på e-post. Hvis søknaden blir godkjent, vil organisasjonsnummeret til enheten bli gitt autorisasjon for tilgang til varslingsadresser.
6.3. Brannmur-oppsett
Hvis en kaller tjenesten fra bak en utgående brannmur, må en lage åpninger i brannmuren sin.
Miljø | Host | IP | Port |
---|---|---|---|
|
|
|
|
|
|
|
|
6.4. REST klientsertifikat-autentisering
Det kreves at en utfører standard klientsertifikat-autentisering. De fleste vanlige HTTP-verktøy har støtte for dette. Eksempel med curl:
$ curl -k -v --cert virksomhet.cer --key virksomhet.key "https://kofuvi.vcert.brreg.no/api/varslingsadresser/909090900" > resultat.json
7. Hent varslingsadresser ut fra organisasjonsnummer
Varslingsadresser hentes ut ved å sende inn organisasjonsnummer som parameter.
7.1. Korrekt kall
Når enheten finnes og har registrert varslingsadresse(r) returneres varslingsadresse(r).
Forespørsel
$ curl -k -v --cert virksomhet.cer --key virksomhet.key 'https://kofuvi.vcert.brreg.no/api/varslingsadresser/909090900' -i -X GET
GET /api/varslingsadresser/909090900 HTTP/1.1
Host: kofuvi.vcert.brreg.no
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2224
{
"_links" : {
"self" : {
"href" : "https://kofuvi.vcert.brreg.no/api/varslingsadresser/909090900"
}
},
"_embedded" : {
"varsling" : {
"enhet" : {
"organisasjonsnummer" : "909090900",
"navn" : "Testvirksomhet AS",
"organisasjonsform" : {
"kode" : "AS"
},
"_links" : {
"self" : {
"href" : "https://data.brreg.no/enhetsregisteret/api/enheter/909090900"
}
}
},
"hentetFraHovedenhet" : false,
"varslingsadresser" : [ {
"kontaktinformasjon" : {
"digitalVarslingsinformasjon" : {
"epostadresse" : {
"fullstendigAdresse" : "tor.eksempel@testfirmaet.no",
"navn" : "økonomi",
"domenenavn" : "testfirmaet.no",
"brukernavn" : "tor.eksempel"
}
},
"identifikator" : "1a4f7dbea984492da8d68fe6b6feb956",
"sistEndret" : "2018-06-07T11:21:59Z",
"kontaktinformasjonForEnhet" : {
"enhetsidentifikator" : {
"verdi" : "909090900",
"type" : "ORGNR"
}
}
},
"_links" : {
"self" : {
"href" : "https://kofuvi.vcert.brreg.no/api/varslingsadresser/909090900/kontaktinformasjon/1a4f7dbea984492da8d68fe6b6feb956"
}
}
}, {
"kontaktinformasjon" : {
"digitalVarslingsinformasjon" : {
"mobiltelefon" : {
"fullstendigAdresse" : "+4791375739",
"navn" : "Kjell",
"internasjonaltPrefiks" : "47",
"nasjonaltNummer" : "91375739"
}
},
"identifikator" : "857583bbd4634471a45826e92288aab7",
"sistEndret" : "2018-06-07T11:21:59Z",
"kontaktinformasjonForEnhet" : {
"enhetsidentifikator" : {
"verdi" : "909090900",
"type" : "ORGNR"
}
}
},
"_links" : {
"self" : {
"href" : "https://kofuvi.vcert.brreg.no/api/varslingsadresser/909090900/kontaktinformasjon/857583bbd4634471a45826e92288aab7"
}
}
} ]
}
}
}
Parameter | Description |
---|---|
|
Organisasjonsnummer for enhet |
Path | Type | Description |
---|---|---|
|
|
Lenker til andre relaterte objekter, og seg selv |
|
|
Lenke til seg selv |
|
|
Verdien til lenken |
|
|
Varslingsadresser |
|
|
Beskrivelse av enheten |
|
|
Organisasjonsnummeret til enheten |
|
|
Navnet til enheten |
|
|
Organisasjonsformen til enheten |
|
|
Selve verdien av organisasjonsformen. Forkortelse. |
|
|
Lenker til objekter som er relatert til enheten |
|
|
En alternativ måte å overføre lenke med rel=self |
|
|
Lenke til enheten i åpne data fra Enhetsregisteret |
|
|
True betyr at du har fått varslingsadresser for en hovedenhet i stedet for for underenheten. Dette feltet vil bare være true når det er spurt på organisasjonsnummeret til en underenhet, og den mangler varslingsadresse, slik at det er varslingsadressen til hovedenheten som returneres. |
|
|
Liste med varslingsadresser for enheten |
|
|
En enkelt varslingsadresse |
|
|
Type varslingsadresse |
|
|
E-postadresse, en konkret type digitalVarslingsinformasjon |
|
|
Fullstendig e-postadresse |
|
|
Feltet skal en ikke forholde seg til i denne versjonen |
|
|
Domenenavnet til epostadressen |
|
|
Delen av epostadressen før @ |
|
|
Mobiltelefonnummer, en konkret type digitalVarslingsinformasjon |
|
|
Fullstendig mobiltelefonnummer |
|
|
Feltet skal en ikke forholde seg til i denne versjonen |
|
|
Internasjonalt prefiks for mobiltelefon |
|
|
Mobiltelefonnummer uten prefiks |
|
|
En unik identifikator (type UUID) for kontaktinformasjonen i Elasticsearch |
|
|
Tidspunkt for siste endring av kontaktinformasjonen |
|
|
Enheten kontaktinformasjonen gjelder |
|
|
ID som identifiserer enheten |
|
|
Verdien på identifikatoren, dvs. organisasjonsnummeret |
|
|
Type identifikator, vil alltid være ORGNR |
|
|
Lenker |
|
|
Lenke til seg selv |
|
|
Verdien til lenken |
7.2. Ingen varslingsadresse funnet
Enheten finnes, men den har ingen varslingsadresser.
Forespørsel
$ curl -k -v --cert virksomhet.cer --key virksomhet.key 'https://kofuvi.vcert.brreg.no/api/varslingsadresser/909090900' -i -X GET
GET /api/varslingsadresser/909090900 HTTP/1.1
Host: kofuvi.vcert.brreg.no
HTTP/1.1 404 Not Found
7.3. Feil format på forespørsel
Feil forespørsel, organisasjonsnummer er oppgitt i feil format.
Forespørsel
$ curl -k -v --cert virksomhet.cer --key virksomhet.key 'https://kofuvi.vcert.brreg.no/api/varslingsadresser/90909090' -i -X GET
GET /api/varslingsadresser/90909090 HTTP/1.1
Host: kofuvi.vcert.brreg.no
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 123
[ {
"logref" : "message",
"message" : "Feilmelding: Organisasjonsnummer må være et nummer med nøyaktig 9 siffer"
} ]
7.4. Klient er ikke autorisert til å benytte tjenesten
Du kan få denne statusen hvis du ikke bruker et gyldig virksomhetssertifikat, enheten din er slettet i Enhetsregisteret eller den ikke kan autoriseres. Se kapittelet om sikkerhetsmekanismer for detaljer.
Forespørsel
$ curl -k -v --cert virksomhet.cer --key virksomhet.key 'https://kofuvi.vcert.brreg.no/api/varslingsadresser/909090900' -i -X GET
GET /api/varslingsadresser/909090900 HTTP/1.1
Host: kofuvi.vcert.brreg.no
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
Content-Length: 128
[ {
"logref" : "message",
"message" : "Organisasjonsnummer 909090900 er ikke autorisert til å benytte denne tjenesten."
} ]
8. Hent en varslingsadresse ut fra organisasjonsnummer og identifikator
En enkelt varslingsadresse kan hentes ut ved å benytte organisasjonsnummer og identifikatoren til varslingsadressen som parametere.
Dette oppslaget forutsetter at du kjenner identifikatoren til varslingsadressen fra tidligere oppslag |
8.1. Korrekt kall
Når enheten og varslingsadressen finnes.
Forespørsel
$ curl -k -v --cert virksomhet.cer --key virksomhet.key 'https://kofuvi.vcert.brreg.no/api/varslingsadresser/909090900/kontaktinformasjon/1745dccd66ef4a5ec30e649e9d419506' -i -X GET
GET /api/varslingsadresser/909090900/kontaktinformasjon/1745dccd66ef4a5ec30e649e9d419506 HTTP/1.1
Host: kofuvi.vcert.brreg.no
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 675
{
"kontaktinformasjon" : {
"digitalVarslingsinformasjon" : {
"mobiltelefon" : {
"fullstendigAdresse" : "+4791375739",
"navn" : "Kjell",
"internasjonaltPrefiks" : "47",
"nasjonaltNummer" : "91375739"
}
},
"identifikator" : "857583bbd4634471a45826e92288aab7",
"sistEndret" : "2018-06-07T11:21:59Z",
"kontaktinformasjonForEnhet" : {
"enhetsidentifikator" : {
"verdi" : "909090900",
"type" : "ORGNR"
}
}
},
"_links" : {
"self" : {
"href" : "https://kofuvi.vcert.brreg.no/api/varslingsadresser/909090900/kontaktinformasjon/1745dccd66ef4a5ec30e649e9d419506"
}
}
}
Parameter | Description |
---|---|
|
Organisasjonsnummer for enhet |
|
Unik ID for en konkret varslingsadresse |
Path | Type | Description |
---|---|---|
|
|
En enkelt varslingsadresse |
|
|
Type varslingsadresse |
|
|
Mobiltelefonnummer, en konkret type digitalVarslingsinformasjon |
|
|
Fullstendig mobiltelefonnummer |
|
|
Feltet skal en ikke forholde seg til i denne versjonen |
|
|
Internasjonalt prefiks for mobiltelefon |
|
|
Mobiltelefonnummer uten prefiks |
|
|
En unik identifikator (type UUID) for kontaktinformasjon i Elasticsearch |
|
|
Tidspunkt for siste endring av kontaktinformasjonen |
|
|
Enheten kontaktinformasjon gjelder |
|
|
ID som identifiserer enheten |
|
|
Verdien på identifikatoren, dvs. organisasjonsnummeret |
|
|
Type identifikator, vil alltid være ORGNR |
|
|
Lenker |
|
|
Lenke til seg selv |
|
|
Verdien til lenken |
8.2. Ingen varslingsadresse funnet
Enheten finnes, men den har ingen varslingsadresser.
Forespørsel
$ curl -k -v --cert virksomhet.cer --key virksomhet.key 'https://kofuvi.vcert.brreg.no/api/varslingsadresser/909090900/kontaktinformasjon/999' -i -X GET
GET /api/varslingsadresser/909090900/kontaktinformasjon/999 HTTP/1.1
Host: kofuvi.vcert.brreg.no
HTTP/1.1 404 Not Found
8.3. Feil format på forespørsel
Feil forespørsel, organisasjonsnummer er oppgitt i feil format.
Forespørsel
$ curl -k -v --cert virksomhet.cer --key virksomhet.key 'https://kofuvi.vcert.brreg.no/api/varslingsadresser/90909090/kontaktinformasjon/999' -i -X GET
GET /api/varslingsadresser/90909090/kontaktinformasjon/999 HTTP/1.1
Host: kofuvi.vcert.brreg.no
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 123
[ {
"logref" : "message",
"message" : "Feilmelding: Organisasjonsnummer må være et nummer med nøyaktig 9 siffer"
} ]
8.4. Klient er ikke autorisert til å benytte tjenesten
Du kan få denne statusen hvis du ikke bruker et gyldig virksomhetssertifikat, enheten din er slettet i Enhetsregisteret eller den ikke kan autoriseres. Se kapittelet om sikkerhetsmekanismer for detaljer.
Forespørsel
$ curl -k -v --cert virksomhet.cer --key virksomhet.key 'https://kofuvi.vcert.brreg.no/api/varslingsadresser/909090900/kontaktinformasjon/1745dccd66ef4a5ec30e649e9d419506' -i -X GET
GET /api/varslingsadresser/909090900/kontaktinformasjon/1745dccd66ef4a5ec30e649e9d419506 HTTP/1.1
Host: kofuvi.vcert.brreg.no
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
Content-Length: 128
[ {
"logref" : "message",
"message" : "Organisasjonsnummer 909090900 er ikke autorisert til å benytte denne tjenesten."
} ]
9. Versjonering
9.1. Versjoner i bruk
API | Header |
---|---|
/varslingsadresser |
|
Pr. dags dato har vi kun én aktiv versjon. Vi vil introdusere V2 ved behov. |
9.2. Strategi
Vi vil forsøke, så langt det lar seg gjøre, å ikke bryte bakoverkompatibiliteten med våre brukere. Likevel kan det være nødvendig i enkelte situasjoner, av for eksempel juridiske årsaker eller vedlikehold, å gjøre endringer som fører til et slikt brudd.
Vi vil i dette tilfellet versjonere tjenesten slik at nyeste versjon vil være tilgjengelig sammen med forrige versjon. Hvis en ikke benytter versjonering i accept header, vil en få siste versjon.
Eldre versjon vil anses som utdatert/deprecated, og vil på sikt bli tatt bort. Ved behov for denne typen endringer vil vi forsøke å gi bruker god tid, og varsle om endringen i forkant.
9.2.1. Når innføres det en ny versjon?
Vi vil innføre en ny versjon når vi introduserer en endring som påvirker bakoverkompatibiliteten. Mindre endringer og patcher vil ikke medføre versjonsendring i header.
Eksempel på endring som medfører versjonering:
-
Fjerne eller endre navn på et attributt i HTTP-responsen
-
Fjerne eller endre navn på et REST-endepunkt
9.2.2. Når fjernes en versjon?
Vi vil legge ut varsel/driftsmeldinger i god tid på https://www.brreg.no/om-oss/driftsmeldinger/. I tillegg kan du abonnere på en RSS-feed her.
9.2.3. Hvordan velger jeg versjon?
Du kan velge versjon ved å spesifisere HTTP Accept-headeren. Bruk av headeren er spesifisert i denne tabellen.
Hvis du ikke spesifiserer Accept-header, vil du automatisk få den seneste versjonen. |
Eksempel
$ curl -k -v --cert virksomhet.cer --key virksomhet.key 'https://kofuvi.vcert.brreg.no/api/varslingsadresser/909090900' -i -X GET \
-H 'Accept: application/vnd.brreg.kofuvi.varslingsadresser.v1+json;charset=UTF-8'
GET /api/varslingsadresser/909090900 HTTP/1.1
Accept: application/vnd.brreg.kofuvi.varslingsadresser.v1+json;charset=UTF-8
Host: kofuvi.vcert.brreg.no
HTTP/1.1 200 OK
Content-Type: application/vnd.brreg.kofuvi.varslingsadresser.v1+json;charset=UTF-8
Content-Length: 2224
{
"_links" : {
"self" : {
"href" : "https://kofuvi.vcert.brreg.no/api/varslingsadresser/909090900"
}
},
"_embedded" : {
"varsling" : {
"enhet" : {
"organisasjonsnummer" : "909090900",
"navn" : "Testvirksomhet AS",
"organisasjonsform" : {
"kode" : "AS"
},
"_links" : {
"self" : {
"href" : "https://data.brreg.no/enhetsregisteret/api/enheter/909090900"
}
}
},
"hentetFraHovedenhet" : false,
"varslingsadresser" : [ {
"kontaktinformasjon" : {
"digitalVarslingsinformasjon" : {
"epostadresse" : {
"fullstendigAdresse" : "tor.eksempel@testfirmaet.no",
"navn" : "økonomi",
"domenenavn" : "testfirmaet.no",
"brukernavn" : "tor.eksempel"
}
},
"identifikator" : "1a4f7dbea984492da8d68fe6b6feb956",
"sistEndret" : "2018-06-07T11:21:59Z",
"kontaktinformasjonForEnhet" : {
"enhetsidentifikator" : {
"verdi" : "909090900",
"type" : "ORGNR"
}
}
},
"_links" : {
"self" : {
"href" : "https://kofuvi.vcert.brreg.no/api/varslingsadresser/909090900/kontaktinformasjon/1a4f7dbea984492da8d68fe6b6feb956"
}
}
}, {
"kontaktinformasjon" : {
"digitalVarslingsinformasjon" : {
"mobiltelefon" : {
"fullstendigAdresse" : "+4791375739",
"navn" : "Kjell",
"internasjonaltPrefiks" : "47",
"nasjonaltNummer" : "91375739"
}
},
"identifikator" : "857583bbd4634471a45826e92288aab7",
"sistEndret" : "2018-06-07T11:21:59Z",
"kontaktinformasjonForEnhet" : {
"enhetsidentifikator" : {
"verdi" : "909090900",
"type" : "ORGNR"
}
}
},
"_links" : {
"self" : {
"href" : "https://kofuvi.vcert.brreg.no/api/varslingsadresser/909090900/kontaktinformasjon/857583bbd4634471a45826e92288aab7"
}
}
} ]
}
}
}