Kom i gang med API

Her finnes informasjon om hvordan du kommer i gang med å integrere ditt system med data.altinn.no (DAN).

Innledning

Integrasjon mot data.altinn.no krever ingen spesiell programvare eller infrastruktur, men de fleste API-ene krever autentisering med et token fra Maskinporten.

Videre kreves en API-nøkkel (“subscription key”) for den eller de tjenestene som skal benyttes. Disse kan man be om gjennom utviklerportalen på data.altinn.no.

Kom i gang - overordnede steg

For å ta bruk data.altinn.no må du:

1. Identifisere hvilke datasett du ønsker å bruke, og dermed hvilken tjeneste som er aktuell for deg.
2. Registrere deg på utviklerportalen (du kan også velge preproduksjonsmiljøet hvor du kan bruke syntetiske data) og få tildelt en API-nøkkel (“subscription key”).
3. Skaffe Maskinporten-tilgang: en integrasjon i Maskinporten og scopet for tjenesten du skal bruke. Scopet tildeler vi; be om det for test og produksjon hver for seg.
4. Se listen over datasett og ta utgangspunkt i eksemplene for å lage din integrasjon. Hvis du benytter .NET 8 eller nyere anbefaler vi bruk av DAN SDK

Protokoll og formater

REST-APIet bygger på HTTP, og tilkoblinger sikres ved hjelp av TLS 1.2/1.3 kryptering. Dataene formateres i JSON, og pakkes inn i en konvolutt (kan utelates) som er lik på tvers av alle datasett. Noen datasett er enkle nøkkel/verdi-par, mens andre har rike strukturer som er beskrevet av et eget JSON schema.

Versjonering

API-et har et versjonsprefiks som en del av URL-en. Gjeldende versjon er “v1”, og eventuelt nye versjoner vil få “v2”, “v3” etc. data.altinn.no vil så langt det lar seg gjøre unngå å introdusere nye versjoner, men for å sikre bakoverkompatibilitet med alle konsumenter vil nødvendig forbedring og utvidelse av funksjonalitet kunne medføre at en ny versjon må introduseres.

Nye uavhengige actions og modeller vil kunne bli lagt til en eksisterende versjon, og tillegg av nye felter vil kunne bli gjort på eksisterende actions og modeller i en gitt versjon.

Gamle versjoner vil bli støttet i minst 12 måneder etter at en ny versjon tilgjengeliggjøres, og alle registrerte brukere vil bli underrettet i god tid før utfasing av gamle versjoner finner sted for å sikre at alle får migrert til ny versjon.

• Gå til data.altinn.no API Portal
• OpenAPI 3.0 (swagger) for v1

Datasett

Feltene (navn, antall og verdityper) i datasett er å regne som ikke-muterbare, men datasett vil kunne endre hvilke autorisasjonsregler som ligger til grunn. Ved behov for nye felter i et gitt datasett, vil et nytt uavhengig datasett introduseres.

Gamle datasett vil kunne utfases i takt med tilgjengeligheten av dataene i de underliggende registrene. Disse er eksterne for data.altinn.no, og følgelig utenfor vår kontroll - men så langt det lar seg gjøre vil datasett på samme måte som versjoner i API-et bli støttet i minst 12 måneder før disse fases ut.

• Vis liste over alle datasett

Feil- og statuskoder

Feil- og statuskoder som beskrevet i metadata-API-et vil ikke kunne endres eller fjernes uten at ny versjon av API-et introduseres, men nye feil- og statuskoder vil kunne bli lagt til i en eksisterende versjon.

• Vis liste over alle statuskoder (JSON)
• Vis liste over alle feilkoder (JSON)

Autentisering og autorisasjon

API-et autentiserer deg med et token fra Maskinporten. Hver tjeneste har sitt eget scope; scopene til data.altinn.no starter med altinn:dataaltinnno/ (noen med dan:), og hvilket scope et datasett krever står på datasettet i datasettoversikten. Tokenet må være utstedt til den virksomheten som spør (requestor).

Autorisasjon til selve API-et skjer med en API-nøkkel (subscription key) for den eller de tjenestene du skal bruke. Den ber du om i utviklerportalen etter å ha registrert deg.

Slik får du Maskinporten-tilgang

Du trenger ikke virksomhetssertifikat, og for testmiljøet holder det med den enkleste rettigheten i Altinn. Stegene er de samme for alle tjenestene på data.altinn.no; bare scopet varierer.

1. Bruker i Samarbeidsportalen. Registrer deg på samarbeid.digdir.no med jobb-e-posten din; du knyttes til virksomheten gjennom e-postdomenet. Virksomheten må ha signert Digdirs bruksvilkår (gjøres én gang, av en som kan forplikte virksomheten).
2. Rettighet i Altinn. For å opprette og administrere integrasjoner trenger du rettigheten «Selvbetjening av klienter i ID-porten/Maskinporten» (test og produksjon) eller «Selvbetjening for testing» (kun test). Den delegeres av virksomhetens hovedadministrator i Altinn.
3. Opprett integrasjonen. I Samarbeidsportalen: Virksomhetens tjenester → Administrasjon av tjenester → Integrasjoner → Ny integrasjon, av typen Maskinporten. Test og produksjon er adskilte miljøer; start i test. Du trenger ikke virksomhetssertifikat: et eget asymmetrisk nøkkelpar er nok (den offentlige nøkkelen legges inn som JWK). Har dere allerede virksomhetssertifikat, kan det brukes i stedet. Se Selvbetjening via Samarbeidsportalen.
4. Få tildelt scope. Send organisasjonsnummer, miljø (test eller produksjon) og scopet altinn:dataaltinnno/<tjeneste> til dan@altinn.no. Vi tildeler scopet til virksomheten i Maskinporten; deretter legger du det på integrasjonen din.
5. Hent token og kall API-et. Signer et JWT-grant med nøkkelen og send det til Maskinportens token-endepunkt (test, produksjon). Bruk access_token som Authorization: Bearer sammen med API-nøkkelen (Ocp-apim-subscription-key) fra utviklerportalen i samme miljø: test.data.altinn.no for test, data.altinn.no for produksjon. Nøklene er ikke de samme i de to miljøene. Framgangsmåten steg for steg står i Digdirs veiledning for API-konsumenter.

Flere måter å integrere mot Maskinporten på, inkludert delegering til en leverandør, er beskrevet på Ta i bruk Maskinporten.

Miljøer og base-URL-er

Det er ulike base-URL-er som skal benyttes avhengig av miljø.

Miljø	API base-URL	Utviklerportal
Prod	https://api.data.altinn.no	https://data.altinn.no
Test	https://test-api.data.altinn.no	https://test.data.altinn.no

For å finne endepunkt-URL-ene til de ulike operasjonene som støttes, som inkluderer versjonen av API-et som skal benyttes, se utviklerportalen.

Lage ny bruker

Alle brukere av data.altinn.no må registrere en profil i utviklerportalen i produksjon eller i testmiljøet hvor man kan registrere applikasjoner og få utdelt API-nøkler som må oppgis i alle requests til data.altinn.no. Kontaktopplysningene du oppgir vil bli benyttet for å sende informasjon om planlagte endringer og nedetid samt annen driftsrelatert informasjon. På profilsiden vil man også kunne hente ut detaljert bruksstatistikk.

Hvis du vil opprette en ny bruker, gå til registreringssiden. Etter å ha fylt inn kontodetaljer, følg instruksjonene i eposten du vil motta. Du vil bli navigert til innloggingssiden når du har verifisert eposten.

Hvis du allerede har en eksisterende bruker, gå til innloggingssiden

Skaffe API-nøkkel

• Logg inn
• Gå til utviklerportalen
• Naviger til produkter og velg produktet du ønsker å benytte
• Fyll inn navnet du ønsker på ditt abonnement og trykk “Subscribe”
• Når abonnementet ditt er klart, naviger til profilen din
• Trykk på “Show” for å vise abonnement-nøkkelen din

Hvordan innhente opplysninger

Datasett kan hentes på to forskjellige måter; direkte eller gjennom en autorisasjonsforespørsel.

De fleste datasett kan hentes direkte med ett kall til data.altinn.no-API-et. Datasett som krever at det innhentes samtykke, eller er på annen måte konfigurert som asynkront (fordi uthentingen av dataene fra kilden er en asynkron prosess) kreves at man først sender en autorisasjonsforespørsel til REST-API-et, som inneholder informasjon om hvilken virksomhet man spør om og hvilke datasett en ønsker å hente. Hvis forespørselen blir autorisert, vil man som svar få en akkrediterings-ID som representerer forespørselen. For datasett som er åpne eller hjemmelsbaserte, vil man umiddelbart kunne høste de datasettene med kall hvor denne akkrediterings-IDen oppgis. For datasett som krever samtykkesvar, vil man kunne sjekke status på dette (om svar er avgitt eller ikke), og så fort dette foreligger vil du kunne høste datasettet på samme måte (så lenge samtykket er gyldig og ikke trukket tilbake).

• Vis liste over alle datasett
• Vis liste over alle datasett (JSON)
• Vis oversikt over metadata-tjenester

Konvolutt og filtrering/transformering

Datasett som hentes gjennom data.altinn.no blir plassert inn i en standard konvolutt. Konvolutten kan fjernes ved å oppgi query-parameteret envelope=false i alle spørringer som returnerer datasett.

Ved bruk av envelope=false, kan man også oppgi et JMESPath-uttrykk, som lar en ytterligere filtrere og transformere dataene som returneres fra data.altinn.no. Dette gjøres med å oppgi query-parameteret query=<jmespath> hvor <jmespath> er et gyldig uttrykk.

JMESPath-filtrering kan også brukes på andre oppslagsendepunkter som ikke returnerer datasett, f.eks. liste over pågående forespørsler (accreditations). Se teknisk beskrivelse av API for mer informasjon om hvilke endepunkter som støtter bruk av query.

Teknisk beskrivelse av API

På portalen finner du oppdatert teknisk dokumentasjon om actions, modeller og feilsituasjoner. Du kan også hente ned Swagger/OpenAPI definisjoner.

Det er to miljøer som er tilgjengelige utenfra: prod og test. Begge miljøene har et metadata-API, som ikke krever autentisering eller autorisasjon for bruk.

• Oversikt over API-er