Grensesnittbeskrivelse
Hensikten med hendelseslisten er å tillate konsumenter med å holde sitt kunderegister ajour med folkeregisteret og reagere raskt på endringer i registeret. Annullering av dødsfall, registrering av falsk identitet eller tildeling av adressebeskyttelse kan være tidskritisk.
Tjenesten tilgjengeliggjør endringer i registeretog tilbyr en feed med hendelser. Det er konsumentene som selv styrer sekvens på lesing og hvor mange hendelser man skal lese. Samme hendelser kan leses av flere systemer hos konsumentene og man kan lese hendelser så mange ganger man ønsker. Hendelseslista tilbyr en løs kobling mellom produsent og konsument. Målet er å ha et fleksibelt API for brukerne av Folkeregisterets opplysninger. Konsumentene selv MÅ holde orden på en intern feed-peker som viser hvor langt man har lest i feeden. Hvis konsument har kopier av folkeregisteret er det anbefalt å lese hendelseslisten hyppig med påfølgende oppslag. Dette hindrer opplevde avvik mellom folkeregisteret og eventuelle kunderegister.
I rettighetspakken "offentlig med hjemmel" kan man i tillegg til å lese feeden, også lese innhold i en enkelt hendelse.
Hendelseslisten kan navigeres gjennom sekvensnummer. Sidestørrelsen som returneres er fast satt til 1000.
Tjenesten er naturlig å se i sammenheng med tjenesten oppslag. I feeden gis en peker til et persondokument. Dette er en nøkkel man kan bruke til å slå opp personen slik han så ut etter at hendelsen inntraff. Man kan også slå opp personen basert på fødsels- eller d-nummer. I enkelte rettighetspakker vil hendelsen kun inneholde en folkeregisteridentifikator.
De ulike tjenestene er dokumentert på swaggerhub.
Feed er i henhold til Atom spesifikasjonen.
Endepunkter
For oppbygging av endepunkter se her.
Eksempler
Oppslag i hendelsesliste:
https://folkeregisteret-api-ekstern.sits.no/folkeregisteret/offentlig-med-hjemmel/api/v1/hendelser/feed/?seq=1
Oppslag på en hendelse:
https://folkeregisteret-api-ekstern.sits.no/folkeregisteret/offentlig-med-hjemmel/api/v1/hendelser/7d9c19b1-4125-4968-b4dc-09cbaf3ac11f
Oppslag på xsd:
https://folkeregisteret-api-ekstern.sits.no/folkeregisteret/offentlig-med-hjemmel/api/v1/hendelser/xsd
Eksempel på curl-kommando som kan benyttes for å teste tjenesten:
curl -v -k -X HEAD 'https://folkeregisteret-api-konsument.sits.no/folkeregisteret/api/privat/v1/hendelser/feed' -H 'accept: application/json' -H 'Content-Type: application/json' -H "Authorization: Bearer $(ditt_token)"
Eksempel på bulkoppslag på hendelsesdokumenter:
$ curl -k -v -X POST -d '{"dokumentidentifikator": ["f5446d4445738d5a3dad02276daf8a1f","f5446d4445738d5a3dad02276daf8a1f"]}' -H "Content-Type: application/json" "https://folkeregisteret-api-konsument.sits.no/folkeregisteret/offentlig-med-hjemmel/api/v1/hendelser/bulkoppslag/" -H "Authorization: Bearer $(ditt_token)"
Headere
Accept
Verdien i denne headeren angir ønsket dataformat. Det er støtte for application/json (default) og application/xml
Content-Type
For bulkoppslag gjøres det POST-requester, disse forventer at headeren Content-Type er satt. Det er støtte for application/json og application/xml (default).
If-None-Match
Denne verdien skal settes lik ETag-header fra siste respons fra tjenesten. Se ETag for mer informasjon om bruk av ETag.
Eksempler på respons fra tjenesten
Hendelsesliste - format JSON
[
{
"sekvensnummer": 1,
"hendelse": {
"folkeregisteridentifikator": "69028400470",
"hendelsetype": "endringIIdentitetsgrunnlag",
"hendelsesdokument": "55591b51b20518f4f22bf1edd6aa9f25",
"persondokument": "8f475708c3d855defca884f4af6e49ae",
"ajourholdstidspunkt": "2017-06-20T09:26:03.689+02:00"
}
},
{
"sekvensnummer": 2,
"hendelse": {
"folkeregisteridentifikator": "69028400470",
"hendelsetype": "endringIAnnenIdentifikasjon",
"hendelsesdokument": "1120bea688fb14a292c244592a1aed76",
"persondokument": "5c3afb4f5afd2fcfbe2f90a6560903a0",
"ajourholdstidspunkt": "2017-06-20T09:26:03.689+02:00"
}
}
]
Hendelsesliste - format ATOM/XML
<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns="http://www.w3.org/2005/Atom">
<id>http://folkeregisteret.api.skatteetaten.no/folkeregisteret/offentlig-med-hjemmel/api/v1/hendelser/feed</id>
<title>Offentlig hendelsesliste</title>
<author>
<name>Skatteetaten</name>
</author>
<link rel='self' type='application/atom+xml'
href='http://folkeregisteret.api.skatteetaten.no/folkeregisteret/offentlig-med-hjemmel/api/v1/hendelser/feed?seq=1'/>
<link rel='first' type='application/atom+xml'
href='http://folkeregisteret.api.skatteetaten.no/folkeregisteret/offentlig-med-hjemmel/api/v1/hendelser/feed?seq=0'/>
<link rel='next' type='application/atom+xml'
href='http://folkeregisteret.api.skatteetaten.no/folkeregisteret/offentlig-med-hjemmel/api/v1/hendelser/feed?seq=1001'/>
<updated>2017-11-13T13:40:08.485Z</updated>
<entry xmlns:ns2="folkeregisteret:tilgjengeliggjoering:hendelse:v1">
<title>Hendelse</title>
<id>tag:skatteetaten.no,2017-10-10:folkeregisteret:tilgjengeliggjoering:hendelse:v1:1</id>
<updated>2017-10-10T14:06:57.59Z</updated>
<content>
<ns2:lagretHendelse>
<ns2:sekvensnummer>1</ns2:sekvensnummer>
<ns2:hendelse>
<ns2:folkeregisteridentifikator>69028400470</ns2:folkeregisteridentifikator>
<ns2:hendelsetype>endringIIdentitetsgrunnlag</ns2:hendelsetype>
<ns2:hendelsesdokument>55591b51b20518f4f22bf1edd6aa9f25</ns2:hendelsesdokument>
<ns2:persondokument>8f475708c3d855defca884f4af6e49ae</ns2:persondokument>
<ns2:ajourholdstidspunkt>2017-06-20T09:26:03.689+02:00</ns2:ajourholdstidspunkt>
</ns2:hendelse>
</ns2:lagretHendelse>
</content>
</entry>
<entry xmlns:ns2="folkeregisteret:tilgjengeliggjoering:hendelse:v1">
<title>Hendelse</title>
<id>tag:skatteetaten.no,2017-10-10:folkeregisteret:tilgjengeliggjoering:hendelse:v1:2</id>
<updated>2017-10-10T14:06:57.612Z</updated>
<content>
<ns2:lagretHendelse>
<ns2:sekvensnummer>2</ns2:sekvensnummer>
<ns2:hendelse>
<ns2:folkeregisteridentifikator>69028400470</ns2:folkeregisteridentifikator>
<ns2:hendelsetype>endringIAnnenIdentifikasjon</ns2:hendelsetype>
<ns2:hendelsesdokument>1120bea688fb14a292c244592a1aed76</ns2:hendelsesdokument>
<ns2:persondokument>5c3afb4f5afd2fcfbe2f90a6560903a0</ns2:persondokument>
<ns2:ajourholdstidspunkt>2017-06-20T09:26:03.689+02:00</ns2:ajourholdstidspunkt>
</ns2:hendelse>
</ns2:lagretHendelse>
</content>
</entry>
</feed>
Hendelsesdokument for en endring - format JSON
{
"dokumentidentifikator": "1120bea688fb14a292c244592a1aed76",
"skjemaversjon": "1.0",
"hendelse": {
"folkeregisteridentifikator": "16117548867",
"hendelsestype": "endringIAnnenIdentifikasjon",
"ajourholdstidspunkt": "2014-01-02T00:00:00Z",
"egenskapshendelse": [
{
"annenIdentifikasjon": {
"gyldighetstidspunkt": "2017-04-18T10:32:18.312+02:00",
"kilde": "kilde",
"aarsak": "kontroll",
"identifikasjonsnummer": "1234567890",
"identifikasjonsnummertype": "utenlandskIdentifikasjonsnummer",
"utstederland": "SWE"
},
"entitet": "annenIdentifikasjon",
"entitetsendring": "registrereNy"
}
]
}
}
Hendelsesdokument for en korrigering - format JSON
{
"dokumentidentifikator": "eb73af9403b0f5702e802ad4f9b8ca4e",
"skjemaversjon": "1.0",
"hendelse": {
"folkeregisteridentifikator": "16117548867",
"hendelsestype": "endringIIdentitetsgrunnlag",
"ajourholdstidspunkt": "2014-01-04T00:00:00Z",
"egenskapshendelse": [
{
"identitetsgrunnlag": {
"gyldighetstidspunkt": "2017-04-19T10:32:18.294+02:00",
"kilde": "korrigert-gjeldende-kilde",
"identitetsgrunnlagstatus": "kontrollert",
"dokumentgrunnlag": []
},
"entitet": "identitetsgrunnlag",
"entitetsendring": "korrigere"
}
]
}
}
Hendelsesdokument for en annullering - format JSON
{
"dokumentidentifikator": "c0e054f025e56d63b14f91fbb5abcb95",
"skjemaversjon": "1.0",
"hendelse": {
"folkeregisteridentifikator": "16117548867",
"hendelsestype": "endringIAnnenIdentifikasjon",
"ajourholdstidspunkt": "2014-01-05T00:00:00Z",
"egenskapshendelse": [
{
"entitet": "annenIdentifikasjon",
"entitetsendring": "annullere"
}
]
}
}
Hendelsesdokument for en korrigering av historisk informasjon - format JSON
NB: Denne entitetsendringen er ikke benyttet. Det er pt ikke støtte for å sette en entitetsendring til "korrigereHistorisk".
{
"dokumentidentifikator": "d1428661e6f2c5c158bf954facdd3ba2",
"skjemaversjon": "1.0",
"hendelse": {
"folkeregisteridentifikator": "16117548867",
"hendelsestype": "endringIIdentitetsgrunnlag",
"ajourholdstidspunkt": "2014-01-04T00:00:00Z",
"egenskapshendelse": [
{
"entitet": "identitetsgrunnlag",
"entitetsendring": "korrigereHistorisk"
}
]
}
}
Statuskode 304
Statuskode 304 (not modified) returneres hvis kallet til tjenesten inkluderte headeren If-None-Match og denne er lik den aktuelle ETag for etterspurte ressurs. Det betyr at det ikke er kommet noen nye innslag på feeden siden forrige kall.
Feilkoder
Hvis statuskode hverken er 200 eller 304, men man får svar fra applikasjonen, så returneres en datastruktur som ser slik ut
{
"kode": "FREG-001",
"melding": "Feil i tjenesten. Vennligst prøv igjen seinere."
}
HTTP Statuskode | Forklaring |
---|---|
400 | Feil i mottatte data - spesifiseres i retur. |
401 | Autentiseringsinformasjon mangler |
403 | Virksomheten er autentisert men mangler autorisasjon for den angitte tjenesten |
404 | Feil uri brukt. |
406 | Oppgitt Accept-header inneholder ikke 'application/atom+xml', 'application/xml' eller 'application/json', dersom Content-Type er satt ved bulkoppslag så vil returen være lik Content-Type dersom Accept-headeren er tom. |
429 | For mange kall er gjort på for kort tid. Vent i minimum antall ms. angitt i Retry-After-header før neste request utføres |
500 | Feil i tjenesten. Vennligst prøv igjen seinere. |