Skip to content
Apier

Utvikler-API

Skatteetaten-API (DM-39)

Valider og send inn MVA-melding mot Skatteetaten — uten å eie virksomhetssertifikatet, Maskinporten-klienten eller token-vekslingen. 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 sender den inn via Altinn 3-instansen på vegne av virksomheten. Validering og dry-run er live i dag; bindende innsending er i beta.

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 frie Tier 1-feltet data.mva_registered. Det DM-39 gir deg er selve MVA-melding-flyten: 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 server-side — 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, scope-grants 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 en AUTH_NO_DELEGATION-handover som forklarer hvem som må delegere, hvor og hvorfor.

Delegeringsmodellen og tre-leddet oppsett (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 fixtures, aldri et ekte statlig system, og merker svaret med _meta.is_sandbox: true. Kjør en dry-run-validering mot organisasjonsnummer 999999999, bekreft at meldingen passerer, og bytt deretter til en produksjonsnøkkel med read:actions-scope når du er klar.

  1. Provisjonér en API-nøkkel og gi den read:actions-scope.
  2. Kjør en dry-run-validering 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 — 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 — ingen 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 (token-veksling 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 read:actions-scope.
  • 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 et regjerings-formet upstream-omslag.
  • 502 MASKINPORTEN_TOKEN_FAILED — token-vekslingen mot Maskinporten feilet; som regel forbigående.

Kodeeksempel

Forskjellen fra et direkte Skatteetaten-kall er hva som mangler: ingen Maskinporten-token i forespørselen, fordi Apier hentet den for deg. Bruk ?dry_run=true for å validere uten å sende inn.

# Dry-run validering av en MVA-melding — ingen innsending skjer.
# Bruk en miljøvariabel for nøkkelen; aldri en literal i koden.
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 }
  }'
# Null-auth sandkasse 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