Tjenestene leverer løpende varslinger om personer/virksomheter med nye eller endrede opplysninger tilgjengelig.

Grensesnittbeskrivelse

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

Se Sikkerhetsmekanismer for informasjon om hva som kreves for å få tilgang til grensesnittet.

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 følgende hendelseslister med apipath i parentes:
    • Inntektsmottaker hendelser (/api/innrapportert/inntektsmottaker/hendelser/)
    • Mva-melding hendelser (/api/merverdiavgift/mvamelding/hendelser/)
    • Næringsspesifikasjon hendelser (/api/formueinntekt/naeringsspesifikasjon/v1/hendelser/)
    • Skattepliktig hendelser (/api/part/skattepliktig/hendelser/)
    • Skatteoppgjør hendelser (/api/formueinntekt/skatteoppgjoer/hendelser/)
    • Skattemelding upersonlig hendelser (/api/formueinntekt/skattemeldingupersonlig/fastsatt/hendelser/)
    • Skattemelding utkast hendelser (/api/formueinntekt/skattemelding/utkast/hendelser/)
    • Skattemelding fastsatt hendelser (/api/formueinntekt/skattemelding/fastsatt/hendelser/)
    • Tilleggsskatt hendelser (/api/formueinntekt/tilleggsskatt/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.

Open Api Specification

Teknisk spesifikasjon av hendelseslistene er publisert på SwaggerHub. Foreløpig gjelder dette:

Versjonering

Se generelle regler for versjonering.

Eksempler

Her er et par 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) for Inntekstmottaker hendelser

$ 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": "2018"
        },
        {
            "sekvensnummer": 12,
            "identifikator": "20125001158",
            "gjelderPeriode": "2018"
        },
        {
            "sekvensnummer": 23,
            "identifikator": "02043700564",
            "gjelderPeriode": "2018"
        },
        {
            "sekvensnummer": 34,
            "identifikator": "17014200150",
            "gjelderPeriode": "2018"
        },
        {
            "sekvensnummer": 45,
            "identifikator": "17055401993",
            "gjelderPeriode": "2018"
        }
    ]
}

XML

hendelser.xsd

hendelser.xml (eksempel)

Hendelsesliste suksess (HTTP status 200) for Skattemelding fastsatt hendelser

Skattemelding fastsatt hendelser, Skattemelding utkast hendelser og Skatteoppgjør hendelser inneholder informasjon om registreringstidspunkt og hendelsetype i tillegg.

$ curl -v --cert datakonsument.cer --key datakonsument.key "https://api-at.sits.no/api/formueinntekt/skattemelding/fastsatt/hendelser/?fraSekvensnummer=1&antall=5"
{
  "hendelser": [
    {
      "sekvensnummer": 1,
      "identifikator": "28064701918",
      "gjelderPeriode": "2020",
      "registreringstidspunkt": "2021-03-10T09:29:16.000000Z",
      "hendelsetype": "NY"
    },
    {
      "sekvensnummer": 2,
      "identifikator": "29114501318",
      "gjelderPeriode": "2020",
      "registreringstidspunkt": "2021-03-10T08:02:43.000000Z",
      "hendelsetype": "NY"
    },
    {
      "sekvensnummer": 3,
      "identifikator": "10038500495",
      "gjelderPeriode": "2020",
      "registreringstidspunkt": "2021-04-16T12:29:39.000000Z",
      "hendelsetype": "NY"
    },
    {
      "sekvensnummer": 4,
      "identifikator": "25035401310",
      "gjelderPeriode": "2020",
      "registreringstidspunkt": "2021-04-16T11:31:32.000000Z",
      "hendelsetype": "NY"
    },
    {
      "sekvensnummer": 5,
      "identifikator": "01065402439",
      "gjelderPeriode": "2020",
      "registreringstidspunkt": "2021-04-16T10:01:03.000000Z",
      "hendelsetype": "NY"
    }
  ]
}

Hendelsesliste suksess (HTTP status 200) for Næringsspesifikasjon hendelser

Næringsspesifikasjon hendelser inneholder også informasjon om registreringstidspunkt, hendelsetype og typeSkattepliktig i tillegg.

