Skip to main content

EMPeppol - Peppol Electronic Invoicing for Dolibarr

EMPeppol is a Dolibarr module that enables sending and receiving electronic invoices via the Peppol (Pan-European Public Procurement OnLine) network. It integrates directly into your Dolibarr interface and communicates with the Peppol network through the Peppyrus access provider.

Introduction

What is Peppol?

Peppol is a standardised international network for exchanging electronic business documents (invoices, credit notes, etc.). It is used in over 30 countries and is mandatory for B2G (Business-to-Government) electronic invoicing in many European countries, including Belgium.

Why EMPeppol?

  • Legal compliance: Meet B2G and B2B electronic invoicing obligations
  • Native integration: Send Peppol invoices directly from Dolibarr, without third-party software
  • Automatic reception: Receive supplier invoices and automatically create entries in Dolibarr
  • Smart VAT mapping: Configure the correspondence between your Dolibarr VAT rates and Peppol categories (VATEX)
  • Setup wizard: A step-by-step wizard guides you through the initial installation

Prerequisites

Before installing EMPeppol, make sure your environment meets the following requirements:

Component Minimum version
Dolibarr 18.0 or higher
PHP 8.1 or higher
PHP Extensions soap, xml, json, curl

You will also need a Peppyrus account (the Peppol access provider used by EMPeppol). Connection credentials (API key) will be provided when you subscribe to the service.

Note: EMPeppol is compatible with Dolibarr multi-entity installations.

Installation

From the DoliStore

  1. Go to the DoliStore and search for EMPeppol
  2. Purchase the module and download the ZIP archive
  3. Extract the archive into the htdocs/custom/ folder of your Dolibarr installation
  4. The final folder should be htdocs/custom/empeppol/

Activation in Dolibarr

  1. Log in to Dolibarr as an administrator
  2. Go to Home → Setup → Modules/Applications
  3. Search for "EMPeppol" in the modules list
  4. Click the Enable button

Once the module is activated, a new EMPeppol menu appears in your navigation bar.

Initial Configuration

On first access to the module, a setup wizard guides you through the essential steps.

Step 1: Peppyrus API Key

  1. Go to EMPeppol → Setup
  2. The wizard starts automatically
  3. Enter your Peppyrus API key (provided when you registered for the service)
  4. Click Validate to test the connection

Tip: If you don't have an API key yet, contact Peppyrus support or visit their website to obtain one.

Step 2: Participant Selection

Once the API key is validated, the wizard displays the list of participants (entities/companies) associated with your Peppyrus account.

  1. Select the participant matching your company
  2. The system automatically configures your Peppol identifier (participant number)
  3. Confirm to proceed to the next step

Step 3: Sender Configuration

  1. Verify your company information (name, address, VAT number)
  2. This information will be used as the sender in Peppol documents
  3. Correct if necessary, then confirm

Important: The sender information must exactly match what is registered with Peppyrus, otherwise invoice sending will fail.

Step 4: Finalisation

The wizard performs a final connectivity test and confirms that the configuration is operational. You can now use EMPeppol to send and receive invoices.

Sending Invoices

Preparing an Invoice for Sending

For an invoice to be sent via Peppol, it must meet certain conditions:

  • The invoice must be validated (status "Unpaid" or higher)
  • The customer must have a Peppol identifier filled in (company number, GLN, etc.)
  • Invoice lines must have VAT rates configured in the VATEX mapping

Sending an Invoice

  1. Open the invoice in Dolibarr
  2. Click on the Peppol tab
  3. Review the invoice summary and recipient information
  4. Click Send via Peppol
  5. The system generates the UBL document, sends it via Peppyrus and displays the sending status

Sending Statuses

Status Description
Pending The invoice is ready but has not yet been sent
Sent The invoice has been successfully transmitted to the Peppol network
Delivered The recipient has acknowledged receipt of the invoice
Error Sending failed (see the error message for details)

Sending Configuration

In EMPeppol → Setup → Sending, you can configure:

  • Automatic sending: Automatically send invoices upon validation
  • Notifications: Receive a confirmation email after each sending
  • UBL format: Choose the UBL format version (BIS Billing 3.0 by default)

Receiving Documents

EMPeppol can receive incoming supplier invoices via the Peppol network and integrate them into Dolibarr.

Configuring Reception

  1. Go to EMPeppol → Setup → Reception
  2. Enable document reception
  3. Configure the settings:
    • Automatic creation: Automatically create supplier invoices in Dolibarr
    • Default third party: Assign a default supplier if the sender is unknown
    • Automatic validation: Automatically validate received invoices (optional)

Viewing Received Documents

  1. Go to EMPeppol → Reception
  2. The list displays all received documents with their status
  3. Click on a document to see details and the associated supplier invoice

Document Processing

When a document is received:

  1. EMPeppol checks whether the sender matches an existing supplier third party in Dolibarr
  2. If yes, a supplier invoice is created and linked to the third party
  3. If not, the document is placed on hold for manual association (or uses the default third party)
  4. Invoice lines are created with the amounts, VAT rates and descriptions from the Peppol document

VAT Mapping (VATEX)

VAT mapping is essential for Peppol compliance. It establishes the correspondence between your Dolibarr VAT rates and Peppol VAT exemption categories (VATEX codes).

Accessing the Mapping

  1. Go to EMPeppol → Setup → VAT Mapping
  2. The page displays all your Dolibarr VAT rates and their Peppol correspondence

Configuring the Mapping

For each Dolibarr VAT rate, you need to define:

  • Peppol VAT code: The standard VAT code (S = Standard, Z = Zero rated, E = Exempt, etc.)
  • VATEX code: The specific exemption code if applicable (e.g. vatex-eu-ae for reverse charge)

Common VAT Codes

Code Description Usage
S Standard rate Standard VAT rate (21%, 6%, etc.)
Z Zero rated 0% rate with right to deduct
E Exempt VAT exempt
AE Reverse charge Reverse charge (intra-community)
G Export Export outside the EU

Tip: Make sure to map all your VAT rates in use before sending invoices. An unmapped rate will cause an error when sending.

Advanced Options

The EMPeppol → Setup → Options page contains additional settings to fine-tune the module's behaviour.

Available Options

  • Debug mode: Enable detailed logging for diagnostics (see Maintenance section)
  • API timeout: Maximum wait time for Peppyrus API calls (default: 30 seconds)
  • Document storage: Keep a local copy of sent/received UBL documents
  • Numbering format: Customise the Peppol reference prefix
  • Webhook: Configure a callback URL for reception notifications

Maintenance and Diagnostics

The maintenance page allows you to check the status of your installation and diagnose any issues.

Checking Prerequisites

Go to EMPeppol → Maintenance to run an automatic check:

  • API connection: Connectivity test with Peppyrus
  • PHP extensions: Verification of required extensions (soap, xml, curl)
  • Configuration: Module configuration validation
  • Certificates: SSL certificate verification for secure communication

Logs and Debug

When debug mode is enabled (see Advanced Options):

  1. Detailed logs are written to the documents/empeppol/logs/ directory in Dolibarr
  2. Each send/receive operation generates a log file with API requests/responses
  3. Generated UBL documents are preserved for inspection

Common Issues

Sending fails with "Invalid participant"

  • Verify that the recipient's Peppol identifier is correct
  • Make sure the recipient is registered on the Peppol network

"VATEX mapping missing" error

  • A VAT rate used in the invoice has no Peppol correspondence
  • Go to VAT mapping and configure the missing rate

API connection error

  • Check your API key in the configuration
  • Test connectivity from the Maintenance page
  • Verify that your server can reach the Peppyrus API (no firewall blocking)

Received invoices don't create third parties

  • Check the reception configuration (automatic creation enabled?)
  • Verify that a default third party is set if desired

FAQ

Which countries are supported?

EMPeppol works in all countries connected to the Peppol network, including most EU countries, the United Kingdom, Singapore, Australia, New Zealand and others.

Does EMPeppol work with multi-entity?

Yes, EMPeppol supports Dolibarr multi-entity installations. Each entity can have its own configuration, API key and Peppol participant.

What invoice format is used?

EMPeppol uses the UBL 2.1 format compliant with the Peppol BIS Billing 3.0 profile, the European standard for electronic invoicing.

Can I send credit notes?

Yes, EMPeppol supports sending credit notes via Peppol. The process is identical to sending invoices.

How do I update the module?

  1. Download the new version from the DoliStore
  2. Replace the files in htdocs/custom/empeppol/
  3. Access Dolibarr — the module will detect the update and apply necessary migrations

Where can I find help?

  • E-dem support: Contact us for any technical questions
  • Peppol documentation: peppol.eu for network specifications
  • Peppyrus documentation: Contact your access provider for API-related questions