Hvordan spør jeg etter plikter mot Skatteetaten via API?

Hva kan jeg sjekke uten en delegering?

Mer enn nok til å designe mot. Det nøkkelløse pliktendepunktet tar en organisasjonsform og returnerer malsettet for den, der hver oppføring bærer sin rettslige henvisning som et felt. Det nøkkelløse fristendepunktet tar et valgfritt år og returnerer den løpende kalenderen, med tidssone, hvilke organisasjonsformer hver oppføring gjelder for, og eventuell helg- eller helligdagsjustering allerede anvendt. Ingen av kallene navngir et selskap, så ingen av dem krever noens tillatelse.

Den kombinasjonen svarer på spørsmålet de fleste prosjekter faktisk starter med. Før du vet hvilke kunder du får, vil du vite hva et norsk aksjeselskap skylder, hvordan et enkeltpersonforetak skiller seg, og hvordan rapporteringsrytmen ser ut gjennom et år. Du kan bygge og teste hele formen på produktet ditt mot de to endepunktene og legge til selskapsspesifikk oppførsel senere.

Det du ikke får uten en nøkkel er noe som helst om en bestemt organisasjon, og det er en bevisst grense framfor en prisgrense. Selskapsdata berører styremedlemmer, signaturrett og innsendingsatferd, og derfor ligger de bak en identifisert kaller selv på gratisnivået. Veiledningen om automatisert regeletterlevelse dekker hvilke fakta som kan utledes av det åpne registeret og hvilke som ikke kan det.

Hvilke Skatteetaten-scopes finnes på en Apier-nøkkel, og hva dekker de?

Ingen, og grunnen er verdt å forstå fordi den sparer deg for en supporthenvendelse. Scopes på en Apier-nøkkel navngir datakilden kallet leser, ikke etaten den resulterende innsendingen til slutt går til. Så det finnes ingen read:skatteetaten å be om, og å be om en gir deg ingenting.

Hold den presiseringen i bakhodet hvis du har lest dokumentasjonen til Digdir, for det er der mesteparten av forvirringen oppstår. Maskinporten har sine egne scopes med etatsnavn, tildelt en registrert klient og presentert på tråden til etaten selv. De er reelle, og de er et annet lag enn scopene på en Apier-nøkkel. Integrerer du direkte, forholder du deg til begge; gjennom en megler tilhører trådscopene megleren og dukker aldri opp i din egen konfigurasjon.

Hva du faktisk trenger avhenger av hvilket endepunkt du kaller. Plikter, frister og selskapskontekst leser registerfakta, så de ligger under read:brreg. Innsendingshistorikk leser Altinn-instanser, så den ligger under read:altinn. Tørrkjøringsflaten bruker read:actions, som er et lese-prefiks på en skrive-formet sti fordi en tørrkjøring ikke gir bivirkninger oppstrøms. Sporingsloggen har sitt eget scope, read:audit, slik at en operatør kan gi selskapsdataoppslag uten samtidig å eksponere den forensiske loggen.

Prefiksene på skrivesiden finnes i vokabularet, men kan ikke tildeles noen nøkkel. Det betyr at en scope-liste er en faktisk oppføring over hvilke kilder en integrasjon berørte framfor en uttalelse om hvor mye den ble stolt på, og det er den egenskapen du vil ha når noen spør hva systemet ditt hadde tilgang til.

Hvordan ser jeg om en innsending allerede er gjort?

Les innsendingshistorikken for organisasjonen framfor å utlede den fra dine egne poster. Databasen din vet hva produktet ditt sendte inn; den vet ikke hva kundens regnskapsfører sendte inn fra et annet sted sist fredag. Historikkendepunktet returnerer det som er registrert på selskapet, sidedelt med limit og offset, og svarkonvolutten bærer friskheten på oppslaget slik at du kan se hvor ferskt svaret er.

Behandle en innsendt periode som en stoppbetingelse før du handler, ikke som et avstemmingssteg i etterkant. En agent som sjekker historikken før den foreslår en innsending, unngår den verste feilmodusen på dette området, som er en dobbel innsending som deretter må rettes gjennom en prosess langt tregere enn den som skapte den. Å kombinere historikkoppslaget med tørrkjøringen gir deg begge halvdeler: om det er gjort, og om det du er i ferd med å sende ville blitt godtatt.

Der en periode faktisk må sendes på nytt, er idempotensnøkkelen sikkerhetsnettet framfor din egen gjentakelseslogikk. En nøkkel gjør at et gjentatt kall spiller av det lagrede svaret i stedet for å kjøre to ganger, og det gjør en tvetydig nettverkstidsavbrudd om fra en beslutning du må ta til et kall du bare kan gjenta. Bygg det inn før du trenger det, for i det øyeblikket du trenger det, er det det siste du vil resonnere om.

Gjør det første kallet

Det første kallet trenger ingenting og returnerer hva et enkeltpersonforetak må sende inn. Det andre er det selskapsavgrensede historikkoppslaget, som krever en nøkkel og kundens delegering.

# Nøkkelløst: hva et norsk enkeltpersonforetak må sende inn.
curl -s "https://www.apier.no/api/v1/public/obligations?entity_type=ENK"

// Er perioden allerede sendt inn? Les historikken.
const res = await fetch(
  "https://www.apier.no/api/v1/company/999999999/filing-history?limit=20",
  { headers: { Authorization: `Bearer ${process.env.APIER_API_KEY}` } },
);

const { data, _meta } = await res.json();
console.log(data.filings, _meta.data_freshness);

Ofte stilte spørsmål

Finnes det et Skatteetaten-scope jeg bør be om på Apier-nøkkelen min?

Ikke på en Apier-nøkkel, og det overrasker folk. Scopes på en Apier-nøkkel navngir datakilden framfor etaten en innsending til slutt havner hos. Plikter og frister nås med read:brreg fordi inndataene er registerfakta, innsendingshistorikk bruker read:altinn fordi det er der instansene ligger, og tørrkjøringsvalidering bruker read:actions. Det finnes ingen read:skatteetaten å be om. Maskinporten-scopes med etatsnavn er et eget lag som bare en direkte integrasjon forholder seg til.

Hva kan jeg spørre om helt uten delegering?

Pliktmalen for en organisasjonsform, og den løpende fristkalenderen. Begge er nøkkelløse: ingen nøkkel, ingen delegering, ingen selskaper navngitt. Det dekker spørsmålet de fleste integrasjoner faktisk starter med, som er hva et norsk aksjeselskap eller enkeltpersonforetak må sende inn og omtrent når.

Hva legger en delegering til?

Tilgang til det selskapsinterne nivået av fakta, som utvider hvilke regler evalueringen kan nå. Hvert selskapsavgrenset svar bærer et data_tier-felt: tier_1 betyr bare åpne registerfakta, tier_2 betyr at kalleren hadde en aktiv delegering. Et tier_1-svar er fullstendig over sine smalere inndata framfor avkortet, og svaret sier hvilke regler det ikke kunne nå.

Hvordan sjekker jeg om en innsending allerede er gjort?

Les innsendingshistorikken for organisasjonen. Den returnerer innsendingene som er registrert på selskapet, sidedelt, med datafriskheten for oppslaget på svarkonvolutten. Fordi den leser Altinn-instanser krever den read:altinn, og som alt selskapsavgrenset krever den selskapets delegering før den kan svare.

Kan jeg sende inn til Skatteetaten gjennom dette API-et?

Validering ja, bindende innsending nei. Tørrkjøringsflaten sjekker en reell nyttelast mot det reelle regelsettet og rapporterer hver sjekk. Live innsending er styrt bak godkjenninger som ikke har landet, og én handlingstype er ikke koblet for live innsending i det hele tatt og svarer med et uttrykkelig avslag framfor en falsk suksess.