You are viewing the documentation for Digipost API Client 2.x, which is not the most recently released version. The newest version is 4.x and can be browsed here.

Introduction

This API makes it possible to access agreements between Digipost users and third parties, and followingly perform certain operations which the user has granted the third party. For instance, the user may permit that certain information may be provided to a third party in order to receive a service. The user may also grant the sender access to documents through an agreement. The agreement governs which documents the sender can access and what operations it can perform.

Download

The library can be acquired from Maven Central Repository, using the dependency management tool of your choice. For Maven you can use the following dependency:

<dependency>
    <groupId>no.digipost</groupId>
    <artifactId>digipost-useragreements-api-client-java</artifactId>
    <version>2.0-delta</version>
</dependency>

Prerequisites

The library requires Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files for JDK/JRE to be installed: www.oracle.com/technetwork/java/javase/downloads/index.html

Starting from Java 8 build 152 the unlimited strength cryptography policy files are bundled with the JDK/JRE, and may be enabled by setting the security property security.policy to "unlimited". How this is set depends on how you deploy your application, but if done early enough, i.e. before the JCE framework is initialized, it can be set programatically like this:

Security.setProperty("crypto.policy", "unlimited"); // only effective on Java 8 b152 or newer

More details are available in the Java 8u152 Release Notes.

Instantiate and configure client

InputStream key = getClass().getResourceAsStream("certificate.p12");

HttpHost proxy = new HttpHost("proxy.example.com", 8080, "http");

BrokerId brokerId = BrokerId.of(1234L);

DigipostUserAgreementsClient client = new DigipostUserAgreementsClient
		.Builder(brokerId, key, "password")
		.useProxy(proxy) 					//optional
		.setHttpClientBuilder(HttpClientBuilder.create())	//optional
		.serviceEndpoint(URI.create("https://api.digipost.no")) //optional
		.build();

Identify Digipost user

final SenderId senderId = SenderId.of(1234L);
final UserId userId = UserId.of("01017012345");

final IdentificationResult identificationResult = client.identifyUser(senderId, userId);
boolean isDigipost = identificationResult.getResult() == IdentificationResultCode.DIGIPOST;

Invoice

The agreement type INVOICE_BANK allows a sender to retrieve a user’s invoices and update their payment status.

Create, read, update and delete agreement

final SenderId senderId = SenderId.of(1234L);
final UserId userId = UserId.of("01017012345");

//CreateAgreement
client.createOrReplaceAgreement(senderId, Agreement.createInvoiceBankAgreement(userId, false));

//GetAgreement
final GetAgreementResult agreement = client.getAgreement(senderId, INVOICE_BANK, userId);

//UpdateAgreement
client.createOrReplaceAgreement(senderId, Agreement.createInvoiceBankAgreement(userId, true));

//DeleteAgreement
client.deleteAgreement(senderId, INVOICE_BANK, userId);

Get and verify invoice agreement

final SenderId senderId = SenderId.of(1234L);
final UserId userId = UserId.of("01017012345");

final GetAgreementResult agreementResult = client.getAgreement(senderId, INVOICE_BANK, userId);
if (agreementResult.isSuccess()) {
	final Agreement agreement = agreementResult.getAgreement();
} else {
	switch (agreementResult.getFailedReason()) {
		case UNKNOWN_USER: //User does not have a Digipost account
		case NO_AGREEMENT: //No agreement exists for user
	}
}

Get invoices

final SenderId senderId = SenderId.of(1234L);
final UserId userId = UserId.of("01017012345");

final List<Document> unpaidInvoice = client.getDocuments(senderId, INVOICE_BANK, userId,
	GetDocumentsQuery.empty());

