Bruk av Digipost sitt OAuth-baserte REST-API

For å komme igang med integrasjonen med Digipost sitt REST-API er det noen enkle steg du bør følge. Når du har gjort dette initielle oppsettet én gang, har du i praksis fri tilgang til å bruke hele vårt API. Denne guiden hjelper deg igang med førstegangsoppsettet.

Steg 1. Sett opp løsningen din hos Digipost

For at du skal kunne bruke vårt API, må du opprette en OAuth-applikasjon hos oss. Dette er en enkel prosess der du forteller oss litt om hva du tenker å bruke API-et til. Her er det viktig at du har tenkt gjennom bruksscenariet, slik at du kan fortelle oss hvilke tilganger du trenger i API-et. Vi trenger følgende informasjon:

1. Informasjon om deg og din løsning

Gi oss følgende opplysninger:

• Din Digipost-adresse (denne finner du under innstillinger / personlig)
• Navn på applikasjonen
• Kort beskrivelse av applikasjonen
• Navn på produsent
• Kontaktperson hos produsent (ditt navn)
• Produsentens telefonnummer og epostadresse
• URL til mer informasjon om applikasjonen
• Logo for applikasjonen (kvadratisk PNG)
• Redirect URI – URI-en Digipost omdirigerer til når en bruker har godkjent et token. Dette må være en URI med HTTPS, da HTTPS er en forutsetning for OAuth 2. Dersom det er en mobil applikasjon, kan man også bruke custom URL schemes.

2. Ønskede tilganger

Vi har laget et granulært tilgangssystem som gjør at du får tilgang til akkurat den informasjonen du trenger, men ikke mer. Dette gjør at dine brukere kan være trygge på akkurat hvilken informasjon de deler med din app- eller webløsning.

Ved forespørsel om OAuth-tilgang trenger vi informasjon om hvilke tilganger du trenger. Dersom du ikke er sikker, holder det å fortelle oss hva du ønsker å oppnå, så kan vi hjelpe deg å definere tilgangsnivået.

Søknad om tilgang sendes pr. epost til support@digipost.no. Inkluder informasjonen over, så går prosessen kjapt og enkelt.

Steg 2. Gjør autentisering via OAuth

Så fort du har fått tilbakemelding fra oss om at din applikasjon er opprettet, kan du ta API-et i bruk. Det første du må gjøre, er å implementere OAuth-pålogging. Dette er en standardisert løsning som du sannsynligvis vil kunne bruke standardiserte biblioteker for. Resultatet vil være at brukeren har autentisert seg, og du sitter med et access-token du kan bruke for å gjøre forespørsler mot API-et.

Les mer om OAuth-integrasjonen

Steg 3. Hent rot-ressurs og finn lenker til det du ønsker å hente

Digipost sitt REST-API er laget for å være selvdokumenterende og enkelt å bruke. For å komme igang bør du starte med å gjøre en GET-forespørsel mot vår rotressurs.

Request

Gjør følgende GET-forespørsel mot API-et:

GET https://www.digipost.no/post/api HTTP/1.1

Accept: application/vnd.digipost-v2+json
Authorization: Bearer ditt-token-her

Legg merke til at vi her spør om Digipost sin medietype for å indikere at vi ønsker JSON og for å si at vi bruker versjon 2 av API-et. Vi inkluderer også access-tokenet i Authorization-headeren, ellers får du kun tilbake en feilmelding om at du ikke er innlogget.

Response

Dersom alt er gjort korrekt med OAuto-påloggingen, vil vi da få følgende svar tilbake (noe forkortet):

{
   "csrfToken":"EMCZ8Y5J13TS8M9088JR0BBFHUOZMRQP",
   "authenticationlevel":2,
   "primaryAccount":{
      "personalidentificationnumberObfuscated":"181185*****",
      "fullName":"Ola Nordmann",
      "firstName":"Ola",
      "middleName":"",
      "lastName":"Nordmann",
      "email":[
         "ola.nordmann@example.com"
      ],
      "phonenumber":"00000000",
      "digipostaddress":"ola.nordmann#1234",
      "address":[
         {
            "street":"Testgate",
            "city":"Oslo",
            "house-number":"16",
            "additional-addressline":"",
            "zip-code":"0001"
         }
      ],
      "link":[
         {
            "rel":"https://www.digipost.no/post/relations/receipts",
            "uri":"https://www.digipost.no/post/api/private/accounts/1/receipts",
            "media-type":"application/vnd.digipost-v2+json"
         },
         {
            "rel":"https://www.digipost.no/post/relations/document_inbox",
            "uri":"https://www.digipost.no/post/api/private/accounts/1/documents/inbox",
            "media-type":"application/vnd.digipost-v2+json"
         },
         ...
      ]
   },
   "link":[
      {
         "rel":"https://www.digipost.no/post/relations/search",
         "uri":"https://www.digipost.no/post/api/recipients/search",
         "media-type":"application/vnd.digipost-v2+json"
      },
      ...
   ]
}

