Hopp til innhold
Apier

Utvikler-API

Innsendingshistorikk-API

Én forespørsel gir deg en virksomhets innsendinger i Altinn 3, koblet til Apiers signerte revisjonslogg der en samsvarende oppføring finnes, så du kan avstemme hva som faktisk ble sendt inn, av hvem og når.

Les dokumentasjonenPrøv sandkassen

Hva er Innsendingshistorikk-API-et?

Endepunktet GET /api/v1/company/{org}/filing-history returnerer en virksomhets Altinn 3-innsendinger (instanser), der hver innsending er paret med oppføringen i Apiers revisjonslogg dersom innsendingen gikk gjennom Apier. Et regnskapsbyrå eller en revisor kan dermed avstemme hvilke innsendinger som ble sendt via Apier mot hvilke som ble levert direkte i Altinn.

Hver innsending er normalisert til Apiers eget format: instance_id, form_code, title, service_owner, submitted_at og status (submitted / processing / completed / rejected). Avstemmingsverdien filed_via_apier er true når det finnes en oppføring i revisjonsloggen, og apier_record bærer da de forensiske pekerne (audit_log_id, correlation_id), aldri selve innsendingsinnholdet.

Hvordan autentiserer jeg meg mot endepunktet?

Dette er et Kategori B-endepunkt: Du autentiserer med en Bearer-API-nøkkel som har scopet read:altinn. Apier holder virksomhetssertifikatet og veksler Maskinporten-tokenet på serveren, så koden din sender kun Authorization-headeren med API-nøkkelen.

Selve tokenvekslingen mot Maskinporten (sertifikat, signert client-assertion og nøkkelrotasjon) håndteres på Maskinporten-API-laget, så du aldri ser et rått token.

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

Tilgang til en virksomhets innsendinger krever en Altinn 3 System User-delegering fra virksomheten til Apiers systembruker. I produksjon er det delegeringstokenet selv som er autoriteten. Mangler delegeringen, svarer Altinn 403 og Apier returnerer feilen AUTH_NO_DELEGATION. I simulert modus (mock) erstatter syntetiske testdata en innvilget delegering.

Oppsettet av en System User-delegering er beskrevet i guiden Altinn System Users.

Hvordan kommer jeg i gang?

Prøv det uten autentisering i sandkassen: GET /api/v1/sandbox/public/company/999999999/filing-history svarer med deterministiske syntetiske innsendinger og merker svaret med _meta.is_sandbox: true. Bla med limit (1–100, standard 20) og offset (≥0); has_more og next_offset i pagination-omslaget forteller når det finnes flere sider.

  1. Kall sandkassespeilet for org 999999999 og bli kjent med PairedFiling-formen og pagination-omslaget.
  2. Opprett en produksjonsnøkkel med scopet read:altinn.
  3. Få virksomheten til å delegere til Apiers systembruker i Altinn.
  4. Bla gjennom resultatene med limit + offset til has_more er false.

Hvordan håndterer jeg feil og manglende tilgang?

Feil følger Compliance Explainer-formatet med error_code, norsk forklaring og fix_steps. Du møter typisk VALIDATION_FAILED (organisasjonsnummeret er ikke 9 siffer, eller en spørreparameter er ugyldig eller gjentatt), SCOPE_INSUFFICIENT (nøkkelen mangler read:altinn), AUTH_NO_DELEGATION (virksomheten har ikke delegert) og FILING_HISTORY_FAILED (en forbigående intern feil). Hver respons bærer en X-Correlation-ID for support.

  • 400 VALIDATION_FAILED: Organisasjonsnummeret er ikke nøyaktig 9 siffer, eller en spørreparameter er ugyldig eller sendt flere ganger.
  • 403 SCOPE_INSUFFICIENT: API-nøkkelen mangler scopet read:altinn.
  • 403 AUTH_NO_DELEGATION: Virksomheten har ikke delegert tilgang i Altinn; svaret forklarer hvem som må delegere, hvor og hvorfor.
  • 500 FILING_HISTORY_FAILED: En uventet, som regel forbigående, intern feil. Prøv igjen, og oppgi X-Correlation-ID til support om den vedvarer.

Kodeeksempel

Forespørselen er en vanlig GET med paginering via offset. Bruk sandkassespeilet for å utforske formen uten en nøkkel.

# Hent innsendingshistorikk. Bearer-nøkkelen leses fra en miljøvariabel.
curl -H "Authorization: Bearer $APIER_API_KEY" \
  "https://www.apier.no/api/v1/company/999999999/filing-history?limit=20&offset=0"
# Sandkasse uten autentisering mot syntetisk org 999999999.
curl "https://www.apier.no/api/v1/sandbox/public/company/999999999/filing-history"

Hvor finner jeg API-referansen?

Den fullstendige API-referansen (inkludert PairedFiling-responsformen og pagination-omslaget) ligger i OpenAPI 3.1-spesifikasjonen på /openapi.json og i utviklerdokumentasjonen under /docs/api.

Relaterte utviklersider