Sikkerhet
Denne tjenesten støtter kun bruk av maskinporten. Se Sikkerhetsmekanismer for informasjon om de ulike sikkerhetsløsningene.
Bruk med Maskinporten
Følgende scope skal benyttes ved autentisering i Maskinporten:
skatteetaten:inntekt
Delegering
Tilgang til denne tjenesten kan delegeres i Altinn, f.eks. dersom leverandør benyttes for den tekniske oppkoblingen. Søk opp følgende tjeneste i Altinn for å delegere tilgangen: Inntekt API.
Grensesnittbeskrivelse
URL har følgede oppbygging:
Url som skal benyttes:
GET https://<env>/api/innrapportert/inntektsmottaker/v1/<rettighetspakke>/<personidentifikator>/inntekter?fraOgMed=<YYYY-MM>[&tilOgMed=<YYYY-MM>][&opplysningspliktig=<opplysningspliktig>]
Gammel url som skal utfases:
GET https://<env>/api/innrapportert/inntektsmottaker/<rettighetspakke>/<personidentifikator>/oppgave/inntekt?fraOgMed=<YYYY-MM>[&tilOgMed=<YYYY-MM>]
<env>
: Miljø-spesifikk adresse<rettighetspakke>
: En av rettighetspakkeneafp
,gff
,husbanken
,kommuneboligsosialeformaal
,ldir
,laanekassen
,pensjonskasse
,sbl
,spkboliglaan
ogudi
.<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. DersomtilOgMed
ikke er satt brukes inneværende måned som parameter.opplysningspliktig=<opplysningspliktig>
: Identifikator (Organisasjonsnummer, fødselsnummer eller d-nummer) for opplysningspliktig. Parameteren opplysningspliktig er kun påkrevd for rettighetspakken OTP, for å sjekke at pensjonsinnretning har en gyldig avtale med opplysningspliktig for en forespurt periode. Kun med gyldig avtale kan pensjonsinnretning få tilgang til inntektsdata. Parameteren opplysningspliktig skal ikke brukes for andre type rettighetspakker.
Lenke til informasjonsmodell: Inntekt
Periodisering
Inntektsdata 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 inntektsdata.
Støttetjenester
Hendelsesliste
For å følge med på endringer i inntekt tilbyr vi en hendelsesliste. URL er:
GET https://<env>/api/innrapportert/inntektsmottaker/hendelser/
Se felles API-dokumentasjon for hendelseslister for bruk.
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 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"
Open API spesifikasjon
Teknisk spesifikasjon av API’et er publisert på SwaggerHub: Inntekt_API
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
Spesifikasjon av return for tjenesten: Inntektsmottaker.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
}
}
]
}
]
}
Samtykkeoppsett
(Gjelder bare datakonsumenter som henter data basert på samtykke)
Tjenestekode | Parametere v/ redirect til Altinn | Eksempel parameter verdi |
---|---|---|
4804_210607 | 4804_210607_fraOgMed, 4804_210607_tilOgMed | &4804_210607_fraOgMed=2021-03&4804_210607_tilOgMed=2021-06 |
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. I enkelte tilfeller kan forespørsler stoppes i infrastrukturen før den når applikasjonen. I disse tilfellene kan det forekomme feilmeldinger som ikke følger formatet oppgitt ovenfor.
JSON
{
"kode": "IM-005",
"melding": "Du er ikke autorisert for bruk av dette endepunktet.",
"korrelasjonsid": "456420a2-6689-4cda-8102-8be499a892dd"
}
Feilkoder
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 |
---|---|---|
IM-001 | 500 | Uventet feil på tjenesten. |
IM-002 | 500 | Uventet feil i et bakenforliggende system. |
IM-003 | 404 | Ukjent url benyttet. |
IM-004 | 401 | Feil i forbindelse med autentisering. |
IM-005 | 403 | Feil i forbindelse med autorisering. |
IM-006 | 400 | Feil i forbindelse med validering av inputdata. |
IM-007 | 404 | Ikke treff på oppgitt personidentifikator. |
IM-008 | 404 | Fant ingen inntektsopplysninger for angitt personidentifikator og tidspunkt. |
IM-009 | 406 | Feil tilknyttet dataformat. Kun json eller xml er støttet. |
IM-010 | 403 | Feil i forbindelse med samtykke. |