Utvikle tilkobling

Generelle utviklingsoppgaver for Digipost-tilkobling er beskrevet her. Nedenfor beskriver vi de spesifikke utviklingsoppgavene som må gjøres for å integrere mot batch-grensesnittet til Digipost.

1. Generere jobbfil for Digipost

For å sende en mottakersplitt- eller masseutsendelse-jobb til Digipost må du produsere et xml-dokument i henhold til Digipost sin xsd. Se mottakersplitt.xsd og masseutsendelse.xsd i batch-startpakken for eksempler. For å generere xml-en anbefaler vi at du benytter et xml-bibliotek som garanterer at den produserte xml-en er gyldig i henhold til xsd-en.

En mottakersplitt-jobb er et zip-arkiv som inneholder en fil med navnet mottakersplitt.xml.

En masseutsendelse-jobb er et zip-arkiv som inneholder en fil med navnet masseutsendelse.xml og tilhørende dokumenter-filer. Mottakerne angis i masseutsendelse.xml. Hvis man sender samme dokument til flere mottakere, skal jobb-zip-arkivet kun inneholde én kopi av pdf-dokumentet, og ikke en kopi for hver mottaker.

Se batch-startpakken for eksempler på mottakersplitt og masseutsendelse.

MERK: Selv om du kan gjenbruke samme filnavn på et ZIP-arkiv, så vil vi sterkt fraråde det. Grunnen til det er at hvis du ikke venter med å laste opp ny før det forrige ZIP-arkivet er ferdigbehandlet kan det oppstå race-condition hvor vi har startet å behandle en jobb som du plutselig overskriver. Du vil da i praksis miste den første opplastingen din. Bruk derfor en eller annen unik id, tidspunkt eller noe slikt for å identifisere filen din unikt. Et annet positivt resultat av det er at du da kan se hvilken jobb en kvittering handler om.

2. Verifisere dokument–mottaker-kobling

Du må selv verifisere at dine genererte masseutsendelse.xml-filer inneholder korrekte mottaker–brev-koblinger (dvs. at rett brev sendes til rett person).

3. Send filer til testkontoen

En vesentlig del av testingen vil være å generere jobbfiler (mottakersplitt og masseutsendelse), laste dem opp til din virksomhets testkonto i Digipost, og se at de blir akseptert (dvs. er gyldige), blir prosessert og at en kvitteringsfil blir generert.

4. Verifiser forventet resultat i testkontoen på virksomhets-webside

Virksomhetssiden for din konto i Digipost på https://www.digipost.no/bedrift er et viktig verktøy for monitorering, feilsøking, etc. Vi oppfordrer deg til å gjøre deg godt kjent med den under utvikling og testing, slik at du vet hvordan du kan benytte den i produksjon. Her kan du blant annet se dine aktive jobber med status, informasjon og eventuell feilinformasjon, såvel som jobb-historikk.

5. Laste opp jobbfil til Digipost

Batch filutveksling

For å sende inn jobber fra din test konto via sftp må du først generere en ssh-nøkkel. Du kan enten la Digipost generere en nøkkel og laste den ned via webgrensesnittet, eller du kan generere en nøkkel på egen hånd og laste den offentlige nøkkelen opp til Digipost. I begge tilfeller må du logge inn på https://www.digipost.no/bedrift og gå "Integrasjon" > "Innstillinger for masseutsendelser". Vi anbefaler at du benytter separate nøkler for test- og prod-kontoer. Når du har lastet opp en nøkkel, kan du benytte den så lenge du vil. Dersom du ønsker å bytte nøkkel, laster du bare opp den nye nøkkelen – den gamle vil da overskrives.

Når du logger deg inn på din virksomhets Digipost-sftp-konto, vil du se tre underkataloger: mottakersplitt, masseutsendelse og masseutsendelse-afp (ikke lenger i bruk). Jobbfiler som lastes opp, må legges i korrekt katalog. Når jobbfilen er ferdig lastet opp, vil den automatisk bli flyttet ut av sftp-området og inn i Digipost sin prosesseringskø. Du kan deretter vente på (polle) at en kvitteringsfil skal bli produsert i kvitteringskatalogen. Dersom du benytter manuell godkjenning, må du logge inn på https://www.digipost.no/bedrift og godkjenne jobben før du får en kvitteringsfil. Dersom jobben skulle feile, vil du kunne se feilinformasjon på virksomhetsnettsiden.

I utviklingsfasen kan du benytte din virksomhets test-sftp-konto i Digipost (sftp.digipost.no) til å teste opplastning av jobber og nedlastning av responser.

6. Laste ned kvitteringsfil og håndtere avvik

Hver av de tre katalogene nevnt ovenfor inneholder en underkatalog med navnet kvittering. Etter at jobben har blitt ferdigprosessert, kan du laste ned kvitteringsfilen fra kvitteringskatalogen. Prosesseringstiden er avhengig av jobbstørrelsen og hvor mange andre jobber som ligger foran i køen. Kvitteringen er et zip-arkiv som har navn på formatet dittfilnavn.mottatt.timestamp.zip eller dittfilnavn.resultat.timestamp.zip, så hvis jobbfilen du lastet opp har navnet min-mottakersplitt.zip, vil zip-arkivet for resultat kvitteringen for eksempel ha navnetmin-mottakersplitt.resultat.20111201-145344585.zip. For resultatkvitteringen vil Zip-arkivet inneholde en fil med navnet jobbtype-resultat.xml eller jobbtype-resultat.txt, hvor jobbtype enten er masseutsendelse eller mottakersplitt. Normalt vil kvitteringsfilen være en xml-fil som bruker samme xsd-versjon som den opplastede jobbfilen. Kvitteringsfilen vil være en tekstfil i de tilfellene der vi ikke klarer å lese den opplastede xml-filen, siden vi da ikke kan avgjøre hvilken xsd-versjon som ble brukt. Dette gjelder for eksempel dersom den innsendte xml-en ikke validerer i henhold til xsd-en.

Dersom jobben er vellykket, vil resultat kvitteringsfilen angi statusen for hver av mottakerne. I en mottakersplitt resultat kvittering vil det fremgå hvilke mottakere som er Digipost-brukere og hvilke andre mottakere vi klarte å identifisere; i en masseutsendelse resultat kvittering vil det fremgå hvilke mottakere som fikk tilsendt brev (dvs. hvem som var Digipost-brukere).

Dersom jobben feilet, vil kvitteringsfilen inneholde en kort beskrivelse av årsaken.

Et avsendersystem må lese kvitteringen og håndtere eventuelle avvik, for eksempel ved å sende en e-post til en administrator, eller automatisk sende brev til mottakere som ikke er Digipost-brukere, via en alternativ kanal (for eksempel fysisk post). Dersom masseutsendelsen er basert på en nylig utført mottakersplitt (dvs. en oppdatert liste av Digipost-brukere), så forventes det i utgangspunktet ingen avvik. Du velger selv om du beholder kvitteringsfilen for fremtidig referanse.

7. Test

Ved å laste opp jobber til testkontoen din får du testet at jobbfilene dine (mottakersplitt og masseutsendelse) er gyldige for prosessering av Digipost. Du får også generert kvitteringsfiler.

8. Produksjon

Når du har testet integrasjonen mot test-kontoen til virksomheten din og har aktivert din prod-konto, kan du gå i produksjon ved å gjøre følgende:

1. Endre avsender-id i mottakersplitt.xml eller masseutsendelse.xml til id-en til produksjonskontoen din.
2. Laste opp jobb-zip-filer til prod_<prod-konto-id>@sftp.digipost.no med den private nøkkelen for prod-kontoen din.

8.1 Verifiser første utsendelser i produksjon med manuell godkjenning

Vi anbefaler at du kjører de første utsendelsene med «manuell godkjenning». Dette betyr at du, etter opplastning av en masseutsendelse-jobb, må gå inn på din virksomhetsside i Digipost og manuelt godkjenne jobben før brevene faktisk sendes. Dette gir en ekstra og siste forsikring om alt er som det skal, før du kjører brevutsendinger helautomatisert. Dersom noe er galt, kan du kansellere jobben.

Når du, etter et par utsendelser, ser at alt fungerer som det skal, kan du velge å skru på automatisk godkjenning. Om du alltid ønsker å godkjenne manuelt, kan du også gjøre det.

Hvordan du angir manuell/automatisk godkjenning i masseutsendelse.xml, er beskrevet i batch-startpakken.