Access Point

What is Peppol ?

Peppol enables participants to exchange standards-based electronic documents over the Peppol network. A general business overview of Peppol is available in this blog post.

Traditional document exchange services are provided by integrators that will send the document based on specific and expensive to operate point-to-point connections. Peppol is based on a 4 corner model where the sender has a sending access point and the receiver has a receiving access point. The communication between the sender and the receiver is governed by Peppol standards which removes the cost of the point-to-point connections. This way, everyone can be connected to everyone and all the participants can choose a commodity access point.

Peppol is in use in 32 countries in Europe plus Canada, Singapore and USA with Peppol Authorities placed in 12 countries.

Peppol is based on three major pillars:

• the network (Peppol eDelivery Network)
• the document specifications (Peppol Business Interoperability Specifications also called Peppol BIS)
• the legal framework that defines the network governance (Peppol Transport Infrastructure Agreements also called the Peppol TIA)

Digiteal is a Peppol Access Point certified by the Belgian Peppol Authority, operated by the Belgian government. The Belgian Peppol Authority manages the list of all their certified Peppol Access Points.

For more information about Peppol, the country profiles and the access points can be found on the official Peppol website.

Peppol identifiers

To identify participants in the Peppol network, identifiers are used. The identifiers are composed of an identifier type and an identifier value.
They are assembled as {type}:{value}. For example, type 9925 corresponds to a Belgian VAT number. The Peppol identifier of Digiteal using that type is therefore 9925:be0630675588.

The list of all the identifier types that can be used is available in the Peppol codelists.

When registering a company and to ensure maximum reachability, it is better to register the company for all the possible company identifiers associated to it. For example, in Belgium, the mandatory identifier type is 0208. So, when registering a company, we advise you to register for both the 0208 and the 9925 types.

Often, you will want to derive the various PEPPOL identifiers from a company VAT number. Here is a little recipe that will enable you to do this:

Address Registry and Peppol directory

The entities that are able to receive documents from the Peppol network are called Peppol participants. They are registered in a technical address registry called the SML (in PROD) and the SMK (in TEST). They operate through a DNS as explained here.

These registries redirect to SMPs that define the capabilities of each Peppol participant. To browse this technical registry manually, please use the participant query tool provided by Philip Helger.

There is also a Peppol directory that enables the general public to find the capabilities of the Peppol participants and their contact information.

To find if a company is able to receive a specific document type, you can call Digiteal API Get supported document types. This endpoint will read the address registry and provide you the list of document types supported by the company.

Document types

The lingua franca on Peppol is UBL. The documents exchanged on Peppol include credit notes, orders, advance shipping notes, invoices, catalogues, message level responses, etc.

Digiteal supports the following document types:

These documents are part of the the Peppol BIS Billing process and are described in the Peppol official documentation.

There are also technical messages exchanged:

• Transport ACK (xsd, example)

UBL invoice generation

The most important document to be able to generate and understand is the invoice. In order to streamline the implementation of the UBL invoice generation in your application, here is a very basic recipe that will show you how easily it can be done:

Get started with the API

Whether you are an ERP, CRM, an accounting package or a company wishing to send/receive invoices from/to Peppol; in order to send or receive invoices through the Digiteal Access Point, you must be granted the role of Peppol integrator within Digiteal. To become Peppol integrator contact the Digiteal's sales team.

Peppol Integration

Integration from a SaaS solution

Integrating Peppol APIs of Digiteal from a SaaS solution is straightforward:

• The Sender using your SaaS solution wishes to send a document through Peppol. You can directly use the API to send it.
• You received a document for one your registered participant. You can inform your customer that will see the document from your Saas solution.

Integration from an on-premises solution

Integrating Peppol APIs of Digiteal from an on-premises solution requires a gateway layer for the following reasons:

• The on-premises Sender software might not be up-to-date and it might not be sending valid Peppol documents. The Sender Peppol Integrator Gateway can fix the outgoing documents so that they can be valid according to the latest specifications.
• The on-premises Sender software cannot contain the credentials of the Integrator that are used to connect to the Digiteal Peppol Access Point.
• All documents sent to the Integrator, for all the registered participants, will be sent through webhooks to a single URL. This reception service will be part of the Receiver Peppol Integrator Gateway. The documents will then be forwarded to the on-premises Receiver software.

Manage participants

Register a participant

As a Peppol integrator within Digiteal you can send and receive documents for a company. For that you must first register the company as a participant in Digiteal and the Peppol network.
You can get the registration details of one of the companies that you registered using the get participant endpoint.

There are various reasons to register a participant:

• Send document only: In that case, set the "limitedToOutboundTraffic" property to true. You will not receive any documents for this participant. Multiple integrators can send documents for the same participant in Peppol.
• Receive (and optionally send): Only a single access point and a single integrator can receive documents through Peppol for any given participant. This means that if the participant is already registered to another Peppol Access Point or if it is already set to receive documents through another Digiteal Peppol integrator, it must first unregister from that third-party before you will be able to register the participant yourself. You will get the folowing errors when this happens:

Error codes

Register for specific document types

You can choose which document types you wish to receive through Peppol per participant. In the registration call, you can define this in the supportedDocumentTypes. By default, if you did not set "limitedToOutboundTraffic" to true, we will register the participant to receive INVOICE and CREDIT_NOTE.

Automatic registration in the Peppol directory

Digiteal registers all participants in the PEPPOL SMP and directory to define which are the technical capabilities and the associated Peppol Access Points of the participants. This is enough for the participants to receive messages from Peppol.

Extra elements can also be added to complete the registration in the Peppol directory:

• name
• countryCode (otherwise extracted from the participant identifier)
• website
• contactPerson (firstName, lastName, email, phoneNumber, language)
• additionalInformation (ex: "pdf included with the xml would be appreciated")
  We advise you to include those optional fields to provide more visibility to your customers in the Peppol directory.

❗️

Starting on April 30th 2023, the name of the participant will become a required information to further improve the quality of the service we provide.

📘

You can register a participant to only send documents through Peppol by using limitedToOutboundTraffic. You will not be able to receive documents for that participant and the participant will not be registered in the Peppol directory.

Get a participant details

You can get the list of all the participants you registered using the get participants endpoint.
You can get the registration details of one of those participants using the get participant endpoint.

Modify registered document types

You can modify the document types of a registered participant using the add document type endpoint and the remove document type endpoint.
This is the recommended way instead of uregister/register participant to avoid any downtime of the Peppol service for the Participant.

Unregister a participant

You must unregister a participant if you wish to stop sending documents or receiving documents for a company.

Manage documents

Send a document

In order to send a document, you must first register the sender and the recipient must be registered to receive that type of document through Peppol.

You can send a document either just by providing the UBL (recommended) or by providing the full Peppol message document envelope (SBDH).

Generation of headers: If you send the SBDH, we will however re-create it based on the embedded UBL to make sure that it is compliant. Indeed, new versions of the standard lead to changes in the header and as certified Access Point Digiteal needs to send compliant messages (including the headers) over the network. If we notice discrepancies between the data that was provided in the header you sent and the header that we deduced from the UBL, we will contact you to sort this out. We recommend that you use the UBL sending so that all of this is handled automatically.

SDBH message identifier: The sending of the UBL also enables you to define the ID of the message that will be added in the SBDH's InstanceIdentifier. If it is not defined, the identifier of the UBL document will be used. This identifier will be used in the following document fields:

• DeliveryNonDelivery: DeliveryNonDelivery/SenderMessageDetails/UAMessageIdentifier
• MLR & Invoice Response: ApplicationResponse/DocumentResponse/DocumentReference/ID

Document sending is performed synchronously which means that when Digiteal will respond to your call the document will have been successfully sent to the recipient's access point.

Webhook

You can subscribe to a webhook to be notified once the document is delivered to the recipent's access point.

📘

Webhook type

PEPPOL_TRANSPORT_ACK_RECEIVED: The payload document is a Transport ACK containing the confirmation of receipt signed by the receiving access point.

You can subscribe to a webhook to be notified once the document is accepted or refused by the recipent.

📘

Webhook type

PEPPOL_MLR_RECEIVED: The payload document is an MLR provided by the accesss point or the receiver based on technical validations.

📘

Webhook type

PEPPOL_INVOICE_RESPONSE_RECEIVED: The payload document is an Invoice Response provided by the receiver based on business validations.

Webhook payloads are defined in the callback section of the send document endpoint.

The Peppol first approach

The best way to integrate Peppol is to use the Peppol first approach. The rationale behind this approach is that Peppol enables automatic exchange of documents and that this exchange is most profitable when a maximum of entities are participating, just like having a phone is more interesting if most people have one.

The principles of the Peppol first approach are very simple:

• Whenever you have a document to send that is part of an ordering process, first check if the recipient is registered in Peppol. Digiteal provides a free service to perform this check (see Get supported document types). Alternatively, you can do this by calling the Peppol directory. Be sure to check this using all the possible identifiers for the recipient. For exmple, in Belgium, use the company number (type 0208) and the Belgian VAT number (type 9925). The recipient might be registered in only one of those.
• If the recipient is in the registry and supports the type of document you wish to send him, you should send the document using Peppol since the fact that he is on the registry means that this is his preferred way of receiving this type of documents, even if you were previously using another delivery channel.
• If the recipient is not in the registry, you should use a fallback mechanism (email, paper mail,...) that relies on your own stored contact details to send documents to that recipient.

Document validation

The Peppol standard is constantly evolving, changes are documented in the Peppol Billing release notes.

As a certified Peppol Access Point, Digiteal must send validated documents to the network. Before enforcing a new version of the standard we will always give you some time to adapt and comply with the new rules.
When a new validation rule will be enforced, an email will be sent to all the Peppol integrators with a reference to the Peppol documentation detailing the update and the date of enforcement by Digiteal.

Here is the enforcing calendar of the latest validation rules by Digiteal:

To validate your documents, you can look at the online validation of Peppol BIS v3 document or you can include the Peppol BIS validation in your document preparation using for example the PHAX-PHIVE library.

Digiteal provides a webhook for you to get notified for all sent documents that do not comply with the latest warning validations. This allows you to be prepared and react before the rules is enforced in our API.

📘

Webhook type

PEPPOL_FUTURE_VALIDATION_FAILED

The webhook payload is defined in the callback section of the send document endpoint and contains details about the document's validation failure.

Receive a document

In order to receive a document, you must first register the receiver.
You can subscribe to webhooks to be notified of newly published documents.

📘

Webhhook types

PEPPOL_INVOICE_RECEIVED: The payload document is an Invoice.
PEPPOL_CREDIT_NOTE_RECEIVED: The payload document is a Credit Note.

Webhook payloads are defined in the API reference within the register participant endpoint.