API for å registrere, oppdatere og slette opplysninger om avtale. API'et svarer også på gyldighet for avtaleforhold.

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

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

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 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 vedvarene 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.
Tags: