Hendelseliste-tjenestene tilbyr hendelseslister med informasjon om endringer i datasett som leveres av Skatteetatens datatjenester.

Grensesnittbeskrivelse

Hendelseslistene gir informasjon om endringer i datasett som leveres av Skatteetatens datatjenester.

For å bruke grensesnittet kreves autentisering med X.509-sertifikat.

Basis-URL for en hendelsesliste er på formatet:

GET https://<env>/<apipath>/hendelser/
  • <env>: Miljø-spesifikk adresse
  • <apipath>: Path til tjenesten man ønsker hendelsesliste for. Det er per i dag tre feed-tjenester med apipath i parentes. Disse er Inntektsmottaker-feed (/api/innrapportert/inntektsmottaker/hendelser/), Skattepliktig feed (/api/part/skattepliktig/hendelser/) og Skatteoppgjør-feed (/api/formueinntekt/skatteoppgjoer/hendelser/)

Hendelsesliste

Hendelseslisten navigeres vha. sekvensnummer og er paginert.

GET https://<env>/<apipath>/hendelser/?fraSekvensnummer=<seq>&antall=<n>
  • fraSekvensnummer=<seq>: Fra og med hvilket sekvensnummer skal spørres etter. Må være større enn 0.
  • antall=<n>: Maks antall ønskede hendelser i responsen uavhengig av hull i sekvensnummer. Parameteren må være større enn 0. Anbefalt størrelse er på minimum 1000, men tjenesten håndterer fint antall på 10000. Om man spør etter antall=1000 og får kun 900 hendelser i responsen, innebærer dette at man har kommet på slutten av hendelseslisten.

Begge parametrene må være satt.

Første sekvensnummer fra dato

For å finne ut hvilket sekvensnummer man skal starte å lese hendelseslisten på finnes et eget endepunkt:

GET https://<env>/<apipath>/hendelser/start[?dato=<yyyy-mm-dd>]
  • dato=<yyyy-mm-dd>: En dato på ISO 8601-format, YYYY-MM-DD. Dersom dette parameteret er satt vil endepunktet returnere sekvensnummer for første hendelse fra og med denne denne datoen. Dersom dato ikke er satt vil endepunktet returnere sekvensnummer for aller første hendelse i listen.

Versjonering

Se generelle regler for versjonering.

Eksempler

Her er et eksempler på spørring med curl mot tjenesten. Du må legge sertifikat og nøkkel som parametre til curl-kommandoen.

Dersom kallet lykkes får man HTTP status 200 og data i JSON eller XML format. Dersom man ikke spesifiserer ønsket format får man JSON.

Dersom man ønsker XML i stedet for JSON kan dette spesifiseres med header Accept satt til application/xml

Hendelsesliste suksess (HTTP status 200)

$ curl -v --cert datakonsument.cer --key datakonsument.key "https://api-at.sits.no/api/innrapportert/inntektsmottaker/hendelser/?fraSekvensnummer=1&antall=5"
{
    "hendelser": [
        {
            "sekvensnummer": 1,
            "identifikator": "09048000875",
            "gjelderPeriode": "2015"
        },
        {
            "sekvensnummer": 12,
            "identifikator": "20125001158",
            "gjelderPeriode": "2015"
        },
        {
            "sekvensnummer": 23,
            "identifikator": "02043700564",
            "gjelderPeriode": "2015"
        },
        {
            "sekvensnummer": 34,
            "identifikator": "17014200150",
            "gjelderPeriode": "2015"
        },
        {
            "sekvensnummer": 45,
            "identifikator": "17055401993",
            "gjelderPeriode": "2015"
        }
    ]
}

XML

hendelser.xsd

hendelser.xml (eksempel)

Første sekvensnummer fra dato suksess (HTTP status 200)

$ curl -v --cert datakonsument.cer --key datakonsument.key "https://api-at.sits.no/api/innrapportert/inntektsmottaker/hendelser/start?dato=2017-08-01"
{
    "sekvensnummer": 21
}

Feilmeldinger (HTTP status ikke 200)

Hvis statuskode ikke er 200, men man får svar fra applikasjonen, så kommer en feilmelding på følgende format. Dersom feilmeldingen ikke er på dette formatet, kan det være forespørselen ikke har kommet fram til applikasjonen. Se den generelle informasjonen om statuskoder og feilmeldinger.

{
  "kode": "FA-001",
  "melding": "fraSekvensnummer må være satt"
}

XML

feil.xsd

feil.xml (eksempel)

Feilkoder

Se også felles feilkoder for alle applikasjonene.

HTTP status Feilkode Tekst
400 FA-001 fraSekvensnummer må være satt
400 FA-002 fraSekvensnummer må være større enn 0
400 FA-003 antall må være spesifisert
400 FA-004 antall må være større enn 0
500 FA-009 Fikk ikke hentet data fra databasen, vennligst prøv igjen senere!
404 FA-010 Fant ingen informasjon i databasen
400 FA-013 Dato har ugyldig format. Forventet YYYY-MM-DD.
404 FA-014 Fant ingen sekvensnummer.
400 FA-015 Ugyldig dokumenttype.

Miljøer

Miljø URL
Akseptansetest (AT) http://api-at.sits.no
Produksjon (Prod) http://api.skatteetaten.no

Ønsker du å komme i kontakt med oss for spørsmål eller andre henvendelser, se veiledning på Skatteetaten.no.

Tags: