Støttetjenester
Hendelsesliste
For å følge med på endringer i Inntektsmottaker tilbyr vi en hendelsesliste. URL er:
GET https://<env>/api/innrapportert/inntektsmottaker/hendelser/
Se felles API-dokumentasjon for hendelseslister for bruk.
Periodisering
Inntektsmottaker data er et aggregat av innrapporterte data fra forskjellige kilder. Hver dataperiode (måned) bygges opp gradvis i takt med at det rapporteres inn nye data. Se periodisering veiledning for hvordan man best velger spørreperiode for inntektsmottaker data.
Grensesnittbeskrivelse
For å bruke grensesnittet kreves autentisering med X.509-sertifikat.
URL har følgede oppbygging:
GET https://<env>/api/innrapportert/inntektsmottaker/<rettighetspakke>/<personidentifikator>/oppgave/inntekt?fraOgMed=<YYYY-MM>[&tilOgMed=<YYYY-MM>]
<env>: Miljø-spesifikk adresse<rettighetspakke>: En av rettighetspakkene sbl, pensjonskasse, gff, ldir, laanekassen, husbanken, udi, afp.<personidentifikator>: Hvilket fødselsnummer eller D-nummer man spør om informasjon for.fraOgMed=<YYYY-MM>: Fra og med hvilken periode innrapporterte inntekter skal leveres.tilOgMed=<YYYY-MM>: Til og med hvilken periode innrapporterte inntekter skal leveres. Valgfritt parameter. DersomtilOgMedikke er satt brukes inneværende måned som parameter.
Bruk med samtykke
For Datakonsumenter som benytter Samtykke gjelder en del tilleggskrav:
AltinnSamtykke header
Må legge ved en ekstra header AltinnSamtykke. Verdien i denne headeren skal være et Json Web Token (JWT) signert av Altinn. Tokenet er en representasjon av samtykket man har innhentet fra skattyteren man henter data for. For informasjon rundt hvordan man skaffer et slikt token, sjekk Altinn: hente token
Begrenset til rettighetspakke sbl
Datakonsumenter som henter data basert på samtykke tildeles rettighetspakken Inntektsmottaker sbl. Se informasjonsmodell for detaljer.
Restriksjoner på spørreperiode
Datakonsumenter med samtykke har kun lov til å spørre om data for de 6 siste månedene.
Eksempel på respons fra tjenesten
Her er et eksempel på en spørring med curl mot tjenesten. Du må legge sertifikat og nøkkel som parametre til curl-kommandoen.
$ curl -v --cert datakonsument.cer --key datakonsument.key -H "AltinnSamtykke: <samtykke>" "https://api-at.sits.no/api/innrapportert/inntektsmottaker/sbl/12345678901/oppgave/inntekt?fraOgMed=2016-11&tilOgMed=2017-01"
Under er eksempler på respons fra inntektstjenesten.
Data kommer som en liste med OppgaveInntektsmottaker (oppgaver som gjelder en inntektsmottaker).
Hver OppgaveInntektsmottaker har
- litt informasjon om oppgaven
- kalendermåned
- inntektsmottaker
- opplysningspliktig
- virksomhet (underenhet til opplysnigspliktig)
- en liste med inntekter. NB! Hvordan denne listen representeres vil for JSON avvike fra strukturen som er beskrevet i XSD. For json-se eksempel nedenfor.
Suksess (HTTP status 200)
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.
JSON
{
"oppgaveInntektsmottaker": [
{
"opplysningspliktigId": "811094242",
"virksomhetId": "811094552",
"kalendermaaned": "2018-07",
"inntektsmottaker": {
"personidentifikator": "01029413157"
},
"inntekt": [
{
"fordel": "utgiftsgodtgjoerelse",
"utloeserArbeidsgiveravgift": false,
"inngaarIGrunnlagForTrekk": false,
"beloep": 5100,
"loennsinntekt": {
"beskrivelse": "reiseKostMedOvernattingPaaHotellBeordringUtover28Doegn",
"spesifikasjon": {
"opptjeningsland": "DZ"
},
"antall": 51
}
},
{
"fordel": "naturalytelse",
"utloeserArbeidsgiveravgift": true,
"inngaarIGrunnlagForTrekk": true,
"beloep": 6000,
"loennsinntekt": {
"beskrivelse": "bil",
"tilleggsinformasjon": {
"bilOgBaat": {
"antallKilometer": 600,
"heravAntallKilometerMellomHjemOgArbeid": 600,
"listeprisForBil": 6000,
"bilregistreringsnummer": "el12345",
"erBilUtenforStandardregelen": true
}
}
}
},
{
"fordel": "kontantytelse",
"utloeserArbeidsgiveravgift": true,
"inngaarIGrunnlagForTrekk": true,
"beloep": 150000,
"loennsinntekt": {
"beskrivelse": "timeloenn",
"antall": 150
}
},
{
"fordel": "kontantytelse",
"utloeserArbeidsgiveravgift": true,
"inngaarIGrunnlagForTrekk": true,
"beloep": 2400,
"loennsinntekt": {
"beskrivelse": "fastloenn",
"tilleggsinformasjon": {
"inntjeningsforhold": "utenlandskeSjoefolkSomIkkeErSkattepliktig"
},
"spesifikasjon": {
"skattemessigBosattILand": "AF"
}
}
},
{
"fordel": "utgiftsgodtgjoerelse",
"utloeserArbeidsgiveravgift": false,
"inngaarIGrunnlagForTrekk": false,
"beloep": 5000,
"loennsinntekt": {
"beskrivelse": "reiseKostMedOvernattingPaaHybelBrakkePrivat",
"antall": 50
}
},
{
"fordel": "utgiftsgodtgjoerelse",
"utloeserArbeidsgiveravgift": true,
"inngaarIGrunnlagForTrekk": true,
"beloep": 2900,
"loennsinntekt": {
"beskrivelse": "smusstillegg"
}
},
{
"fordel": "utgiftsgodtgjoerelse",
"utloeserArbeidsgiveravgift": false,
"inngaarIGrunnlagForTrekk": false,
"beloep": 2800,
"loennsinntekt": {
"beskrivelse": "overtidsmat",
"antall": 28
}
},
{
"fordel": "utgiftsgodtgjoerelse",
"utloeserArbeidsgiveravgift": false,
"inngaarIGrunnlagForTrekk": false,
"beloep": 4900,
"loennsinntekt": {
"beskrivelse": "reiseKostMedOvernattingPaaPensjonat",
"antall": 49
}
}
]
}
]
}
XML
Dersom man ønsker XML i stedet for JSON kan dette spesifiseres med header Accept satt til application/xml
inntektsmottaker.xml (eksempel)
inntektsmottaker-sbl.xml (eksempel uten tilleggsopplysninger og spesifikasjoner)
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.
JSON
{
"kode": "IM-006",
"melding": "Påkrevd felt 'fraOgMed' kan ikke være frem i tid."
}
XML
Dersom Accept-header er satt til application/xml vil også eventuell feilmelding være i XML:
Samtykkeoppsett
(Gjelder bare datakonsumenter som henter data basert på samtykke)
| Tjenestekode | Parametere v/ redirect til Altinn | Eksempel parameter verdi |
|---|---|---|
| 4804_170223 | 4804_170223_fraOgMed, 4804_170223_tilOgMed | &4804_170223_fraOgMed=2017-03&4804_170223_tilOgMed=2017-06 |
Feilkoder
Se også felles feilkoder for alle applikasjonene.
| Feilkode | HTTP Statuskode | Tekst |
|---|---|---|
| IM-000 | 400 | Påkrevd felt ‘foedselsnummer’ er ugyldig. |
| IM-001 | 400 | Feltet ‘tilOgMed’ kan ikke være før ‘fraOgMed’. |
| IM-002 | 400 | Feltet ‘tilOgMed’ har ugyldig format. Må følge ‘yyyy-mm’ |
| IM-003 | 400 | Påkrevd felt ‘fraOgMed’ mangler. |
| IM-004 | 400 | Feltet ‘fraOgMed’ har ugyldig format. Må følge ‘yyyy-mm’ |
| IM-005 | 400 | Påkrevd felt ‘fraOgMed’ kan ikke være eldre enn Januar 2015. Det foreligger ikke data i dette systemet fra før dette tidspunktet. |
| IM-006 | 400 | Påkrevd felt ‘fraOgMed’ kan ikke være frem i tid. |
| IM-010 | 404 | Fant ikke noen informasjon om inntekt for gitt fødselsnummer og dato. |
| IM-013 | 400 | Feil med samtykke signatur. Kunne ikke finne rett sertifikat for validering |
| IM-014 | 500 | Kunne ikke hente Altinn sertifikat fra Keystore. Ta kontakt med kundeservice |
| IM-018 | 400 | Feil med validering av samtykke fra Altinn. Kan ikke verifisere samtykke. |
| IM-019 | 400 | Samtykke er utgått på tid. |
| IM-020 | 400 | Feil med signatur av samtykke fra Altinn. Kan ikke verifisere samtykke. |
| IM-021 | 500 | Skattyter har skjermingskode som ikke kan tolkes. Kontakt kundeservice |
| IM-022 | 500 | En feil oppsto under validering av samtykke. Vennligst kontakt brukerstøtte. |
| IM-024 | 400 | Header AltinnSamtykke mangler. |
| IM-101 | 400 | Validering av samtykke feilet med feilmelding: |
Miljøer
| Miljø | URL |
|---|---|
| Akseptansetest (AT) | https://api-at.sits.no |
| Produksjon (Prod) | https://api.skatteetaten.no |
Ønsker du å komme i kontakt med oss for spørsmål eller andre henvendelser, se veiledning på Skatteetaten.no.