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-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 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-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 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-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 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-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:

feil.xsd

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.