Aller au contenu principal

EMPeppol - Facturation électronique Peppol pour Dolibarr

EMPeppol est un module Dolibarr qui permet d'envoyer et de recevoir des factures électroniques via le réseau Peppol (Pan-European Public Procurement OnLine). Il s'intègre directement dans votre interface Dolibarr et communique avec le réseau Peppol via le fournisseur d'accès Peppyrus.

Introduction

Qu'est-ce que Peppol ?

Peppol est un réseau international standardisé pour l'échange de documents commerciaux électroniques (factures, notes de crédit, etc.). Il est utilisé dans plus de 30 pays et est obligatoire pour la facturation électronique B2G (Business-to-Government) dans de nombreux pays européens, dont la Belgique.

Pourquoi EMPeppol ?

  • Conformité légale : Répondez aux obligations de facturation électronique B2G et B2B
  • Intégration native : Envoyez vos factures Peppol directement depuis Dolibarr, sans logiciel tiers
  • Réception automatique : Recevez les factures fournisseurs et créez automatiquement les écritures dans Dolibarr
  • Mapping TVA intelligent : Configurez la correspondance entre vos taux TVA Dolibarr et les catégories Peppol (VATEX)
  • Assistant de configuration : Un wizard vous guide pas à pas lors de la première installation

Prérequis

Avant d'installer EMPeppol, vérifiez que votre environnement remplit les conditions suivantes :

Élément Version minimum
Dolibarr 18.0 ou supérieur
PHP 8.1 ou supérieur
Extensions PHP soap, xml, json, curl

Vous aurez également besoin d'un compte Peppyrus (le fournisseur d'accès Peppol utilisé par EMPeppol). Les informations de connexion (clé API) vous seront fournies lors de la souscription au service.

Note : EMPeppol est compatible avec les installations multi-entités de Dolibarr.

Installation

Depuis le DoliStore

  1. Rendez-vous sur le DoliStore et recherchez EMPeppol
  2. Achetez le module et téléchargez l'archive ZIP
  3. Décompressez l'archive dans le dossier htdocs/custom/ de votre installation Dolibarr
  4. Le dossier final doit être htdocs/custom/empeppol/

Activation dans Dolibarr

  1. Connectez-vous à Dolibarr en tant qu'administrateur
  2. Allez dans Accueil → Configuration → Modules/Applications
  3. Recherchez "EMPeppol" dans la liste des modules
  4. Cliquez sur le bouton Activer

Une fois le module activé, un nouveau menu EMPeppol apparaît dans votre barre de navigation.

Configuration initiale

Lors du premier accès au module, un assistant de configuration (wizard) vous guide à travers les étapes essentielles.

Étape 1 : Clé API Peppyrus

  1. Accédez à EMPeppol → Configuration
  2. Le wizard démarre automatiquement
  3. Saisissez votre clé API Peppyrus (fournie lors de votre inscription au service)
  4. Cliquez sur Valider pour tester la connexion

Astuce : Si vous n'avez pas encore de clé API, contactez le support Peppyrus ou rendez-vous sur leur site pour en obtenir une.

Étape 2 : Sélection du participant

Une fois la clé API validée, le wizard affiche la liste des participants (entités/entreprises) associés à votre compte Peppyrus.

  1. Sélectionnez le participant correspondant à votre société
  2. Le système configure automatiquement votre identifiant Peppol (numéro de participant)
  3. Validez pour passer à l'étape suivante

Étape 3 : Configuration de l'expéditeur

  1. Vérifiez les informations de votre société (nom, adresse, numéro TVA)
  2. Ces informations seront utilisées comme expéditeur (sender) dans les documents Peppol
  3. Corrigez si nécessaire, puis validez

Important : Les informations de l'expéditeur doivent correspondre exactement à celles enregistrées auprès de Peppyrus, sinon l'envoi de factures échouera.

Étape 4 : Finalisation

Le wizard effectue un test de connectivité final et confirme que la configuration est opérationnelle. Vous pouvez maintenant utiliser EMPeppol pour envoyer et recevoir des factures.

Envoi de factures

Préparer une facture pour l'envoi

Pour qu'une facture puisse être envoyée via Peppol, elle doit remplir certaines conditions :

  • La facture doit être validée (statut "Non payée" ou supérieur)
  • Le client doit avoir un identifiant Peppol renseigné (numéro d'entreprise, GLN, etc.)
  • Les lignes de facture doivent avoir des taux TVA configurés dans le mapping VATEX

Envoyer une facture

  1. Ouvrez la facture dans Dolibarr
  2. Cliquez sur l'onglet Peppol
  3. Vérifiez le résumé de la facture et les informations du destinataire
  4. Cliquez sur Envoyer via Peppol
  5. Le système génère le document UBL, l'envoie via Peppyrus et affiche le statut d'envoi

Statuts d'envoi

Statut Description
En attente La facture est prête mais n'a pas encore été envoyée
Envoyée La facture a été transmise avec succès au réseau Peppol
Délivrée Le destinataire a accusé réception de la facture
Erreur L'envoi a échoué (voir le message d'erreur pour les détails)

Configuration d'envoi

Dans EMPeppol → Configuration → Envoi, vous pouvez paramétrer :

  • Envoi automatique : Envoyer automatiquement les factures dès leur validation
  • Notifications : Recevoir un email de confirmation après chaque envoi
  • Format UBL : Choisir la version du format UBL (BIS Billing 3.0 par défaut)

Réception de documents

EMPeppol peut recevoir des factures fournisseurs entrantes via le réseau Peppol et les intégrer dans Dolibarr.

Configurer la réception

  1. Allez dans EMPeppol → Configuration → Réception
  2. Activez la réception de documents
  3. Configurez les paramètres :
    • Création automatique : Créer automatiquement les factures fournisseurs dans Dolibarr
    • Tiers par défaut : Associer un tiers fournisseur par défaut si l'expéditeur est inconnu
    • Validation automatique : Valider automatiquement les factures reçues (optionnel)

Consulter les documents reçus

  1. Accédez à EMPeppol → Réception
  2. La liste affiche tous les documents reçus avec leur statut
  3. Cliquez sur un document pour voir les détails et la facture fournisseur associée

Traitement des documents

Lorsqu'un document est reçu :

  1. EMPeppol vérifie si l'expéditeur correspond à un tiers fournisseur existant dans Dolibarr
  2. Si oui, une facture fournisseur est créée et liée au tiers
  3. Si non, le document est placé en attente pour association manuelle (ou utilise le tiers par défaut)
  4. Les lignes de facture sont créées avec les montants, taux TVA et descriptions du document Peppol

Mapping TVA (VATEX)

Le mapping TVA est essentiel pour la conformité Peppol. Il établit la correspondance entre vos taux TVA Dolibarr et les catégories d'exonération TVA Peppol (codes VATEX).

Accéder au mapping

  1. Allez dans EMPeppol → Configuration → Mapping TVA
  2. La page affiche tous vos taux TVA Dolibarr et leur correspondance Peppol

Configurer le mapping

Pour chaque taux TVA Dolibarr, vous devez définir :

  • Code TVA Peppol : Le code TVA standard (S = Standard, Z = Zero rated, E = Exempt, etc.)
  • Code VATEX : Le code d'exonération spécifique si applicable (par exemple vatex-eu-ae pour autoliquidation)

Codes TVA courants

Code Description Utilisation
S Standard rate Taux TVA standard (21%, 6%, etc.)
Z Zero rated Taux à 0% avec droit à déduction
E Exempt Exonéré de TVA
AE Reverse charge Autoliquidation (intracommunautaire)
G Export Exportation hors UE

Conseil : Assurez-vous de mapper tous vos taux TVA utilisés avant d'envoyer des factures. Un taux non mappé provoquera une erreur à l'envoi.

Options avancées

La page EMPeppol → Configuration → Options contient des paramètres supplémentaires pour affiner le comportement du module.

Options disponibles

  • Mode debug : Activer les logs détaillés pour le diagnostic (voir section Maintenance)
  • Timeout API : Durée maximale d'attente pour les appels à l'API Peppyrus (défaut : 30 secondes)
  • Stockage des documents : Conserver une copie locale des documents UBL envoyés/reçus
  • Format de numérotation : Personnaliser le préfixe des références Peppol
  • Webhook : Configurer une URL de callback pour les notifications de réception

Maintenance et diagnostic

La page de maintenance vous permet de vérifier l'état de votre installation et de diagnostiquer les problèmes éventuels.

Vérification des prérequis

Accédez à EMPeppol → Maintenance pour lancer une vérification automatique :

  • Connexion API : Test de connectivité avec Peppyrus
  • Extensions PHP : Vérification des extensions requises (soap, xml, curl)
  • Configuration : Validation de la configuration du module
  • Certificats : Vérification des certificats SSL pour la communication sécurisée

Logs et debug

Quand le mode debug est activé (voir Options avancées) :

  1. Les logs détaillés sont écrits dans le répertoire documents/empeppol/logs/ de Dolibarr
  2. Chaque envoi/réception génère un fichier de log avec les requêtes/réponses API
  3. Les documents UBL générés sont conservés pour inspection

Problèmes courants

L'envoi échoue avec "Invalid participant"

  • Vérifiez que l'identifiant Peppol du destinataire est correct
  • Assurez-vous que le destinataire est bien enregistré sur le réseau Peppol

Erreur "VATEX mapping missing"

  • Un taux TVA utilisé dans la facture n'a pas de correspondance Peppol
  • Allez dans le mapping TVA et configurez le taux manquant

Erreur de connexion API

  • Vérifiez votre clé API dans la configuration
  • Testez la connectivité depuis la page Maintenance
  • Vérifiez que votre serveur peut accéder à l'API Peppyrus (pas de blocage pare-feu)

Les factures reçues ne créent pas de tiers

  • Vérifiez la configuration de réception (création automatique activée ?)
  • Vérifiez qu'un tiers par défaut est défini si souhaité

FAQ

Quels pays sont supportés ?

EMPeppol fonctionne dans tous les pays connectés au réseau Peppol, incluant la plupart des pays de l'UE, le Royaume-Uni, Singapour, l'Australie, la Nouvelle-Zélande et d'autres.

EMPeppol fonctionne-t-il en multi-entité ?

Oui, EMPeppol supporte les installations multi-entités de Dolibarr. Chaque entité peut avoir sa propre configuration, clé API et participant Peppol.

Quel format de facture est utilisé ?

EMPeppol utilise le format UBL 2.1 conforme au profil Peppol BIS Billing 3.0, le standard européen de facturation électronique.

Peut-on envoyer des avoirs (notes de crédit) ?

Oui, EMPeppol supporte l'envoi de notes de crédit via Peppol. Le processus est identique à l'envoi de factures.

Comment mettre à jour le module ?

  1. Téléchargez la nouvelle version depuis le DoliStore
  2. Remplacez les fichiers dans htdocs/custom/empeppol/
  3. Accédez à Dolibarr, le module détectera la mise à jour et appliquera les migrations nécessaires

Où trouver de l'aide ?

  • Support E-dem : Contactez-nous pour toute question technique
  • Documentation Peppol : peppol.eu pour les spécifications du réseau
  • Documentation Peppyrus : Contactez votre fournisseur d'accès pour les questions relatives à l'API