Trekkpålegg API
Målgruppen for siden er utviklere og IT-arkitekter hos systemleverandører som leverer lønns- og personalsystemer (eller sluttbrukersystemer) til arbeidsgivere. Slike systemer kalles i det videre sluttbrukersystemer og forkortes SBS. Det skal etableres et nytt grensesnitt for å formidle trekkpålegg fra Skatteetaten til arbeidsgivere med ansatte som skal ha utleggstrekk i lønn.
Grensesnittet vil på sikt erstatte det eksisterende grensesnittet for trekkformidling, men i første omgang vil det nye
grensesnittet komme i tillegg til det eksisterende grensesnittet. Grensesnittet vil først tilbys i et testmiljø,
deretter i piloter og til slutt i full produksjon.
Figuren under viser arkitekturen: 
Beskrivelse:
Skatteetaten etablerer en ny utleggstrekksak og oppretter en JSON-melding om dette i utleggstrekk-API
Send informasjon om nytt trekkpålegg til arbeidsgiver via Dialogporten Arbeidsgiver henter trekkpålegg fra Skatteetaten. 2a SBS henter et systembrukertoken fra Maskinporten 2b SBS utfører kall (get) mot trekkpålegg-API for å hente trekkpålegg Trekkpliktig arbeidsgiver kan også hente de samme trekkpåleggene fra Altinn-innboksen i Digdirs Felles arbeidsflate. En slik løsning vil videreføres også i fremtiden. For generell informasjon om tjenester fra Skatteetaten se egne sider om:
Scope
Følgende scope skal benyttes ved autentisering i Maskinporten: skatteetaten:trekkpaalegg.
Ved bruk av systembruker må forespørselen også inneholde ressurs-id ske-informasjon-om-trekkpaalegg som beskrevet her for produksjon: https://docs.altinn.studio/api/authentication/systemuserapi/systemuserrequest/external/#create-a-standard-system-user-request
Teknisk spesifikasjon
URL-er til API-et, beskrivelsen av parameterne, endepunkter og respons ligger i Open API spesifikasjonen på SwaggerHub.
Skatteetaten tilbyr API for å hente trekkpålegg.
Hovedtrekkene i det nye grensesnittet er:
- Grensesnittet er et maskin-maskin-grensesnitt som overfører trekkpålegg fra Skatteetaten til arbeidsgivere med SBS-systemer.
- Grensesnittet er basert på en RESTful-stil som tilbyr et API.
- SBS må spørre (poll) mot grensesnittet for å sjekke om det er nye trekkpålegg.
- Det vil etter hvert komme et grensesnitt der SBS kan motta notifikasjon (event) om at Skatteetaten har et nytt trekkpålegg til arbeidsgiver.
- I grensesnittet må SBS presentere et token som inneholder organisasjonsnummeret til trekkpliktig arbeidsgiver.
- Tokenet får SBS ved å koble seg opp mot Maskinporten med et gitt "scope".
- Trekkpålegget leveres i formatet JSON.
API Spesifikasjon
Skatteetaten tilbyr API for å hente trekkpålegg.
Open API spesifikasjonen er tilgjengelig her: swaggerhub
Trekkpålegg API
Alle URIer er relative til
https://api-test.sits.no (test) --- (prod) Metode HTTP request Beskrivelse hent alle gjeldende GET /api/trekkpaalegg/v1 Hent alle gjeldende trekkpålegg for den trekkpliktige hent versjon GET /api/trekkpaalegg/v1/trekkid/trekkversjon Hent en spesifikk versjon av et trekkpålegg.
Hent alle gjeldende
GET /api/trekkpaalegg/v1
Returnerer siste versjon av samtlige trekkpålegg for en trekkpliktig. Dersom en trekkpliktig har svært mange trekkpålegg (flere tusen) så bør man benytte fraSekvensnummer og maksAntall for begrense returen til kun å inneholde trekkpålegg som er endret siden forrige spørring. Dersom antall returnerte trekkpålegg er lik maksAntall så må det gjøres en ny spørring med fraSekvensnummer lik det største sekvensnummeret i siste retur inntil man har fått returnert samtlige endrede trekkpålegg.
Parametre
Navn Type Beskrivelse Notater fraSekvensnummer String Begrenser returnerte trekkpålegg til bare inneholde nyere enn angitt sekvensnummer. 0 eller større. Oppgis sammen med maksAntall. Mest relevant for trekkpliktige med svært mange trekkpålegg [default til null] maksAntall String Angir maks antall trekkpålegg som skal returneres. 1 eller større. Skal bare brukes sammen med fraSekvensnummer. Mest relevant for trekkpliktige med svært mange trekkpålegg [default til null]
Retur type
Liste av Trekkpaalegg https://skatteetaten.github.io/beta-apier/trekkpaalegg/feltbeskrivelser/Models/Trekkpaalegg
Autorisasjon
Se Tilgang https://skatteetaten.github.io/beta-apier/trekkpaalegg/tilgang
HTTP request headere
Content-Type: Ikke definert Accept: application/json, /
Hent versjon
GET /api/trekkpaalegg/v1/trekkid/trekkversjon Returnerer den angitte versjonen av et trekkpålegg
Parametre
Navn Type Beskrivelse Notater trekkid String Id til trekkpålegget [default til null] trekkversjon String Versjonen til det angitte trekkpålegg [default til null]
Retur type
Trekkpaalegg
Autorisasjon
Se Tilgang
HTTP request headere
Content-Type: Ikke definert Accept: application/json, /
Open API spesifikasjonen er tilgjengelig her :
swaggerhub Trekkpålegg API Alle URIer er relative til
https://api-test.sits.no (test) --- (prod) Metode HTTP request Beskrivelse hent alle gjeldende GET /api/trekkpaalegg/v1 Hent alle gjeldende trekkpålegg for den trekkpliktige hent versjon GET /api/trekkpaalegg/v1/:trekkid/:trekkversjon Hent en spesifikk versjon av et trekkpålegg. Hent alle gjeldende GET /api/trekkpaalegg/v1
Returnerer siste versjon av samtlige trekkpålegg for en trekkpliktig. Dersom en trekkpliktig har svært mange trekkpålegg (flere tusen) så bør man benytte fraSekvensnummer og maksAntall for begrense returen til kun å inneholde trekkpålegg som er endret siden forrige spørring. Dersom antall returnerte trekkpålegg er lik maksAntall så må det gjøres en ny spørring med fraSekvensnummer lik det største sekvensnummeret i siste retur inntil man har fått returnert samtlige endrede trekkpålegg.
Parametre Navn Type Beskrivelse Notater fraSekvensnummer String Begrenser returnerte trekkpålegg til bare inneholde nyere enn angitt sekvensnummer. 0 eller større. Oppgis sammen med maksAntall. Mest relevant for trekkpliktige med svært mange trekkpålegg [default til null] maksAntall String Angir maks antall trekkpålegg som skal returneres. 1 eller større. Skal bare brukes sammen med fraSekvensnummer. Mest relevant for trekkpliktige med svært mange trekkpålegg [default til null] Retur type Liste av Trekkpaalegg
Autorisasjon Se Tilgang
HTTP request headere Content-Type: Ikke definert Accept: application/json, / Hent versjon GET /api/trekkpaalegg/v1/trekkid/trekkversjon
Returnerer den angitte versjonen av et trekkpålegg
Parametre Navn Type Beskrivelse Notater trekkid String Id til trekkpålegget [default til null] trekkversjon String Versjonen til det angitte trekkpålegg [default til null] Retur type Trekkpaalegg
Autorisasjon Se Tilgang
HTTP request headere Content-Type: Ikke definert Accept: application/json, /
Datakatalog
Tilgang til tjenesten
Tilgang styres via Maskinporten.
For å få utstedt token av Maskinporten må lønnssystemet gjennom sitt virksomhetssertifikat angi hvilket organisasjonsnummer de representerer. Dette organisasjonsnummeret må være godkjent av Skatteetaten.
For å benytte tjenestene for trekkpålegg skal følgende scope angis ved autentisering i Maskinporten: skatteetaten:trekkpaalegg
API-et støtter to varianter av autentisering via Maskinporten. Disse er beskrevet under
Alternativ 1 - Systemleverandør er trekkpliktig
Dersom systemleverandør kun skal motta trekkpålegg for sin egen organisasjon, kan man benytte klassisk autentisering via Maskinporten. Mer informasjon om dette finnes her.
Alternativ 2 - Systembruker
Dersom systemleverandør ønsker å tilby funksjonalitet der en annen organisasjon (kunde av systemleverandøren) skal benytte systemet til å motta trekkpålegg, skal Altinn sin nye funksjonalitet for ‘systembruker’ benyttes. Mer informasjon om dette finnes i Altinn Systembruker for SBS og Systembruker roadmap.
Systemleverandør må for å støtte systembruker registrere seg i Maskinporten og Altinn test environment.
Testoppsett
Test uten bruk av systembruker (alternativ 1)
Valgfrie organisasjoner fra Tenor kan benyttes som trekkpliktig.
Test der systembruker benyttes (alternativ 2)
Valgfrie organisasjoner fra Tenor kan benyttes som trekkpliktig. Den valgte organisasjonen i Tenor (som representerer en trekkpliktig) må godkjenne at dens fagsystem kan benytte tilgangsressursen/tjenesten «Informasjon om trekkpålegg» på vegne av virksomheten. Det opprettes da en «systembruker» som er koblingen mellom bruker, system, leverandør og API. Dette API-et finnes foreløpig ikke i Felles datakatalog.