Altinn 3, Maskinporten og systembruker — slik fungerer maskinell innsending

Hva integrasjonen gjør

Macct sender inn til det offentlige på vegne av kunden, uten at kunden deler passord eller logger inn manuelt. Følgende går maskinelt:

• Skattekort til arbeidsgiver — henter trekkprosent/tabellkort fra Skatteetaten.
• MVA-melding — leveres via en Altinn 3-app hos Skatteetaten.
• Næringsspesifikasjon + skattemelding (AS) — RF-1167-grunnlaget og selskapets skattemelding.
• Årsregnskap — RR0002 til Regnskapsregisteret i Brønnøysund via Altinn.
• A-melding og aksjonærregisteroppgave — til Skatteetaten.

Tre byggeklosser gjør dette mulig: Maskinporten (maskin-til-maskin- autentisering fra Digdir), en systembruker (kundens fullmakt til fagsystemet, godkjent med BankID i Altinn), og Altinn 3 / Skatteetatens API-er (selve innsendingen). Brønnøysundregistrene brukes til validering av organisasjonsnummer, rolle og status ved registrering.

Digdir / Maskinporten: klient, JWT-grant og scopes

Maskinporten er Digdirs OAuth2-tjeneste for maskin-til-maskin (M2M). Fagsystemet har én klient per miljø (test og produksjon hver for seg), autentisert med et virksomhetssertifikat / en nøkkel registrert i Samarbeidsportalen. Tokens hentes med grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer: et signert JWT-assertion byttes mot et access token for de scopene klienten har fått tildelt.

POST https://maskinporten.no/token
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&
assertion=<signert JWT: iss=clientId, aud=maskinporten, scope=...>

Scopene vi bruker

Systembruker: System Register, request og BankID-godkjenning

En systembruker er kundens fullmakt til fagsystemet i Altinn. Flyten er tre steg:

1. Registrer systemet (én gang per miljø)

Fagsystemet registreres i Altinns System Register med en systID på formen <leverandør-orgnr>_macct, klient-ID-en(e) fra Maskinporten, og hvilke rettigheter og tilgangspakker systemet forvalter.

POST {altinn}/authentication/api/v1/systemregister/vendor
{ "id": "<orgnr>_macct", "vendor": { "ID": "0192:<orgnr>" },
  "clientId": ["..."], "rights": [...], "accessPackages": [...],
  "allowedRedirectUrls": ["https://macct.no/altinn/callback"] }

2. Opprett en systembruker-forespørsel per kunde

POST {altinn}/authentication/api/v1/systemuser/request/vendor
{ "systemId": "<orgnr>_macct",
  "partyOrgNo": "<kundens orgnr>",
  "externalRef": "selskap-123",
  "rights": [ { "resource": [ { "id": "urn:altinn:resource", "value": "app_skd_formueinntekt-skattemelding-v2" } ] }, ... ],
  "accessPackages": [ { "urn": "urn:altinn:accesspackage:merverdiavgift" }, ... ],
  "redirectUrl": "https://macct.no/altinn/callback" }
→ svar inneholder en confirmUrl (am.ui.altinn.no/.../systemuser/request?id=...)

3. Kunden godkjenner med BankID

Kunden åpner confirmUrl og godkjenner i Altinn. Etter godkjenning slås den faktiske systembrukeren opp («bysystem»-listen), og en systemUserId lagres på kunden. Den brukes ikke direkte i tokenet — selve fullmakten bæres av externalRef + kundens orgnr (under).

Tilgangspakker vs. rettigheter (rights)

Altinn 3 skiller mellom to fullmaktstyper, og innsending krever ofte begge:

• Rettigheter (rights) — peker på en konkret ressurs/app, f.eks. app_skd_formueinntekt-skattemelding-v2 (skattemelding), app_brg_aarsregnskap-vanlig-202406 (årsregnskap), ske-innrapportering-amelding (a-melding).
• Tilgangspakker (access packages) — rollebaserte «bunter» som Altinns policy-motor (PDP) krever for å instansiere enkelte apper. Vi bruker urn:altinn:accesspackage:regnskap-okonomi-rapport og urn:altinn:accesspackage:merverdiavgift.

Tokens: Maskinporten-token og Altinn-token-utveksling

For å handle på vegne av en annen virksomhet enn klient-eieren binder vi tokenet til systembrukeren via authorization_details (RAR-typen urn:altinn:systemuser):

authorization_details = [{
  "type": "urn:altinn:systemuser",
  "systemuser_org": { "authority": "iso6523-actorid-upis", "ID": "0192:<kundens orgnr>" },
  "externalRef": "selskap-123"
}]

Maskinporten-tokenet byttes deretter mot et Altinn-token for å nå Storage/App-API-ene:

GET {altinn}/authentication/api/v1/exchange/maskinporten
Authorization: Bearer <maskinporten-token med altinn:instances.write>
→ Altinn-JWT brukt mot app-instanser

Per tjeneste: API-kall og parametere

Skattekort til arbeidsgiver

Direkte mot Skatteetatens «Skattekort for arbeidsgivere» (v3, forskudd-API) med et systembruker-bundet Maskinporten-token og scope skatteetaten:skattekorttilarbeidsgiver. Vert: api.skatteetaten.no (prod) / api-test.sits.no (test). Parametere: inntektsår, arbeidsgivers orgnr og den ansattes fødselsnummer. Svar: trekktype (tabell/prosent), tabellnummer og trekkprosent — som skrives på den ansatte og brukes i lønnskjøringen.

MVA-melding

Leveres via Altinn 3-appen mva-melding-innsending-v1 (instances.write + systembruker), ikke det avviklede direkte-API-et. To XML-dokumenter bygges: selve meldingen (mvamelding, namespace skattemeldingformerverdiavgift) og en innsendings-wrapper (mvameldinginnsending). Flyt:

1) POST .../instances              (opprett instans, instanceOwner = kundens orgnr)
2) PUT/POST data: mvamelding + wrapper  (erstatt auto-opprettet element)
3) PUT .../process/next            (data → confirmation → feedback)
→ kvittering: instanceOwnerPartyId/instanceGuid

Meldingen inneholder bl.a. skattleggingsperiode (to-måneders termin + år), fastsattMerverdiavgift, mvaSpesifikasjonslinje[], meldingskategori=alminnelig og skattepliktig>organisasjonsnummer. Valgfri forhåndsvalidering finnes på /api/mva/grensesnittstoette/mva-melding/valider.

Årsregnskap (RR0002)

Til Regnskapsregisteret via Altinn-appen app_brg_aarsregnskap-vanlig-202406. To dataTypes lastes opp: Hovedskjema (RR0002H_M — metadata) og Underskjema (RR0002U_M — resultat/balanse med detaljlinjer). Prosessen føres til PROSESS_FULLFORT, som er kvitteringen på at innsendingen er gjennomført.

Næringsspesifikasjon og skattemelding (AS)

Næringsspesifikasjonen (RF-1167-grunnlaget) bygges og godkjennes først; deretter genereres selskapets skattemelding (v2-format, skattemeldingForFormuesOgInntektsskatt, pakket i skattemeldingOgNaeringsspesifikasjonRequest med base64-kodede deldokumenter) og leveres via app_skd_formueinntekt-skattemelding-v2. Innsending er aldri automatisk: status-løpet er DRAFT → READY_FOR_REVIEW → APPROVED → SUBMITTED med SHA-256- integritetssjekk i hvert steg og en obligatorisk preflight-kontroll (krever bl.a. fullført årsavslutning og eksplisitt godkjenning) før noe sendes.

Fallgruver verdt å unngå

Punktene under er de som typisk koster mest tid. Alle er håndtert i Macct.

Hva en Macct-kunde må gjøre

For at Macct skal kunne sende inn MVA-melding, årsregnskap, skattemelding m.m. på vegne av selskapet ditt, trenger vi én engangsgodkjenning fra deg:

1. Du får en lenke til Altinn (am.ui.altinn.no) fra Macct.
2. Du logger inn med BankID og godkjenner systembruker-forespørselen — du må ha en rolle på selskapet (typisk daglig leder eller styreleder, eller en delegert rolle) i Brønnøysund/Altinn.
3. Godkjenningen gir Macct en systembruker med nøyaktig de tilgangspakkene og rettighetene som står i forespørselen — verken mer eller mindre.

Du deler aldri passord, BankID-koder eller API-nøkler. Fullmakten er avgrenset, sporbar, og du kan når som helst trekke den tilbake i Altinn under Tilgangsstyring → Systemtilgang. Og selv med fullmakt på plass sender Macct aldri noe inn uten at det er utløst og godkjent — innsending krever alltid et eksplisitt menneskelig «send».