Grensesnittbeskrivelse

Tjeneste for å hente ut årets renteinntekter knyttet til Boligsparing for ungdom.

For å bruke grensesnittet kreves autentisering med X.509-sertifikat.

URL har følgede oppbygging:

GET https://<env>/api/innrapportert/boligsparingforungdom/<inntektsaar>/<personidentifikator>
  • <env>: Miljø-spesifikk adresse
  • <inntektsaar>: Inntektsåret man spør om informasjon for, i formatet YYYY.
  • <personidentifikator>: Hvilket fødselsnummer eller D-nummer man spør om informasjon for.

Versjonering

Se Om versjonering for generelle regler for versjonering.

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 -k https://api-at.sits.no/api/innrapportert/boligsparingforungdom/2017/08028830701 --key nøkkel.key --cert sertifikat.cer -XGET -H 'accept: application/json'

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

{
  "personidentifikator": "12345678901",
  "inntektsaar": "2019",
  "aaretsRenter": 100.00
}

XML

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

$ curl -v --header "Accept: application/xml" --cert datakonsument.cer --key datakonsument.key "https://api-at.sits.no/innrapportert/boligsparingforungdom/2017/08028830701"

<?xml version='1.0' encoding='UTF-8'?>
<boligsparingForUngdom xmlns="no:skatteetaten:datasamarbeid:boligsparingforungdom:v1">
   <personidentifikator>25120800194</personidentifikator>
   <inntektsaar>2015</inntektsaar>
   <aaretsRenter>534.00</aaretsRenter>
</boligsparingForUngdom>

boligsparingForUngdom.xsd

boligsparingForUngdom.xml (eksempel)

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": "BSA-003",
 "melding": "Du er ikke autorisert for bruk av dette endepunktet.",
 "korrelasjonsid": "23a235f5-28f9-47db-9abd-ab78977c32fa"
}

XML

Dersom Accept-header er satt til application/xml vil også eventuell feilmelding være i XML:

<feil xmlns="urn:no:skatteetaten:datasamarbeid:feil:v1">
   <kode>BSA-003</kode>
   <melding>Du er ikke autorisert for bruk av dette endepunktet.</melding>
   <korrelasjonsid>a621a996-315d-4b8a-ac6c-6239e67f03e7</korrelasjonsid>
</feil>

feil.xsd

feil.xml (eksempel)

Feilkoder

Se også felles feilkoder for alle applikasjonene.

Feilkode HTTP Statuskode Feilmelding
BSU-001 500 Fant ikke autentiseringstoken
BSU-002 401 Autentisering feilet
BSU-003 403 Du er ikke autorisert for bruk av dette endepunktet.
BSU-004 500 Den forespurte informasjonen er for øyeblikket utilgjengelig, vennligst prøv igjen senere! Dersom problemet vedvarer, ta kontakt med brukerstøtte!
BSU-005 400 Det forespurte identifikator er ikke støttet
BSU-006 400 Det forespurte inntektsåret er ikke støttet
BSU-007 400 Oppgitt accept header er ikke gyldig, vennligst velg mellom application/json eller application/xml
BSU-008 404 Fant ingen informasjon på oppgitt inntektsaar og personidentifikator

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: