Slik bruker du Altinns REST-API

Hva er Altinns REST-API, og hva kan man bruke det til?

📸: Ole Petter Baugerød Stokke
📸: Ole Petter Baugerød Stokke Vis mer

Hva er Altinns REST API, og hva kan man bruke det til? Kort fortalt kan du oppdatere pålogget brukers meldingsboks. Du kan legge til, signere, slette og liste opp dokumenter.

For å kunne legge dokumenter i meldingsboksen til en bruker/organisasjon som en bruker kan representere i Altinn, må du først registrere applikasjonen din. Når det er gjort får du en offentlig API-nøkkel tilbake.

Dette gjør du ved å fylle ut følgende to skjemaer, og sende de til api@altinn.no.

Når du har mottatt API-nøkkelen er du klar til å autentisere deg mot ID-porten, slik at du kan gjøre kall mot REST API-et. Det første du må gjøre er å få fatt i en cookie; ASPXAUTH. Denne får du tak i ved å gå til følgende url:

https://www.altinn.no/Pages/ExternalAuthentication/Redirect.aspx?returnUrl=:returnUrl

I test bytter du ut www.altinn.no med tt02.altinn.no

Hvis du allerede har brukt ID-porten til autentisering, og derfor har en pålogget bruker, kan du legge «&userToken» på URL-en ovenfor. Da slipper brukeren å logge inn på nytt for å få fatt i .ASPXAUTH. userToken settes til SHA256 av fødselsnr til pålogget bruker:

https://www.altinn.no/Pages/ExternalAuthentication/Redirect.aspx?returnUrl=:returnUrl&userToken=<SHA256 av fødselsnr>

returnUrl settes til URL-en på din webside (må være den du har mottatt API-nøkkel til, da den er lagt til i Altinns whitelist siden det brukes CORS ved kryssdomene forespørsler) som du ønsker å returnere til etter å ha fisket opp cookien.

Husk på at siden du nå navigerer vekk fra din egen applikasjon, for deretter å returnere vil du miste utfyllt informason og state i applikasjonen før autentisering. Med tanke på brukervennlighet er ikke dette helt ideellt for å si det mildt, men det kan håndteres slik at det blir minst mulig smertefullt for brukeren. Du kan feks lagre i local storage eller lagre utkastet ditt (hvis applikasjonen din har denne type funksjonalitet) før du setter window.location.href til autentiserings URL-en, og passe på at returnUrl har nødvendige id’er og parametere for å få gjennopprettet.

I påfølgende kall mot REST API-et settes .ASPXAUTH på requesten ved å sette xhr.withCredentials: true (se Ajax-eksempel lenger nede).

Du er nå klar til å kommunisere med Altinns meldingsboks fra web-applikasjonen din.

Vær klar over at alle kall mot Altinn vil vises som 2 requests i nettverksloggen i for eksempel Google Chromes developer tools. Den første har request metode OPTIONS. Dette er en preflight, som gjøres for å sjekke at man har gyldig cookie. Den lages automatisk ved alle forespørsler som gjøres fordi Altinn bruker CORS ved kommunikasjon på tvers av domener.

Opprett et skjema i meldingsboksen

https://www.altinn.no/api/:userId/messages

Hvis du ønsker å sende inn et tomt eller delvis utfyllt skjema, legg på:

?complete=false.

Om skjemaet ikke skal kunne endres, sett complete til true.

  • Meldingsboks til pålogget bruker: userId = my
  • Meldingsboksen til organsisasjon pålogget bruker kan representere: userId = organisasjonsnr

I payloaden til requesten (call.data i eksemplet nedenfor) legger man inn en xml som spesifiserer skjemaet som kan fylles ut, samt liste over eventuelle vedlegg.

Praktisk eksempel

Hos Plan- og bygningsetaten i Oslo bruker vi REST API-et i den digitale byggesøknadssprosessen.

«Oslo kommune var første kommune til å ta i bruk den nye digitale motorveien for byggesøknader på Altinn via Fellestjenester Bygg (…) Siden januar 2018 har Oslo kommune tatt imot digitale rammesøknader. Gjennomføringsplanen oppdateres gjennom digital signatur av ansvarsretter via Fellestjenester BYGG og bruk av ID-porten. »
- Bygg21

Ansvarsretter legges til signering i meldingsboksen, til det firmaet som ansvarlig søker ønsker at skal ta ansvar for en del av et byggeprosjekt — altså ikke pålogget brukers meldingsboks. I løsningen deres er det ansvarlig søker for et byggeprosjekt som er logget på.

For å få lagt skjemaer til signering i meldingsboksen til et annet firma, benytter vi isteden Direktorat for byggkvalitet (DIBK)s distribusjonstjeneste for Altinn  —  Ansvarsrett. Da skjer all magien i XML-en som legges i payloaden til requesten (call.data i eksemplet nedenfor). Vi setter i dette tilfellet userId til pålogget brukers organisasjonsnr, og sender inn en melding som spesifiserer at vi ønsker å benytte oss av DIBKs tjenester. Denne meldingen plukkes senere opp av DIBK, som oppretter en Ansvarsrett til signering i meldingsboksen til firmaet spesifisert i XML-en.

I vår løsning har vi brukt Ajax for å utføre requestene:

image: Slik bruker du Altinns REST-API

Dokumentasjon

Dokumentasjonen på altinn.github.io er ikke alltid oppdatert, så jeg anbefaler å bruke https://www.altinn.no/api/help/

image: Slik bruker du Altinns REST-API

Gotcha

Denne sier at Content-Type er hal+json. Det feiler, siden dette endepunktet ønsker seg octet-stream, noe man fort ser om man sjekker dokumentasjonen her.