$ curl -v --cert datakonsument.cer --key datakonsument.key "https://api-at.sits.no/api/formueinntekt/naeringsspesifikasjon/v1/hendelser/?fraSekvensnummer=1&antall=9"
{
    "hendelser": [
        {
            "sekvensnummer": 1,
            "identifikator": "25038804416",
            "gjelderPeriode": "2020",
            "registreringstidspunkt": "2022-01-19T09:40:03Z",
            "hendelsetype": "NY",
            "typeSkattepliktig": "personligSkattepliktig"
        },
        {
            "sekvensnummer": 2,
            "identifikator": "25015201137",
            "gjelderPeriode": "2020",
            "registreringstidspunkt": "2022-01-25T10:49:19Z",
            "hendelsetype": "NY",
            "typeSkattepliktig": "personligSkattepliktig"
        },
        {
            "sekvensnummer": 3,
            "identifikator": "25015201137",
            "gjelderPeriode": "2020",
            "registreringstidspunkt": "2022-01-25T09:53:30.774522Z",
            "hendelsetype": "NY",
            "typeSkattepliktig": "upersonligSkattepliktig"
        },
        {
            "sekvensnummer": 4,
            "identifikator": "10037819471",
            "gjelderPeriode": "2020",
            "registreringstidspunkt": "2022-02-10T14:04:08Z",
            "hendelsetype": "NY",
            "typeSkattepliktig": "upersonligSkattepliktig"
        },
        {
            "sekvensnummer": 5,
            "identifikator": "29026009527",
            "gjelderPeriode": "2020",
            "registreringstidspunkt": "2022-02-11T12:04:50Z",
            "hendelsetype": "NY",
            "typeSkattepliktig": "personligSkattepliktig"
        },
        {
            "sekvensnummer": 6,
            "identifikator": "02118001764",
            "gjelderPeriode": "2020",
            "registreringstidspunkt": "2022-02-21T11:50:57.626248Z",
            "hendelsetype": "NY",
            "typeSkattepliktig": "personligSkattepliktig"
        },
        {
            "sekvensnummer": 7,
            "identifikator": "24065600842",
            "gjelderPeriode": "2020",
            "registreringstidspunkt": "2022-01-18T14:24:01Z",
            "hendelsetype": "NY",
            "typeSkattepliktig": "personligSkattepliktig"
        },
        {
            "sekvensnummer": 8,
            "identifikator": "24085701718",
            "gjelderPeriode": "2020",
            "registreringstidspunkt": "2022-01-14T16:34:22Z",
            "hendelsetype": "NY",
            "typeSkattepliktig": "personligSkattepliktig"
        },
        {
            "sekvensnummer": 9,
            "identifikator": "15124802560",
            "gjelderPeriode": "2020",
            "registreringstidspunkt": "2022-01-18T13:46:27Z",
            "hendelsetype": "NY",
            "typeSkattepliktig": "personligSkattepliktig"
        }
    ]
}

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.

Nye feilkoder

Noen av hendelseslistene har tatt i bruk nye feilkoder. For øyeblikket gjelder dette for Skatteoppgjør hendelser, Inntektsmottaker hendelser, Tilleggsskatt hendelser, Skattemelding fastsatt hendelser og Skattemelding utkast hendelser.

Tabellen under viser en oversikt over hvilke typer feil applikasjonen kan gi. Feilmeldingen vil kunne variere selv om samme feilkode returneres. Dette er for å kunne gi en så presis beskrivelse av feilen som mulig. Ved vedvarende feil vennligst ta kontakt med brukerstøtte med applikasjon og korrelasjonsid fra feilmelding.

Feilkode HTTP Statuskode Feilområde
FA-001 500 Uventet feil på tjenesten.
FA-002 404 Ukjent url benyttet.
FA-003 401 Feil i forbindelse med autentisering.
FA-004 400 Feil i forbindelse med validering av inputdata.
FA-005 404 Ingen hendelser funnet for oppgitt input.
FA-006 406 Feil tilknyttet dataformat. Kun json eller xml er støttet.
Tags: