Tjenestepensjonsavtale API

Grensesnittbeskrivelse

For å bruke grensesnittet kreves [autentisering med Maskinporten-token].

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 adresse
• <rettighetspakke>: En kode for virksomheten sitt juridiske grunnlag for datauthenting. Se Rettighetspakk
• <pensjonsinnretning>: Identifikator (Organisasjonsnummer) for pensjonsinnretning.
• <opplysningspliktig>: Identifikator (Organisasjonsnummer) for opplysningspliktig.
• <fraOgMed>: Start årstall og måned for avtaleinngåelse angitt i nummer, må oppgis som YYYY-MM.
• <tilOgMed>: Slutt årstall og måned for avtaleinngåelse angitt i nummer, må ppgis som YYYY-MM.

POST https://<env>/api/tjenestepensjonsavtale/v1/<rettighetspakke>/avtaleforhold

• <env>: Miljø-spesifikk adresse
• <rettighetspakke>: En kode for virksomheten sitt juridiske grunnlag for datauthenting. Se Rettighetspakk

Dokumentformat:

TjenestepensjonsavtaleAvtaleforholdV1.xsd

TjenestepensjonsavtaleAvtaleforholdV1.json

DELETE https://<env>/api/tjenestepensjonsavtale/v1/<rettighetspakke>/avtaleforhold

• <env>: Miljø-spesifikk adresse
• <rettighetspakke>: En kode for virksomheten sitt juridiske grunnlag for datauthenting. Se Rettighetspakk

Dokumentformat:

TjenestepensjonsavtaleAvtaleforholdSlettV1.xsd

TjenestepensjonsavtaleAvtaleforholdSlettV1.json

Versjonering

Se generelle regler for versjonering.

Eksempel på respons fra tjenesten

Under følger ekempler på kall mot Tjenestepensjonsavtale-api. Alle kall må ha maskinporten token som parametre til curl-kommandoen.

Hente gyldighet:

$ curl -v -H "Authorization: Bearer {maskinporten_token}" "https://api-at.sits.no/api/tjenestepensjonsavtale/v1/{rettighetspakke}/avtaleforhold/gyldighet?opplysningspliktig=987654321&pensjonsinnretning=123456789&fraOgMed=2020-01&tilOgMed=2020-06"

Registrere avtale:

$ 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-at.sits.no/api/tjenestepensjonsavtale/v1/{rettighetspakke}/avtaleforhold"

Endre avtale:

$ 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-at.sits.no/api/tjenestepensjonsavtale/v1/{rettighetspakke}/avtaleforhold"

Slette avtale:

$ curl -v -H "Content-Type: application/json" -H "Authorization: Bearer {maskinporten_token}" -X DELETE -d '{"avtalereferanse" : "referanse til avtale","opplysningspliktig" : {"norskIdentifikator" : "999999999"}}' "https://api-at.sits.no/api/tjenestepensjonsavtale/v1/{rettighetspakke}/avtaleforhold"

Suksess (HTTP status 200 eller 201)

For henting av avtaleforholdGyldighet, 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. For registrering av avtale, dersom kallet lykkes får man HTTP status 201 og ingen data i respons. For endring av avtale, dersom kallet lykkes får man HTTP status 201 og ingen data i respons. For sletting av avtale, dersom kallet lykkes får man HTTP status 200 og ingen data i respons.

JSON

{
  "gyldig": "false",
  "maanederUtenGyldigAvtaleforhold": {
    "maaned": [
      "2020-01",
      "2020-02",
      "2020-04"
E
    ]
  }
}

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-at.sits.no/api/tjenestepensjonsavtale/v1/{rettighetspakke}/avtaleforhold/gyldighet?opplysningspliktig=987654321&pensjonsinnretning=123456789&fraOgMed=2020-01&tilOgMed=2020-06"

tjenestepensjonsavtaleAvtaleforholdGyldighet.xsd

tjenestepensjonsavtaleAvtaleforholdGyldighet.xml (eksempel)

Feilmeldinger (HTTP status ikke 200)

Hvis statuskode ikke er 200 eller 201, 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": "OTP-003",
 "melding": "Obligatorisk parameter 'pensjonsinnretning' mangler.",
 "korrelasjonsid": "df496591-dabc-42b8-84e2-163ad19302e6"
}

XML

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

feil.xsd

feil_tjenestepensjonsavtale_api.xml (eksempel)

Feilkoder

Se også felles feilkoder for alle applikasjonene.

Miljøer

Ønsker du å komme i kontakt med oss for spørsmål eller andre henvendelser, se veiledning på Skatteetaten.no.