final List<Document> allOptions = client.getDocuments(senderId, INVOICE_BANK, userId,
	GetDocumentsQuery.builder()
		.invoiceStatus(InvoiceStatus.PAID)
		.invoiceDueDateFrom(new LocalDate(2017, 1, 1))
		.invoiceDueDateTo(new LocalDate(2017, 5, 1))

Update invoice status

final SenderId senderId = SenderId.of(1234L);
final UserId userId = UserId.of("01017012345");

final List<Document> unpaidInvoice = client.getDocuments(senderId, INVOICE_BANK, userId, GetDocumentsQuery.empty());
final Document invoice = unpaidInvoice.get(0);

//set status to PAID
client.payInvoice(senderId, INVOICE_BANK, invoice.getId(), new InvoicePayment(123));

//set status to DELETED
client.deleteInvoice(senderId, INVOICE_BANK, invoice.getId());

//generic version
client.updateInvoice(senderId, INVOICE_BANK, invoice.getId(), new InvoiceUpdate(InvoiceStatus.PAID, 123));

Bank account numbers

Users may allow access to their registered bank account numbers for specific senders. The agreement type BANK_ACCOUNT_NUMBER_FOR_RECEIPTS allows a sender to retrieve users’ bank account numbers in order to couple the bank accounts with digital receipts to be sent to the users’ Digipost inbox. The sending is performed with the regular API for sending documents to Digipost users: digipost.github.io/digipost-api-client-java

Fetch all bank account numbers

import static no.digipost.api.useragreements.client.AgreementType.BANK_ACCOUNT_NUMBER_FOR_RECEIPTS;

...

// The ID of the receipt supplier party, i.e. the organization with access to bank account numbers
SenderId sender = SenderId.of(1234L);


// The stream is made available immediately when the client starts receiving
// the response, which is a rather long chunked http response.
StreamingRateLimitedResponse<UserId> accountsResponse =
    client.getAgreementOwners(sender, BANK_ACCOUNT_NUMBER_FOR_RECEIPTS);


// The processing of the stream should
// continuously persist/update the received agreements.
accountsResponse.map(UserId::serialize).forEach(this::persistAccountNumber);


// Lastly, get the duration you must wait before you are allowed to do the request
// again, and ensure that any subsequent request does not happen before.
Duration delay = accountsResponse.getDelayUntilNextAllowedRequest();

...

private void persistAccountNumber(String accountNumber) {
    // handle persisting or updating the received account number
}

Alternative: consume response with Java Stream API

// Alternatively, one can acquire the underlying Java Stream from the
// StreamingRateLimitedResponse, but it is imperative with proper resource
// management and that the stream is closed after it is consumed.
try (Stream<UserId> accounts = accountsResponse.asStream()) {
    accounts.map(UserId::serialize).forEach(this::persistAccountNumber);
}

Send receipt to user with bank account number

This is performed with the Digipost API Client library.

Messages sent to user

The agreement type FETCH_MESSAGES allows a sender to retrieve metadata for documents that sender has previously sent to the user, that e.g. can be used to present a synthetic inbox to the user. The metadata includes a deep-link the user can use to access the document in Digipost.

Create, read, update and delete agreement

final SenderId senderId = SenderId.of(1234L);
final UserId userId = UserId.of("01017012345");

//CreateAgreement
client.createOrReplaceAgreement(senderId, Agreement.createAgreement(userId, AgreementType.FETCH_MESSAGES));

//GetAgreement
final GetAgreementResult agreement = client.getAgreement(senderId, AgreementType.FETCH_MESSAGES, userId);

//UpdateAgreement
client.createOrReplaceAgreement(senderId, Agreement.createAgreement(userId, AgreementType.FETCH_MESSAGES));

//DeleteAgreement
client.deleteAgreement(senderId, AgreementType.FETCH_MESSAGES, userId);

Get and verify agreement

final SenderId senderId = SenderId.of(1234L);
final UserId userId = UserId.of("01017012345");

final GetAgreementResult agreementResult = client.getAgreement(senderId, AgreementType.FETCH_MESSAGES, userId);
if (agreementResult.isSuccess()) {
	final Agreement agreement = agreementResult.getAgreement();
} else {
	switch (agreementResult.getFailedReason()) {
		case UNKNOWN_USER: //User does not have a Digipost account
		case NO_AGREEMENT: //No agreement exists for user
	}
}

Get documents

final SenderId senderId = SenderId.of(1234L);
final UserId userId = UserId.of("01017012345");

final List<Document> previouslyDeliveredDocs = client.getDocuments(senderId, AgreementType.FETCH_MESSAGES,
	userId, GetDocumentsQuery.empty());

final ZoneId OSLO_ZONE = ZoneId.of("Europe/Oslo");
final List<Document> withinTimeWindow = client.getDocuments(senderId, AgreementType.FETCH_MESSAGES, userId,
	GetDocumentsQuery.builder()
		.deliveryTimeFrom(ZonedDateTime.of(2020, 1, 1, 0, 0, 0, 0, OSLO_ZONE))
		.deliveryTimeTo(ZonedDateTime.now(OSLO_ZONE))
		.build());