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

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: