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/)
- Mva-register – avgiftssubjekter med skattemeldingsplikt hendelser (/api/merverdiavgift/mvaregister/avgiftssubjekter/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:
- Inntektsmottaker hendelser
- Mva-melding hendelser
- Mva-register – avgiftssubjekter med skattemeldingsplikt hendelser
- Næringsspesifikasjon hendelser
- Skattepliktig hendelser
- Skatteoppgjør hendelser
- Skattemelding upersonlig hendelser
- Skattemelding utkast hendelser
- Skattemelding fastsatt hendelser
- Tilleggsskatt hendelser
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
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
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
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. |