Module Peppibar

From Dolibarr ERP CRM Wiki
Jump to navigation Jump to search

Return to developer
documentation index

File Doc dev.png

Return to user
documentation index
File Doc user.png

Informations

Module name Peppibar
Editor / Editeur Dazax.io - https://dazax.io
Download or buy page / Page achat ou téléchargement
Status / Statut / Estado Stable
Prerequisites / Prérequis

Dolibarr min version: 22    Dolibarr max version: 23

Last update date / Date mise à jour fiche / Fecha última actualización 2026-02-20
Note / Nota Requires PHP extensions: curl, dom, json. Requires Dolibarr Invoice module enabled.

Features

Peppibar provides complete PEPPOL (Pan-European Public Procurement OnLine) network integration for electronic invoicing in Dolibarr. It was developed specifically for compliance with the Belgian mandatory structured electronic invoicing law effective January 1, 2026, which requires all VAT-registered Belgian companies to issue and receive structured electronic invoices.

The module uses Peppyrus as its PEPPOL Access Point, which is currently free for users.

Sending customer invoices

  • Automatic UBL 2.1 XML generation from Dolibarr invoices, compliant with Peppol BIS Billing 3.0
  • Multi-level validation before sending (EN 16931, Peppol rules, UBL schema)
  • Secure transmission on the PEPPOL network with status tracking (sent, delivered, failed)
  • Optional automatic sending upon invoice validation
  • Native PEPPOL tab on each customer invoice card
  • Detailed sending reports and audit trail
  • Option to embed the Dolibarr PDF inside the UBL XML (BT-122/BT-125)

Receiving supplier invoices

  • Automatic polling of incoming invoices via CRON (configurable frequency)
  • Intelligent supplier matching by VAT number, Peppol ID, or company name
  • Duplicate detection to prevent multiple imports
  • UBL vs Dolibarr comparison modal for verifying and synchronizing supplier data
  • Draft import workflow for user validation before booking
  • Automatic PDF and UBL XML attachment to imported invoices

PEPPOL participant directory

  • Multi-criteria search: by name, VAT number, or Peppol ID
  • SMP (Service Metadata Publisher) lookup for verifying capabilities
  • Document type capability verification per participant
  • Direct integration: apply lookup results to third-party records in Dolibarr

Belgian accounting exports

  • ZIP generation containing PDFs and UBL files for custom periods
  • Full export history with traceability and re-download

Dashboard and monitoring

  • Real-time statistics (today / this month / this year)
  • Color-coded visual indicators by status (pending, delivered, failed, received)
  • Recent activity log
  • Instant API connection status check

Audit and diagnostics

  • Complete audit log of all actions (sends, receipts, exports)
  • Expert/Debug mode with API connection testing, UBL validation testing, SMP search testing, detailed log viewer with filtering, system information

Supported standards

  • UBL 2.1 - Universal Business Language
  • Peppol BIS Billing 3.0 - PEPPOL billing profile
  • EN 16931 - European electronic invoicing standard
  • PEPPOL Schemes supported: 9925 (Belgian VAT number), 0208 (BCE/KBO enterprise number)

Installation

From the application

  • Download the archive file of module (.zip file)
  • Go on menu Home -> Setup -> Modules -> Deploy external module and submit the file.
  • Module is then visible into list of available modules (Home -> Setup -> Modules) and can be activated.

Manually

  • Download the archive file of module (.zip file)
  • Put the file into the root directory of Dolibarr.
  • Uncompress the archive file, for example with command
unzip modulefile.zip
  • Module is then visible into list of available modules (Home -> Setup -> Modules) and can be activated.

Prerequisites

  • Dolibarr: 22.0.x to 23.0.x
  • PHP: 7.4 or higher (validated on PHP 8.2)
  • PHP extensions: curl, dom, json
  • Dependency: Dolibarr Invoice module (modFacture) must be enabled
  • Peppyrus account: Free registration at https://peppyrus.be

Setup

To use this module, you must first enable it using an administrator account, via the menu option "Home - Setup - Modules".

Choose the tab where the module is listed. Then click on "Activate".

The module is now activated.

If a cog icon appears Cog circle.svg on module thumb or at end of the line of the module, click on it to access the setup page specific to the module.

Setup of Peppyrus API

1) Create a free account at https://peppyrus.be

2) From your Peppyrus dashboard, retrieve your API Key

Setup of Dolibarr module

1) Go to the Peppibar configuration page: Home > Setup > Modules > Peppibar > Configuration (admin only)

2) Fill in the following fields:

  • Environment: Select Test (sandbox) or Production
  • Peppyrus API Key: Paste the API key from your Peppyrus dashboard
  • Your PEPPOL ID: Your company identifier on the PEPPOL network (e.g. your Belgian VAT number)
  • PEPPOL Scheme: Select the scheme matching your PEPPOL ID:
    • 9925 - Belgian VAT number (most common for Belgian companies)
    • 0208 - BCE/KBO enterprise number

3) Click Test API Connection to verify your configuration

Optional settings

Setting Description Default
Auto-send on validation Automatically send invoices via PEPPOL when they are validated in Dolibarr Disabled
Auto-poll received invoices Enable automatic polling for incoming supplier invoices Enabled
Poll frequency Interval in minutes between each poll for received invoices 60 minutes
Embed PDF in UBL Include the Dolibarr-generated PDF inside the UBL XML document (BT-122/BT-125) Disabled
Debug mode Log all API requests and responses for troubleshooting Disabled

Setup of CRON jobs

For automatic receiving and status synchronization, enable the scheduled jobs:

  • Access Home > Setup > Scheduled Jobs
  • Enable the following jobs:
