Skip to main content

DoliFalco - Peppol Electronic Invoicing via Falco for Dolibarr

DoliFalco is a Dolibarr module that enables sending and receiving electronic invoices via the Peppol network through the Belgian access provider Falco. It integrates directly into your Dolibarr interface and provides full synchronisation with the Falco platform for managing your Peppol invoices.

Introduction

What is Falco?

Falco (falco-app.be) is a Belgian Peppol access provider. The Falco platform enables businesses to send and receive electronic invoices compliant with the Peppol standard. The Expert subscription from Falco includes API access, which is required for using DoliFalco.

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 DoliFalco?

  • Native integration: Send and receive Peppol invoices directly from Dolibarr, without leaving your ERP
  • Falco synchronisation: Direct connection to the Falco API for smooth and automated management
  • Automatic discovery: Automatically look up your customers' Peppol identifiers by VAT number
  • Peppol ID cache: Cache discovered Peppol identifiers to speed up recurring sends
  • Status tracking: Automatic polling to track the status of your sent invoices
  • Invoice reception: Receive and integrate supplier invoices into Dolibarr
  • Reconciliation: Tools for matching Dolibarr invoices with Peppol documents
  • Sandbox mode: Test safely before going to production
  • Multi-entity: Compatible with Dolibarr multi-entity installations

Prerequisites

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

Component Minimum version
Dolibarr 18.0 or higher
PHP 8.0 or higher
PHP Extensions json, curl

You will also need a Falco account with an Expert subscription (required for API access). Visit falco-app.be to create your account and subscribe to the appropriate plan.

Note: DoliFalco is compatible with Dolibarr multi-entity installations. Each entity can have its own Falco connection.

Installation

From the DoliStore

  1. Go to the DoliStore and search for DoliFalco
  2. Purchase the module (EUR 300) 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/dolifalco/

Activation in Dolibarr

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

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

Configuration

DoliFalco configuration is done in several steps accessible through the module's administration pages.

Falco API Connection (setup.php)

Connecting to the Falco API is done in 3 simple steps:

  1. Go to DoliFalco -> Setup
  2. Click Link application to initiate the connection with Falco
  3. The system generates an authorisation link to the Falco platform
  4. Authorise DoliFalco to access your Falco account

Step 2: Enter the API Key

  1. Log in to your Falco account at falco-app.be
  2. Go to your account settings and copy your API key
  3. Paste the API key into the designated field in DoliFalco
  4. Confirm the entry

Tip: API access requires a Falco Expert subscription. If you don't see an API key in your Falco account, check your subscription level.

Step 3: Test the Connection

  1. Click the Test connection button
  2. DoliFalco makes a call to the Falco API to verify that the credentials are correct
  3. A confirmation message is displayed on success
  4. If it fails, check your API key and your Falco subscription

Important: Until the connection is validated, the other module features will not be accessible.

Sending Configuration (sending.php)

In DoliFalco -> Setup -> Sending, configure the sending mode for your invoices:

  • Manual mode: You trigger sending manually from each invoice. This is the recommended mode to start with
  • Automatic mode: Invoices are automatically sent via Peppol as soon as they are validated in Dolibarr

Tip: Start with manual mode to familiarise yourself with the process, then switch to automatic mode once everything is working correctly.

Advanced Options (options.php)

The options page allows you to configure advanced features:

  • Automatic Peppol ID discovery: DoliFalco can automatically look up a customer's Peppol identifier from their VAT number. This feature queries the Peppol directory (SMP/SML) to find the matching identifier
  • Peppol ID cache: Enables caching of discovered Peppol identifiers, avoiding the need to repeat the lookup for each send. The cache significantly speeds up recurring sends to the same customers
  • Status polling: DoliFalco can automatically query the Falco API to update the status of your sent invoices (sent, delivered, error)

Reception Configuration (receiving.php)

In DoliFalco -> Setup -> Reception, configure supplier invoice reception:

  1. Enable Peppol document reception
  2. Configure the processing settings:
    • Automatic creation: Automatically create supplier invoices in Dolibarr upon reception
    • Default third party: Assign a default supplier if the sender is unknown in Dolibarr
    • Automatic reconciliation: Enable automatic matching with existing supplier orders

Usage

Sending an Invoice via Peppol

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 (or automatic discovery must be enabled)
  • Your company information (sender) must be correctly configured

Manual Sending

  1. Open the invoice in Dolibarr
  2. Click on the Peppol tab (or the DoliFalco button)
  3. Review the invoice summary and recipient information
  4. If the customer's Peppol identifier is not filled in, DoliFalco will attempt to discover it automatically (if the option is enabled)
  5. Click Send via Peppol
  6. The system transmits the invoice to Falco, which sends it on the Peppol network

Automatic Sending

When automatic mode is enabled (see Sending Configuration), invoices are automatically sent as soon as they are validated. No manual action is required.

Tracking Sending Statuses

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

Automatic polling (if enabled in the options) updates these statuses regularly without manual intervention.

Receiving Supplier Invoices

  1. Go to DoliFalco -> Reception
  2. The list displays all documents received via Peppol with their status
  3. Click on a document to see details and the associated supplier invoice

When a document is received:

  1. DoliFalco 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

Reconciliation (reconciliation.php)

The reconciliation page allows you to match Dolibarr invoices with Peppol documents:

  1. Go to DoliFalco -> Reconciliation
  2. The page displays sent/received invoices and their correspondence in Dolibarr
  3. You can manually associate unmatched documents
  4. Automatic reconciliation (if enabled) performs these associations based on invoice references

Peppol Discovery (peppol_discovery.php)

The Peppol discovery page allows you to manually look up a company's Peppol identifier:

  1. Go to DoliFalco -> Peppol Discovery
  2. Enter the VAT number of the company you are looking for
  3. DoliFalco queries the Peppol directory and displays the results
  4. You can directly assign the discovered Peppol identifier to the corresponding third party in Dolibarr

Tip: This feature is particularly useful for checking whether a customer or supplier is registered on the Peppol network before attempting to send.

Advanced Options

Sandbox / Production Mode

DoliFalco offers two environments:

  • Sandbox: Test environment to validate your configuration without sending real invoices on the Peppol network. Use this mode for your initial tests
  • Production: Live environment for sending and receiving Peppol invoices. Switch to production only after validating correct operation in sandbox

Important: Invoices sent in sandbox mode are not transmitted to real recipients. They are processed in Falco's test environment.

Multi-Entity

DoliFalco supports Dolibarr multi-entity installations. Each entity can have:

  • Its own Falco API connection
  • Its own sending and reception configuration
  • Its own Peppol ID cache
  • Its own automatic discovery settings

Debug Page (debug.php)

The debug page provides detailed technical information for diagnostics:

  • Logs of API calls to Falco
  • Request and response details
  • Error history
  • Active configuration information

Maintenance and Diagnostics

Maintenance Page (maintenance.php)

Go to DoliFalco -> Maintenance to perform maintenance operations:

  • API connection test: Verify that the connection with Falco is operational
  • Clear Peppol ID cache: Delete cached Peppol identifiers to force a new lookup
  • Prerequisites check: Verify that your PHP environment meets all required conditions
  • Usage statistics: View the number of invoices sent/received and success rates

Logs and Debug

When debug mode is enabled (see Debug page):

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

Common Issues

Sending fails with an API connection error

  • Check your API key in the configuration
  • Test the connection from the maintenance page
  • Verify that your server can reach the Falco API (no firewall blocking)
  • Verify that your Falco Expert subscription is active

The recipient's Peppol ID is not found

  • Verify that the customer's VAT number is correctly filled in Dolibarr
  • Use the Peppol Discovery page to manually look up the identifier
  • Verify that the recipient is registered on the Peppol network

Received invoices don't create third parties

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

An invoice status remains "Pending"

  • Verify that status polling is enabled in the options
  • Check the debug page to identify any errors
  • Test the API connection from the maintenance page

Error in sandbox mode

  • Verify that you are using Falco's sandbox credentials and not production credentials
  • Consult the Falco documentation for sandbox mode limitations

FAQ

What is Falco?

Falco is a Belgian Peppol access provider available at falco-app.be. It offers different subscription plans for sending and receiving Peppol invoices. The Expert subscription is required to use DoliFalco as it includes the API access needed for synchronisation.

How much does DoliFalco cost?

The DoliFalco module is available for EUR 300 on the DoliStore. This price does not include the Falco subscription, which is billed separately by Falco.

Which countries are supported?

DoliFalco works in all countries connected to the Peppol network via Falco, including most EU countries, the United Kingdom and other Peppol network member countries.

Does DoliFalco work with multi-entity?

Yes, DoliFalco supports Dolibarr multi-entity installations. Each entity can have its own independent configuration and Falco connection.

What is the difference between sandbox and production mode?

Sandbox mode is a test environment provided by Falco. Invoices sent in sandbox are not transmitted to real recipients. Production mode sends invoices on the real Peppol network. It is recommended to always test in sandbox before switching to production.

Does automatic Peppol ID discovery work for all countries?

Automatic discovery queries the Peppol directory (SMP/SML) and works for all companies registered on the Peppol network, regardless of their country. However, not all companies are registered on Peppol yet.

How do I update the module?

  1. Download the new version from the DoliStore
  2. Replace the files in htdocs/custom/dolifalco/
  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
  • Falco documentation: falco-app.be for questions about your Falco account and subscription