Inntektsmottaker API leverer innrapporterte inntektsopplysninger for en skattyter for en gitt periode. Informasjonen som avleveres er tilsvarende det som innrapporteres av arbeidsgivere.

Sikkerhet

Denne tjenesten støtter både bruk av maskinporten og virksomhetssertifikat. 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: Inntektsmottaker 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 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. Dersom tilOgMed ikke er satt brukes inneværende måned som parameter.
  • opplysningspliktig=<opplysningspliktig>: Identifikator (Organisasjonsnummer) 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 inntektsmottaker data. Parameteren opplysningspliktig skal ikke brukes for andre type rettighetspakker.

Lenke til informasjonsmodell: Inntektsmottaker

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.

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.

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

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
                    }
                }
            ]
        }
    ]
}

XML

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

inntektsmottaker.xsd

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:

feil.xsd

feil.xml (eksempel)

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 Obligatorisk felt ‘personidentifikator’ 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 Obligatorisk felt ‘fraOgMed’ mangler.
IM-004 400 Feltet ‘fraOgMed’ har ugyldig format. Må følge ‘yyyy-mm’
IM-005 400 Obligatorisk 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 Obligatorisk felt ‘fraOgMed’ kan ikke være frem i tid.
IM-010 404 Fant ingen informasjon for gitt identifikator og periode.
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-token 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-026 400 Ingen JWT token i forespoersel.
IM-027 404 Fant ikke noen informasjon om inntektsmottakere for opplysningspliktig og periode.
IM-028 400 Feil i request mot bakenforliggende system.
IM-029 500 Det var en uventet feil på tjenesten. Vennligst ta kontakt med brukerstøtte med applikasjon og korrelasjonsid fra denne meldingen!
IM-030 403 En uventet feil oppstod ved autentisering. Kontakt brukerstøtte.
IM-031 400 Token inneholder ikke claims.
IM-032 400 Obligatorisk felt ‘opplysningspliktig’ er ugyldig.
IM-033 403 Pensjonsinnretningen har ikke gyldig avtale med opplysningspliktig i den forespurte perioden.
IM-034 404 Fant ikke den forespurte avtalen for opplysningspliktig og periode

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.

Tags: