Med Digipost sine API-er for privatpersoner kan din app eller nettside enkelt liste ut en brukers brev, laste ned innholdet, og se metadata for brevet. Denne guiden viser deg hvordan du kan behandle brev i Digipost via REST-API-et.
Før du leser denne guiden, bør du lese introduksjonen til API-et.
Som alltid starter vi med å hente rotressursen:
GET https://www.digipost.no/post/api HTTP/1.1 Accept: application/vnd.digipost-v2+json Authorization: Bearer ditt-token-her
Vi får da følgende svar tilbake (noe forkortet):
{
"primaryAccount":{
"fullName":"Ola Nordmann",
...
"link":[
{
"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"
},
{
"rel":"https://www.digipost.no/post/relations/document_workarea",
"uri":"https://www.digipost.no/post/api/private/accounts/1/documents/workarea",
"media-type":"application/vnd.digipost-v2+json"
},
{
"rel":"https://www.digipost.no/post/relations/document_archive",
"uri":"https://www.digipost.no/post/api/private/accounts/1/documents/archive",
"media-type":"application/vnd.digipost-v2+json"
},
...
]
}
}
Vi har nå rot-ressursen og kan begynne å se etter lenker som leder oss dit vi vil. Lenkene vi er på jakt etter, finner vi på objektet primaryAccount, siden en brukers brev er knyttet til hennes konto. Målet vårt er å hente brevene brukeren har i postkassen; derfor leter vi etter en relation som har noe med dette å gjøre.
De tre relasjonene som har noe med mottatte dokumenter å gjøre, heter
document_inbox,
document_workarea og
document_archive.
Disse henter henholdsvis brev i postkassen, på kjøkkenbenken og i arkivet.
Siden vi er på jakt etter brukerens postkasse, bruker vi lenken knyttet til den første relationen:
{
"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"
}
Vi gjør nå et GET-kall mot URI-en i linken vi fant over for å hente postkassen til brukeren:
GET https://www.digipost.no/post/api/private/accounts/1/documents/inbox HTTP/1.1 Accept: application/vnd.digipost-v2+json Authorization: Bearer ditt-token-her
Serveren svarer da med følgende (igjen, noe forkortet):
{
"document":[
{
"subject":"Forsikringspolise 2013",
"creatorName":"Eksempelbanken AS",
"created":"2013-03-08T13:12:12.000+01:00",
"fileType":"pdf",
"fileSize":90003,
"origin":"CORPORATION",
"authentication-level":"PASSWORD",
"location":"INBOX",
"read":false,
"type":"LETTER",
"link":[
{
"rel":"https://www.digipost.no/post/relations/self",
"uri":"https://www.digipost.no/post/api/private/accounts/1/documents/7",
"media-type":"application/vnd.digipost-v2+json"
},
{
"rel":"https://www.digipost.no/post/relations/update_document",
"uri":"https://www.digipost.no/post/api/private/accounts/1/documents/7",
"media-type":"application/vnd.digipost-v2+json"
},
{
"rel":"https://www.digipost.no/post/relations/delete_document",
"uri":"https://www.digipost.no/post/api/private/accounts/1/documents/7",
"media-type":"application/vnd.digipost-v2+json"
},
{
"rel":"https://www.digipost.no/post/relations/forward_document",
"uri":"https://www.digipost.no/post/api/private/accounts/1/documents/7/forward",
"media-type":"application/vnd.digipost-v2+json"
},
{
"rel":"https://www.digipost.no/post/relations/get_document_content",
"uri":"https://www.digipost.no/post/api/private/accounts/1/documents/7/content",
"media-type":"application/octet-stream"
},
{
"rel":"https://www.digipost.no/post/relations/organisation_logo",
"uri":"https://www.digipost.no/post/api/private/organisations/5/logo",
"media-type":"image/png"
}
]
},
...
],
...
}
Vi ser her at vi har fått en liste med dokumenter. Denne listen inneholder alle metadata for dokumentene brukeren har i postkassen sin.
Hvert dokument har en god del attributter, og en god del lenker som brukes til å gjøre noe med hvert dokument.
La oss se på et par konkrete eksempler:
Hvert dokument har et innhold. Som vi ser av feltet fileType er dette dokumentet en PDF-fil. Dersom vi ønsker å laste ned denne PDF-filen, finner vi lenken for dette. Ved å se igjennom listen av lenker, ser vi at vi har en lenke med relationen get_document_content – dette må være rett link. Vi ser av dokumentasjonen for denne at vi kan gjøre helt vanlige GET-forespørsler mot den:
GET https://www.digipost.no/post/api/private/accounts/1/documents/7/content HTTP/1.1 Accept: application/octet-stream Authorization: Bearer ditt-token-her
Serveren vil da svare oss med PDF-dokumentet, slik at vi kan vise dette.
Kanskje vi ønsker å hente logoen til organisasjonen som har sendt oss brevet. Vi ser av link-listen at dette dokumentet har en lenke med relation organisation_logo. Dokumentasjonen for denne sier oss at vi kan gjøre en enkel GET-forespørsel for å få den.
Her blir vi forøvrig introdusert til en viktig ting: ikke alle dokumenter har en tilhørende logo. Dersom brevet er sendt fra en privatperson, har det åpenbart ikke en logo. Dette gjelder de fleste ting i API-et: Du kan ikke alltid forvente å finne en lenke. Et annet eksempel på dette er dersom du ønsker å laste ned innholdet til et dokument, men ikke er innlogget på høyt nok sikkerhetsnivå – da får du heller ikke en lenke til dette. Derfor bør du alltid når du leter etter lenker ha en god «fallback» i tilfelle lenken ikke finnes i listen.
Det at lenken ikke finnes, er ikke en feilsituasjon; det er en måte å indikere at innholdet du ønsker, ikke er tilgjengelig.
Det siste eksempelet vi skal se på, er flytting av dokumentet fra postkassen til arkivet. Vi ser at vi har en lenke med relation update_document. Ved å lese dokumentasjonen for denne, så ser vi at vi kan gjøre en POST med dokumentet til lenken, og da vil vi kunne endre en del av feltene. Hvilke vi har tilgang til å endre, ser vi også av dokumentasjonen.
Siden vi ønsker å flytte dokumentet til arkivet, endrer vi feltet location. Vi POSTer så dokumentet inn, og sørger for å sette riktige medietyper:
POST https://www.digipost.no/post/api/private/accounts/1/documents/7 HTTP/1.1
Content-type: application/vnd.digipost-v2+json
Accept: application/vnd.digipost-v2+json
Authorization: Bearer ditt-token-her
{
"subject":"Forsikringspolise 2013",
"creatorName":"Eksempelbanken AS",
"created":"2013-03-08T13:12:12.000+01:00",
"fileType":"pdf",
"fileSize":90003,
"origin":"CORPORATION",
"authentication-level":"PASSWORD",
"location":"ARCHIVE",
"read":false,
"type":"LETTER"
}
Vi får nå tilbake det oppdaterte dokumentet og ser at plasseringen ble oppdatert.
Vi har nå sett på hvordan vi kan gå via rot-ressursen, finne riktig URL for å hente ut alle dokumentene i postkassen, hente ut metadata for et enkelt dokument, bruke lenkene for hvert dokument til å hente ut mer info slik som PDF-fil og logo, og til slutt oppdatere dokumentet.
Det er enda flere muligheter knyttet til dokumentene: vi kan endre emne, vi kan videresende dokumentet, vi kan slette det og så videre. Ved å se på lenkene du får ut på dokumentet, og lese relation-sidene for disse, vil du enkelt kunne forstå hvordan du gjør alle disse tingene.