Sende post
For å sende post så må du først lage en DigitalPost
eller en FysiskPost
, så opprette en Forsendelse
og legge ved posten. Deretter sendes denne gjennom en SikkerDigitalPostKlient
. Når brevet er sendt så kan du spørre om status på en meldingskø. Hvis du mottar en kvittering så kan du sjekke innholdet og så bekrefte mottatt kvittering.
Opprette digital post
Mottaker mottaker = Mottaker
.builder("99999999999")
.build();
// Integrasjonspunktet henter mobilnummer til mottaker fra KRR.
SmsVarsel smsVarsel = SmsVarsel.builder("Du har mottatt brev i din digitale postkasse")
.build();
// Integrasjonspunktet henter E-postadresse til mottaker fra KRR.
EpostVarsel epostVarsel = EpostVarsel.builder("Du har mottatt brev i din digitale postkasse")
.varselEtterDager(asList(1, 4, 10))
.build();
DigitalPost digitalPost = DigitalPost
.builder(mottaker, "Ikke-sensitiv tittel")
.virkningsdato(new Date())
.aapningskvittering(false)
.sikkerhetsnivaa(Sikkerhetsnivaa.NIVAA_3)
.epostVarsel(epostVarsel)
.smsVarsel(smsVarsel)
.build();
Opprette fysisk post
FysiskPost fysiskPost = FysiskPost.builder()
.adresse(
KonvoluttAdresse.build("Ola Nordmann")
.iNorge("Fjellheimen 22", "", "", "0001", "Oslo")
.build())
.retur(
Returhaandtering.DIREKTE_RETUR.MAKULERING_MED_MELDING,
KonvoluttAdresse.build("Returkongen")
.iNorge("Returveien 3", "", "", "0002", "Oslo")
.build())
.sendesMed(Posttype.A_PRIORITERT)
.utskrift(Utskriftsfarge.FARGE)
.build();
Opprette selve forsendelsen
DigitalPost digitalPost = null; //Som initiert tidligere
Dokument hovedDokument = Dokument
.builder("Sensitiv brevtittel", new File("/sti/til/dokument"))
.mimeType("application/pdf")
.build();
Dokumentpakke dokumentpakke = Dokumentpakke.builder(hovedDokument)
.vedlegg(new ArrayList<>())
.build();
AvsenderOrganisasjonsnummer avsenderOrgnr =
AktoerOrganisasjonsnummer.of("999999999").forfremTilAvsender();
Avsender avsender = Avsender
.builder(avsenderOrgnr)
.build();
Forsendelse forsendelse = Forsendelse
.digital(avsender, digitalPost, dokumentpakke)
.konversasjonsId(UUID.randomUUID().toString())
.spraakkode("NO")
.build();
Utvidelser
Difi har egne dokumenttyper, eller utvidelser, som kan sendes som metadata til hoveddokumenter. Disse utvidelsene er strukturerte xml-dokumenter med egne mime-typer. Disse utvidelsene benyttes av postkasseleverandørene til å gi en øket brukeropplevelse for innbyggere. Les mer om utvidelser på https://begrep.difi.no/SikkerDigitalPost/
Utvidelsene ligger som generert kode i sdp-shared
, som er en avhengighet av dpi-proxy-klient-java
. Du kan selv lage kode
for å generere xml fra instanser av disse typene med JAXB, eller du kan lage xml på andre måter.
SDPLenke lenke = new SDPLenke();
lenke.setUrl("http://example.com");
StringWriter stringWriter = new StringWriter(lenke.toString().length());
JAXBContext.newInstance(SDPLenke.class).createMarshaller().marshal(lenke, stringWriter);
MetadataDokument innkalling = MetadataDokument.builder(
"lenke.xml",
"application/vnd.difi.dpi.lenke+xml",
stringWriter.toString().getBytes()
).build();
Dokument hovedDokument = Dokument
.builder("Sensitiv brevtittel", new File("/sti/til/dokument"))
.mimeType("application/pdf")
.metadataDocument(innkalling)
.build();
Opprette klient og sende post
Forsendelse forsendelse = null; //Som initiert tidligere
KlientKonfigurasjon klientKonfigurasjon = KlientKonfigurasjon
.builder(URI.create("http://localhost:9093")) // Integrasjonspunkt URI.
.connectionTimeout(20, TimeUnit.SECONDS)
.build();
DatabehandlerOrganisasjonsnummer databehandlerOrgnr =
AktoerOrganisasjonsnummer.of("555555555").forfremTilDatabehandler();
Databehandler databehandler = Databehandler
.builder(databehandlerOrgnr)
.build();
SikkerDigitalPostKlient sikkerDigitalPostKlient = new SikkerDigitalPostKlient(databehandler, klientKonfigurasjon);
try {
sikkerDigitalPostKlient.send(forsendelse);
} catch (SendException sendException) {
SendException.AntattSkyldig antattSkyldig = sendException.getAntattSkyldig();
String message = sendException.getMessage();
}
Hent kvittering og bekreft
SikkerDigitalPostKlient sikkerDigitalPostKlient = null; //Som initiert tidligere
ForretningsKvittering forretningsKvittering = sikkerDigitalPostKlient.hentKvittering();
if (forretningsKvittering instanceof LeveringsKvittering) {
//Forsendelse er levert til digital postkasse
} else if (forretningsKvittering instanceof AapningsKvittering) {
//Forsendelse ble åpnet av mottaker
} else if (forretningsKvittering instanceof MottaksKvittering) {
//Kvittering på sending av fysisk post
} else if (forretningsKvittering instanceof ReturpostKvittering) {
//Forsendelse er blitt sendt i retur
} else if (forretningsKvittering instanceof Feil) {
//Feil skjedde under sending
}
sikkerDigitalPostKlient.bekreft(forretningsKvittering);
Husk at det ikke er mulig å hente nye kvitteringer før du har bekreftet mottak av nåværende.
Hvordan komme i gang
Tekniske krav
- Java 1.8 eller nyere
- Maven for å laste ned dpi-proxy-klient-java
Endringer fra sikker digital post klient
Formålet med dette biblioteket er å tilby en drop-in erstatning for sikker-digital-post-klient-biblioteket, slik at man enkelt kan ta i bruk Integrasjonspunktet fremfor direkte sending til meldingsformidleren. API-et til sikker-digital-post-klient er bevart etter beste evne. Under er det listet opp konsepter som skiller seg fra sikker-digital-post-klient.
- Konfigurasjon av miljø
- Endring i opprettelse av printforsendelse
- Metoder og klasser markert som deprecated
- mpcID
- Prioritet
- Nøkkelpar
- Fakutererbare bytes
- SOAP-relatert kode er fjernet
- SendResultat
Konfigurasjon av miljø
Konfigurasjon av miljø gjøres nå ved å spesifisere URL-en til integrasjonspunktet som man ønsker å benytte.
Klientkonfigurasjon
tilbyr nå tre metoder for å sette miljø. Vær OBS på å endre parameter hvis string- eller URI-builder-metoden ble benyttet i tidligere klientbibliotek da man i tilfellet ikke vil få noen typefeil/synlige feil i koden.
//builder(Miljo miljo)}
Miljo INTEGRASJONSPUNKT_LOCALHOST = new Miljo(URI.create("http://localhost:9093"));
KlientKonfigurasjon klientKonfigurasjon = KlientKonfigurasjon.builder(miljo).build();
//builder(URI integrasjonspunktRoot)
URI INTEGRASJONSPUNKT_URI = URI.create("http://localhost:9093");
KlientKonfigurasjon klientKonfigurasjon = KlientKonfigurasjon.builder(INTEGRASJONSPUNKT_URI).build();
//@Deprecated
//builder(String integrasjonspunktRootUri)
String INTEGRASJONSPUNKT_URI = "http://localhost:9093";
KlientKonfigurasjon klientKonfigurasjon = KlientKonfigurasjon.builder(INTEGRASJONSPUNKT_URI).build();
Endring i opprettelse av printforsendelse:
// Tidligere
Forsendelse forsendelse = Forsendelse.fysisk(avsender, fysiskPost, dokumentpakke).build();
// Nå
String mottakerPersonNummer = "27127000293";
final Mottaker mottaker = Mottaker.builder(mottakerPersonNummer).build();
Forsendelse forsendelse = Forsendelse.fysisk(avsender, fysiskPost, dokumentpakke, mottaker).build();
Metoder og klasser markert som deprecated.
Utdaterte konsepter er markert med Deprecated. Det er anbefalt å benytte overloadet metoder i buildere. Se JavaDoc for deprecated metoder for hvilken alternativ metode som burde benyttes.
mpcID
Fra tidligere dokumentasjon:
Sett en unik `Forsendelse.mpcId` for å unngå at det konsumeres kvitteringer på tvers av ulike avsendere med samme organisasjonsnummer. Dette er nyttig i større organisasjoner som har flere avsenderenheter. I tillegg kan det være veldig nyttig i utvikling for å unngå at utviklere og testmiljøer går i beina på hverandre.
MpcID settes nå i integrasjonspunktet.
Prioritet
Kø-prioritet settes nå i integrasjonspunktet.
Nøkkelpar
Nøkler håndteres av integrasjonspunktet.
Fakturerbare bytes
Denne informasjonen er ikke lengre mulig å hente ut fra klientbiblioteket da integrasjonspunktet ikke eksponerer dette.
SOAP-relatert kode er fjernet.
Dette innebærer metoden getMeldingTemplate
som ble eksponert fra SikkerDigitalPostKlient
.
SendResultat
Grunnet data eksponert fra integrasjonspunktet er det gjort endringer i følgende metoder i klassen SendResultat
:
// Returnerer nå `null`
String getMeldingsId();
// Returnerer nå `null`
String getReferanseTilMeldingsId();
// Returnerer nå `0`
long getFakturerbareBytes();
Det er samtidig innført en ny metode, som burde benyttes fremfor dem over:
String getConversationId()
Logging av forespørsel og respons
Klienten støtter registrering av http interceptors som kan brukes for direkte tilgang og til logging av request og responser mot integrasjonspunktet.
KlientKonfigurasjon.builder()
.httpRequestInterceptors(new HttpRequestInterceptor() {
@Override
public void process(HttpRequest request, HttpContext context) throws HttpException, IOException {
System.out.println("Utgående request!");
}
})
.httpResponseInterceptors(new HttpResponseInterceptor() {
@Override
public void process(HttpResponse response, HttpContext context) throws HttpException, IOException {
System.out.println("Innkommende request!");
}
})
.build();
Debugging
Merk: Innstillingene under er ikke anbefalt i produksjonsmiljøer.
Den underliggende http-klienten har støtte for å logge meldingene som sendes over nettverket. Sett org.apache.http.wire
til debug
eller lavere for å slå på denne loggingen.
Alternativt kan logging av requests gjøres ved hjelp av interceptors som beskrevet over.
Feilhandtering
Exception-hierarkiet i klienten er plassert under SikkerDigitalPostException
. Deretter er de grovt kategorisert i KonfigurasjonException
og SendException
.
KonfigurasjonException
er typisk feil relatert til konfigurasjon av klienten, som for eksempel manglende støtte for XML-standarder i Java-installasjonen, ugyldig keystore og lignende.
SendException
brukes for feil relatert til gjennomføringen av en sending. Disse blir forsøkt markert med om feilen skyldes forhold på klienten eller serveren.
Dersom en SendException
skyldes feil på klienten vil det generelt ikke være hensiktsmessig å gjøre en automatisk retry av forsendelsen.
Custom mapping av feil
Det er mulig å registrerte en ExceptionMapper
for oversetting av feil som oppstår i forbindelse med sending av post. Dette gjøres med SikkerDigitalPostKlient.setExceptionMapper()
.
Tips og triks
Validering av PDF-dokumenter som sendes til utskriftstjenesten
Dokumenter som sendes til utskriftstjenesten valideres før de printes. Derfor anbefaler vi at du bruker en egen printvalidator som kan benyttes for å validere printbarheten til PDF-dokumentet før det sendes til utskriftstjenesten.