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:tjenestepensjonsavtale
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: Tjenestepensjonsavtale API.
Grensesnittbeskrivelse
Hent avtaleforhold gyldighet
URL har følgede oppbygging:
GET https://{env}/api/tjenestepensjonsavtale/v1/{rettighetspakke}/avtaleforhold/gyldighet?pensjonsinnretning={pensjonsinnretning}&opplysningspliktig={opplysningspliktig}&fraOgMed={fraOgMed}&tilOgMed={tilOgMed}
env
: Miljø-spesifikk adresserettighetspakke
: En kode for virksomheten sitt juridiske grunnlag for datauthenting. Se Rettighetspakkepensjonsinnretning
: Identifikator (Organisasjonsnummer) for pensjonsinnretning.opplysningspliktig
: Identifikator (Organisasjonsnummer) for opplysningspliktig.fraOgMed
: Start årstall og måned for første måned som skal hentes, må oppgis som YYYY-MM.tilOgMed
: Slutt årstall og måned for siste måned som skal hentes, må oppgis som YYYY-MM.
Lenke til informasjonsmodell: Tjenestepensjonsavtale avtaleforhold gyldighet
Eksempel på kall
$ curl -v -H "Authorization: Bearer {maskinporten_token}" "https://api-test.sits.no/api/tjenestepensjonsavtale/v1/{rettighetspakke}/avtaleforhold/gyldighet?opplysningspliktig=987654321&pensjonsinnretning=123456789&fraOgMed=2020-01&tilOgMed=2020-06"
Suksess
For henting av gyldighet, 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.
Eksempel på respons
{
"gyldig": "false",
"maanederUtenGyldigAvtaleforhold": {
"maaned": [
"2020-01",
"2020-02",
"2020-04"
]
}
}
Hent virkningsperiode gyldighet
URL har følgede oppbygging:
GET https://{env}/api/tjenestepensjonsavtale/v1/{rettighetspakke}/avtaleforhold/virkningsperiode/gyldighet?pensjonsinnretning={pensjonsinnretning}&opplysningspliktig={opplysningspliktig}&fraOgMed={fraOgMed}&tilOgMed={tilOgMed}
env
: Miljø-spesifikk adresserettighetspakke
: En kode for virksomheten sitt juridiske grunnlag for datauthenting. Se Rettighetspakkepensjonsinnretning
: Identifikator (Organisasjonsnummer) for pensjonsinnretning.opplysningspliktig
: Identifikator (Organisasjonsnummer) for opplysningspliktig.fraOgMed
: Start årstall og måned angitt i nummer, må oppgis som YYYY-MM.tilOgMed
: Slutt årstall og måned angitt i nummer, må oppgis som YYYY-MM.
Lenke til informasjonsmodell: Tjenestepensjonsavtale virkningsperiode gyldighet
Eksempel på kall
$ curl -v -H "Authorization: Bearer {maskinporten_token}" "https://api-test.sits.no/api/tjenestepensjonsavtale/v1/{rettighetspakke}/avtaleforhold/virkningsperiode/gyldighet?opplysningspliktig=987654321&pensjonsinnretning=123456789&fraOgMed=2020-01&tilOgMed=2020-06"
Suksess
For henting av gyldig virkningsperiode, 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.
Eksempel på respons
{
"gyldig": false,
"maanederUtenforGyldigVirkningsperiode": {
"maaned": [
"2020-01",
"2020-02",
"2020-03"
]
}
}
Registrere / endre avtale:
URL har følgede oppbygging:
POST https://{env}/api/tjenestepensjonsavtale/v1/<rettighetspakke>/avtaleforhold
env
: Miljø-spesifikk adresserettighetspakke
: En kode for virksomheten sitt juridiske grunnlag for datauthenting. Se Rettighetspakke
Lenke til informasjonsmodell: Tjenestepensjonsavtale avtaleforhold
Dokumentformat:
TjenestepensjonsavtaleAvtaleforholdV1.xsd
TjenestepensjonsavtaleAvtaleforholdV1.json
Eksempel på kall
$ curl -v -H "Content-Type: application/json" -H "Authorization: Bearer {maskinporten_token}" -X POST -d '{"avtalereferanse" : "referanse til avtale","fraOgMed" : "2020-01","opplysningspliktig" : {"norskIdentifikator" : "999999999"}}' "https://api-test.sits.no/api/tjenestepensjonsavtale/v1/{rettighetspakke}/avtaleforhold"
Suksess
For registrering og endring av avtale, dersom kallet lykkes får man HTTP status 201 og ingen data i respons.
Slette avtale
URL har følgede oppbygging:
DELETE https://<env>/api/tjenestepensjonsavtale/v1/{rettighetspakke}/avtaleforhold
env
: Miljø-spesifikk adresserettighetspakke
: En kode for virksomheten sitt juridiske grunnlag for datauthenting. Se Rettighetspakke
Lenke til informasjonsmodell: Tjenestepensjonsavtale forhold slette
Dokumentformat:
TjenestepensjonsavtaleAvtaleforholdSlettV1.xsd
TjenestepensjonsavtaleAvtaleforholdSlettV1.json
Eksempel på kall
$ curl -v -H "Content-Type: application/json" -H "Authorization: Bearer {maskinporten_token}" -X DELETE -d '{"avtalereferanse" : "referanse til avtale","opplysningspliktig" : {"norskIdentifikator" : "999999999"}}' "https://api-test.sits.no/api/tjenestepensjonsavtale/v1/{rettighetspakke}/avtaleforhold"
Suksess
For sletting av avtale, dersom kallet lykkes får man HTTP status 200 og ingen data i respons.
Open Api Specification
Teknisk spesifikasjon av API’et er publisert på SwaggerHub: Tjenestepensjonsvtale API
Versjonering
Se generelle regler for versjonering.
XML
For svar på XML format, sett header Accept
til application/xml
:
$ curl -v -H "Accept: application/xml" -H "Authorization: Bearer {maskinporten_token}" "https://api-test.sits.no/api/tjenestepensjonsavtale/v1/{rettighetspakke}/avtaleforhold/gyldighet?opplysningspliktig=987654321&pensjonsinnretning=123456789&fraOgMed=2020-01&tilOgMed=2020-06"
tjenestepensjonsavtaleAvtaleforholdGyldighet.xsd
tjenestepensjonsavtaleAvtaleforholdGyldighet.xml (eksempel)
Feilhåndtering
Feilmeldinger (HTTP status ikke 200)
Hvis statuskode ikke er 200 eller 2001, 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.
XML
Dersom Accept
-header er satt til application/xml
vil også eventuell feilmelding være i XML:
JSON
{
"kode": "OTP-005",
"melding": "Du er ikke autorisert for tilgang til den forespurte ressursen.",
"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 |
---|---|---|
OTP-001 | 500 | Uventet feil på tjenesten. |
OTP-002 | 500 | Uventet feil i et bakenforliggende system. |
OTP-003 | 404 | Ukjent url benyttet. |
OTP-004 | 401 | Feil i forbindelse med autentisering. |
OTP-005 | 403 | Feil i forbindelse med autorisering. |
OTP-006 | 400 | Feil i forbindelse med validering av inputdata. |
OTP-007 | 404 | Ingen data funnet på oppgitte inputparametere. |
OTP-008 | 406 | Feil tilknyttet dataformat. Kun json eller xml er støttet. |