API for å svare på oppslag om gyldighet for avtaleforhold, dvs. informasjon om pensjonsinnretning har gyldig avtale med opplysningspliktig, registrere og oppdatere avtale, og slette avtale.

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

Dokumentformat:

TjenestepensjonsavtaleAvtaleforholdV1.xsd

TjenestepensjonsavtaleAvtaleforholdV1.json

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

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.

HTTP status Feilkode Feilmelding
404 OTP-001 Fant ikke den forespurte AvtaleforholdGyldigheten.
400 OTP-002 Feltet ‘rettighetspakke’ mangler eller ugyldig.
400 OTP-003 Obligatorisk parameter ‘pensjonsinnretning’ mangler.
400 OTP-004 Parameteren ‘pensjonsinnretning’ har ugyldig format. Må være nøyaktig 9 sifre
400 OTP-005 Obligatorisk parameter ‘opplysningspliktig’ mangler.
400 OTP-006 Parameteren ‘opplysningspliktig’ har ugyldig format. Må være nøyaktig 9 sifre
400 OTP-007 Obligatorisk parameter ‘fraOgMed’ mangler.
400 OTP-008 Parameteren ‘fraOgMed’ har ugyldig format. må oppgis som YYYY-MM
400 OTP-009 Obligatorisk parameter ‘tilOgMed’ mangler.
400 OTP-010 Parameteren ‘tilOgMed’ har ugyldig format. må oppgis som YYYY-MM
403 OTP-011 En uventet feil oppstod ved autentisering. Kontakt brukerstøtte.
500 OTP-012 Det skjedde en feil i forbindelse med maskinporten autentisering: token mangler.
500 OTP-013 Det skjedde en feil i forbindelse med maskinporten autentisering: token invalid.
404 OTP-014 Fant ikke den forespurte avtalen
400 OTP-015 Parameteren ‘avtalereferanse’ har ugyldig format. Maks 4000 tegn
400 OTP-016 Parameteren ‘tilOgMed’ kan ikke være før parameteren ‘fraOgMed’
400 OTP-017 Parameteren ‘tilOgMed’ kan ikke være inn i fremtiden
400 OTP-018 Feil i request mot bakenforliggende system
403 OTP-019 En uventet feil oppstod ved autentisering mot bakendforliggende system. Kontakt brukerstøtte.
503 OTP-020 Ikke kontakt mot bakendforliggende system. Kontakt brukerstøtte.
500 OTP-021 Ukjent feil mot bakendforliggende system. Kontakt brukerstøtte.

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: