Hopp til innhold
Apier

Utvikler-API

Skatteetaten-API (DM-39)

Valider MVA-melding mot Skatteetaten uten å eie virksomhetssertifikatet, Maskinporten-klienten eller tokenvekslingen. Bindende innsending er låst (kun prøveinnsending i dag); Apier brokerer hele kjeden bak én Bearer-nøkkel.

Les dokumentasjonenPrøv sandkassen

Hva er Skatteetaten-API-et (DM-39)?

DM-39 er Skatteetatens tilgang for validering og innsending av MVA-melding (merverdiavgiftsmelding). Apier eksponerer den som en normalisert REST- og MCP-flate: Du sender en strukturert MVA-melding, Apier validerer den mot regelverket, og (når innsending er slått på) sender den inn via Altinn 3-instansen på vegne av virksomheten. Validering og prøveinnsending er i drift i dag; bindende innsending er låst (ikke slått på ennå).

Skatteetatens egne delings-API-er for å lese MVA-registeret ble avslått 2026-06-02, så feltet data.skatteetaten.mva_register er utfaset og alltid null. MVA-registreringsstatus leser du i stedet fra det gratis Tier 1-feltet data.mva_registered. Det DM-39 gir deg er selve MVA-meldingsflyten: validering og innsending.

Hvordan autentiserer jeg mot Skatteetaten via Maskinporten?

Du autentiserer mot Apier med én Bearer-API-nøkkel. Apier holder virksomhetssertifikatet og Maskinporten-klienten, henter et Maskinporten-token med riktige scopes og veksler det inn mot Skatteetaten på serveren. Du genererer aldri en nøkkel, signerer aldri en JWT-client-assertion og ser aldri det rå tokenet.

Hele Maskinporten-seremonien (virksomhetssertifikat, JWK-opplasting, RS256-signert client-assertion, scopetildelinger og nøkkelrotasjon) håndteres på Maskinporten-API-laget. Tokenet logges aldri og returneres aldri til koden din; bare tidsstempel, scope og suksess/feil registreres.

Hvordan får jeg tilgang på vegne av en virksomhet?

Tilgang på vegne av en virksomhet går gjennom en Altinn 3 System User-delegering: Virksomheten delegerer de nødvendige ressursene til Apiers systembruker i Altinn. Når delegeringen er på plass, autoriserer Apier kallene mot Skatteetaten med den delegerte tilgangen. Uten delegering svarer Altinn 403, og Apier returnerer feilen AUTH_NO_DELEGATION, som forklarer hvem som må delegere, hvor og hvorfor.

Delegeringsmodellen og det treleddede oppsettet (Maskinporten + Samarbeidsportalen + Altinn System Register) er beskrevet i guiden Altinn System Users, og System User-flaten har sin egen System User-API-side.

Hvordan kommer jeg i gang?

Start i sandkassen: Hver MVA-flate har et speil under /api/v1/sandbox som svarer med syntetiske testdata, aldri et ekte statlig system, og merker svaret med _meta.is_sandbox: true. Kjør en prøveinnsending mot organisasjonsnummer 999999999, bekreft at meldingen passerer, og bytt deretter til en produksjonsnøkkel med scopet read:actions når du er klar.

  1. Opprett en API-nøkkel og gi den scopet read:actions.
  2. Kjør en prøveinnsending i sandkassen mot org 999999999 og bekreft at meldingen passerer forhåndssjekkene.
  3. Få virksomheten til å delegere i Altinn, og verifiser tilgangen med en handleevnesjekk før innsending.
  4. Send inn med Idempotency-Key når innsending er slått på for kontoen din (i dag låst, kun prøveinnsending); duplikater returnerer det lagrede svaret i stedet for å sende inn på nytt.

Hvordan håndterer jeg feil og avviste innsendinger?

Alle feil følger Apiers Compliance Explainer-format med error_code, en norsk forklaring og konkrete fix_steps, uten at rå Skatteetaten- eller Altinn-interne detaljer lekker ut. Du møter typisk VALIDATION_FAILED (meldingen er feilformatert), SCOPE_INSUFFICIENT (nøkkelen mangler read:actions), AUTH_NO_DELEGATION (virksomheten har ikke delegert i Altinn), GOVERNMENT_VALIDATION_REJECTED (Skatteetaten avviste totaler eller avstemming) og MASKINPORTEN_TOKEN_FAILED (tokenvekslingen feilet). Hver respons bærer en X-Correlation-ID du kan oppgi til support.

  • 400 VALIDATION_FAILED: Meldingen er feilformatert eller mangler påkrevde felter. Rett feltene listet i explanation.details og prøv igjen.
  • 403 SCOPE_INSUFFICIENT: API-nøkkelen mangler scopet read:actions.
  • 403 AUTH_NO_DELEGATION: Virksomheten har ikke delegert tilgang i Altinn; responsen forklarer hvem som må delegere, hvor og hvorfor.
  • 502 GOVERNMENT_VALIDATION_REJECTED: Skatteetaten avviste innholdet etter orkestrering (f.eks. totaler som ikke avstemmer); produksjonsendepunktet returnerer 502 med omslaget upstream, som har samme form som svaret fra etaten.
  • 502 MASKINPORTEN_TOKEN_FAILED: Tokenvekslingen mot Maskinporten feilet; som regel forbigående.

Kodeeksempel

Forskjellen fra et direkte Skatteetaten-kall er at det ikke ligger noe Maskinporten-token i forespørselen, fordi Apier hentet det for deg. Bruk ?dry_run=true for å validere uten å sende inn.

# Prøveinnsending av en MVA-melding. Ingenting sendes inn.
# Bruk en miljøvariabel for nøkkelen, aldri en hardkodet verdi.
curl -X POST \
  -H "Authorization: Bearer $APIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  "https://www.apier.no/api/v1/actions/execute?dry_run=true" \
  -d '{
    "action_type": "mva_melding",
    "org_number": "999999999",
    "period": "2026-03",
    "payload": { "total_revenue_nok": 1250000 }
  }'
# Sandkasse uten autentisering mot syntetisk org 999999999:
# samme responsform som produksjon, ingen ekte innsending.
curl -X POST \
  -H "Content-Type: application/json" \
  "https://www.apier.no/api/v1/sandbox/public/actions/execute?dry_run=true" \
  -d '{ "action_type": "mva_melding", "org_number": "999999999",
        "period": "2026-03", "payload": { "total_revenue_nok": 1250000 } }'

Hvor finner jeg API-referansen?

Den fullstendige API-referansen ligger i OpenAPI 3.1-spesifikasjonen på /openapi.json og i utviklerdokumentasjonen under /docs/api. MVA-innsendingsflyten steg for steg er beskrevet i guiden /docs/guides/mva-filing.

Relaterte utviklersider