Job Description Recommended frequency
Poll received invoices Polls Peppyrus for new incoming supplier invoices Every hour
Sync received invoice statuses Synchronizes draft/validated state with Dolibarr Every 5 minutes
Sync sent invoice statuses Checks delivery status from Peppyrus Every 6 hours

Setup of third-party PEPPOL identifiers

For each customer you want to send electronic invoices to:

1) Open the third-party card in Dolibarr

2) In the Complementary attributes section, fill in:

  • Default PEPPOL ID: The customer's PEPPOL participant identifier
  • Default PEPPOL Scheme: The scheme code matching their identifier

You can also use the PEPPOL Participant Directory (accessible from the Peppibar menu) to search and automatically fill these fields.

Usage

Sending a customer invoice via PEPPOL

1) Create and validate a customer invoice in Dolibarr as usual

2) Open the invoice card and click on the PEPPOL tab

3) Review the pre-filled PEPPOL information (recipient ID, document type, etc.)

4) Click Send via PEPPOL to transmit the invoice

5) The status will update as the invoice progresses through the PEPPOL network:

  • Pending - Invoice submitted to Peppyrus
  • Delivered - Invoice successfully delivered to the recipient
  • Failed - An error occurred (details available in the audit log)

If Auto-send on validation is enabled, steps 2-4 are performed automatically when you validate the invoice.

Receiving supplier invoices

When automatic polling is enabled (via CRON), incoming invoices are automatically retrieved from Peppyrus.

1) Go to Peppibar > Received Invoices to see all incoming invoices

2) Click on an invoice to review the UBL data and compare it with Dolibarr data

3) The module automatically matches the supplier by VAT number, Peppol ID, or company name

4) Click Import to create a draft supplier invoice in Dolibarr with all data pre-filled

5) Review and validate the draft invoice as usual

Using the PEPPOL participant directory

1) Go to Peppibar > Participant Directory

2) Search by company name, VAT number, or Peppol ID

3) The SMP lookup will show the participant's capabilities (supported document types)

4) Click Apply to third-party to automatically fill the PEPPOL fields on a Dolibarr third-party record

Exporting accounting data (Belgium)

1) Go to Peppibar > Accounting Exports

2) Select a date range for the export

3) Click Generate Export to create a ZIP file containing all PDFs and UBL XML files for the selected period

4) Download the ZIP or access it later from the export history

Using the dashboard

The main Peppibar menu entry opens the dashboard, which provides:

  • Real-time statistics: invoices sent/received today, this month, this year
  • Color-coded status overview: pending, delivered, failed, received
  • Recent activity log
  • Quick API connection status check

Using expert/debug mode

Go to Peppibar > Expert to access diagnostic tools:

  • API Connection Test: Verify the connection to Peppyrus
  • UBL Validation Test: Test UBL generation and validation on a specific invoice
  • SMP Search Test: Test the participant directory lookup
  • Log Viewer: Browse and filter all audit logs
  • System Information: View module version, PHP configuration, and Dolibarr environment details

Permissions

The module provides the following permission levels:

Permission Description
Read Read PEPPOL data, dashboard and logs
Send Send customer invoices via PEPPOL
Receive Receive supplier invoices via PEPPOL
Export Export accounting data

Development and contributions

The development of this module is managed by Dazax.io.

  • Support: peppibar@dazax.io
  • License: GPL-3.0+

Changelog

Version 1.0.1 (2026-02-20)

  • Added option to embed the Dolibarr invoice PDF inside the UBL XML transmitted via PEPPOL (BT-122/BT-125, per Peppol BIS Billing 3.0 section 6.8)
  • New admin configuration setting PEPPIBAR_EMBED_PDF_IN_UBL

Version 1.0.0 (2026-01-31)

  • Initial stable release
  • Full PEPPOL integration: UBL 2.1 generation and multi-level validation (EN 16931, Peppol BIS Billing 3.0, UBL schema)
  • Send customer invoices and receive supplier invoices via PEPPOL network
  • SMP participant directory search
  • Belgian accounting exports (ZIP with PDFs and UBL files)
  • Dashboard with real-time statistics
  • Expert/debug tools
  • CRON jobs for automatic polling and status synchronization
  • Complete audit log
  • Security: encrypted API key storage, permission-based access control
  • Languages: English (en_US) and French (fr_BE)

Troubleshooting

API connection fails

  • Verify your API key is correctly entered in the module configuration
  • Check that your server can reach https://peppyrus.be (no firewall blocking outbound HTTPS)
  • Ensure PHP curl extension is installed and enabled
  • Try enabling Debug mode in the configuration to see detailed API logs

Invoice sending fails validation

  • Check that all mandatory fields are filled on the invoice (customer VAT number, addresses, etc.)
  • Verify the customer's PEPPOL ID and scheme are correctly set on their third-party card
  • Review the validation errors displayed in the PEPPOL tab - they indicate which EN 16931 or Peppol rule failed
  • Common issues: missing VAT number, missing postal address, invalid tax category

Supplier not matched during import

  • The module tries to match by: VAT number, then Peppol ID, then company name
  • If no match is found, you can manually select the supplier during import
  • Ensure your supplier third-party records have their VAT numbers correctly filled in Dolibarr

CRON jobs not running

  • Verify the scheduled jobs are marked as Scheduled in Dolibarr admin
  • Check that the Dolibarr CRON system is properly configured (security key generated, system cron or webcron set up)
  • Review the CRON execution logs in Home > Setup > Scheduled Jobs > Logs
Retrieved from "https://wiki.dolibarr.org/index.php?title=Module_Peppibar&oldid=65424"