Tjenestepensjonsavtale API

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 adresse
• <rettighetspakke>: En kode for virksomheten sitt juridiske grunnlag for datauthenting. Se Rettighetspakke
• <pensjonsinnretning>: 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-at.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 adresse
• <rettighetspakke>: En kode for virksomheten sitt juridiske grunnlag for datauthenting. Se Rettighetspakke
• <pensjonsinnretning>: 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-at.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 adresse
• <rettighetspakke>: 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-at.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 adresse
• <rettighetspakke>: 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-at.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.

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-at.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 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"
}

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.