Bokmål Nynorsk English
Registrer deg Register
Språk    Language    Bokmål Nynorsk English Tjenester privat Tenester privat Private Tjenester bedrift Tenester verksemd Business Digipost Labs Hjelp Help Hjelp Help
For partnere For partnarar For partners For utviklere For utviklarar For developers Sikkerhet Sikkerheit Security Vilkår Terms
Du må oppgradere nettleseren din for å bruke Digipost. Les mer her.

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:

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:

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:

Rettighet Muligheter dette gir
READ_ACCOUNT_INFOLese kontoinformasjon (navn, fødselsdato, adresse, epostadresse, telefonnummer)
READ_DOCUMENT_META_INFOLese informasjon om brev (men ikke innhold og ikke informasjon om konfidensielle brev)
READ_DOCUMENT_CONTENTLese innhold i brev (ikke brev som krever BankID/Buypass)
UPDATE_DOCUMENTOppdatere brev (endre emne)
DELETE_DOCUMENTSlette brev
UPLOAD_DOCUMENTLaste opp i arkivet
SEND_DOCUMENTSende brev
READ_SETTINGSSe innstillinger
READ_RECEIPTSLese kvitteringer (dersom du har aktivert dette)
DELETE_RECEIPTSSlette kvitteringer (dersom du har noen)
UPDATE_SETTINGSOppdatere innstillinger
Åpne Posten og Bring sin chatdialog