Vi ser her at vi har fått en del informasjon om brukerens pålogging, blant annet hvilket autentiseringsnivå brukeren er innlogget med (vil alltid være nivå 2 for OAuth-pålogginger) samt et CSRF-token (mer info om dette senere). I tillegg har vi fått et objekt kalt primaryAccount. Her finner vi litt basisinformasjon om brukeren du har hentet data på vegne av.

Lenker

Det viktigste prinsippet for å komme seg videre herfra er å forstå hvordan lenkene i Digipost sitt REST-API er bygget opp, og hvordan de er tenkt brukt. Tanken bak lenkene er rett og slett at du ikke skal behøve å hardkode en rekke URL-er i applikasjonen din. Vi gir deg isteden lenker til alt du har tilgang til å gjøre. Dette betyr at den eneste URL-en koden din trenger å forholde seg til, er rot-URL-en; resten av URL-ene kan du utlede fra den første responsen.

Du kan anta at alle responser du får fra Digipost vil inneholde en liste med lenker. Denne listen inneholder link-objekter som er definert som enkle JSON-objekter. Strukturen deres er som følger:

 {
    "rel":"https://www.digipost.no/post/relations/receipts",
    "uri":"https://www.digipost.no/post/api/private/accounts/1/receipts",
    "media-type":"application/vnd.digipost-v2+json"
 }

Feltene i objektet betyr følgende:

• rel: Dette er relation-verdien til lenken. Den forteller deg hva lenken peker på. Dersom du besøker denne URL-en i nettleseren din, vil du her finne dokumentasjon på hvilket HTTP-verb du skal bruke, hvilke inndata som forventes (om det er noen), hvilke utdata du får og eventuelle feilsituasjoner som kan oppstå.
• uri: Dette er URL-en du faktisk skal bruke når du gjør forespørselen.
• media-type: Dette feltet sier noe om hva du kan forvente deg å få tilbake som respons når du kaller denne URL-en. I de fleste tilfeller vil dette være Digipost sine egne medietype, men av og til er andre ting definert her. Eksempler på dette er application/pdf for brev og text/html for kvitteringer.

Når du fra koden din skal hente ut en lenke, anbefaler vi at du forholder deg til relation-navnet. Dette er det siste ordet du finner etter skråstreken i rel-feltet. Dersom du finner lenken du skal bruke ut fra dette feltet, og ikke har noen andre hardkodede verdier i kildekoden din, vil integrasjonen din være beskyttet mot eventuelle endringer i URL-strukturen hos Digipost.

Ofte stilte spørsmål

OAuth

Digipost sitt REST-API er basert på den åpne standarden OAuth. Dette gjør det enkelt å bruke standardiserte biblioteker for å håndtere autentiseringen mot API-et.

Når brukeren har gitt deg tilgang til å aksessere hans Digipost-konto via dette API-et, kan du hente ut informasjon på samme måte som digipost.no henter ut informasjon. Faktisk bruker vi akkurat det samme API-et for innloggede brukere her på digipost.no – dette betyr at du får akkurat de samme mulighetene til å hente ut informasjon som vi har, selvsagt forutsatt at brukerne gir deg tilgang til dette. Mer informasjon om OAuth finner du her.

Tilgangsstyring

All informasjon brukeren har tilgang til via digipost.no, kan du i praktis hente ut via vårt REST-API. Den eneste begrensningen er at du ikke kan gjøre ting som krever nivå-4-pålogging (f.eks lese innholdet i sensitive brev).

For at brukerne skal vite akkurat hvilke data din app eller nettside ønsker å hente ut, har vi laget et granulært tilgangssystem. Dette betyr at du kun spør brukeren om tilgang til den informasjonen du trenger. Dette er bra for både brukeren og deg – du får tilgang til den informasjonen du trenger (men ikke mer), og brukeren kan trygt gi deg tilgang og vite akkurat hva du kommer til å hente ned.

Tilganger du kan spørre om er: