📍 Article principal : Dolibarr 23 ERP/CRM pour TPE-PME francophone. Ce tutoriel décrit la mise en conformité FNE pour une TPE-PME ivoirienne qui veut continuer à émettre légalement des factures à ses clients professionnels.
La Direction Générale des Impôts (DGI) ivoirienne a généralisé en 2024-2025 la Facture Normalisée Électronique (FNE) — une facture qui n’a de valeur fiscale qu’après transmission, validation et marquage par le système central de la DGI. Concrètement, une facture émise hors FNE n’est plus déductible pour le client professionnel et expose l’émetteur à des sanctions. La conformité passe par trois éléments : un certificat fiscal délivré par la DGI, un connecteur logiciel qui transmet chaque facture en XML, et l’impression d’un QR code et d’un numéro fiscal sur la facture finale. Ce tutoriel équipe Dolibarr 23 d’un module FNE complet, conforme aux spécifications publiées par la DGI.
Prérequis
- Instance Dolibarr 23 (voir tutoriel installation)
- Entreprise immatriculée en Côte d’Ivoire avec numéro CC (Compte Contribuable) actif
- Certificat fiscal FNE obtenu auprès de la DGI (procédure en agence ou en ligne sur e-impôts)
- Accès aux endpoints API FNE de production (URL et identifiants fournis par la DGI à la délivrance du certificat)
- Niveau : avancé (PHP, XML, signature numérique)
- Temps estimé : 6 à 8 heures pour un développeur expérimenté
Étape 1 — Obtenir le certificat fiscal FNE
La première démarche est administrative. Le dirigeant ou le responsable comptable se connecte sur le portail e-impôts de la DGI Côte d’Ivoire et dépose une demande FNE depuis l’espace contribuable. Les pièces nécessaires : copie du registre de commerce, attestation de régularité fiscale (à jour des déclarations), pièce d’identité du gérant. Le délai de délivrance varie de quelques heures à plusieurs jours selon la charge de la DGI.
Le certificat délivré contient une clé publique X.509, une clé privée chiffrée par mot de passe, un identifiant FNE entreprise, l’URL de l’API de production et l’URL de l’API de test. Stocker ces éléments dans un coffre-fort numérique (Bitwarden, Vaultwarden self-hosted) et créer une copie chiffrée de sauvegarde sur clé USB conservée hors site. La perte du certificat entraîne une nouvelle procédure de délivrance et une rupture de service de plusieurs jours.
Étape 2 — Installer le certificat dans Dolibarr
Le certificat se présente généralement sous forme d’un fichier .p12 (PKCS#12) qui contient la clé privée et le certificat public. Le déposer dans /var/www/dolibarr/documents/fne/ avec des permissions restrictives, et l’exposer aux variables d’environnement Coolify pour qu’il soit lisible par PHP.
mkdir -p /var/www/dolibarr/documents/fne mv certif_fne_masociete.p12 /var/www/dolibarr/documents/fne/ chown www-data:www-data /var/www/dolibarr/documents/fne/certif_fne_masociete.p12 chmod 0600 /var/www/dolibarr/documents/fne/certif_fne_masociete.p12 # Variables Coolify FNE_CERT_PATH=/var/www/dolibarr/documents/fne/certif_fne_masociete.p12 FNE_CERT_PASSWORD=<mot-de-passe-fourni-par-DGI> FNE_API_URL=https://api.fne.dgi.gouv.ci/v1 FNE_ENTITY_ID=<identifiant-entreprise>
Le mot de passe ne doit jamais apparaître dans un fichier versionné Git. Utiliser le coffre des secrets Coolify ou un fichier .env exclu de Git. Pour PHP, charger le certificat via openssl_pkcs12_read :
$pkcs12 = file_get_contents(getenv('FNE_CERT_PATH'));
openssl_pkcs12_read($pkcs12, $certs, getenv('FNE_CERT_PASSWORD'));
$privateKey = $certs['pkey'];
$publicCert = $certs['cert'];
// $privateKey et $publicCert sont maintenant utilisables pour signer le XML
Étape 3 — Construire le XML FNE
La DGI publie une spécification XSD précise du format XML attendu. Le document contient l’identité du fournisseur (CC, raison sociale, adresse), l’identité du client (CC ou matricule consommateur final), le détail des lignes de facture (désignation, quantité, prix HT, taux de TVA, total HT, total TVA, total TTC), la date d’émission, le mode de paiement, et un identifiant unique de facture côté entreprise.
Une fonction Dolibarr fne_build_xml($facture) dans le module construit le XML à partir de l’objet Facture chargé. Le code parcourt les lignes via $facture->lines, calcule les totaux par taux de TVA, ajoute les éventuelles remises et retient à la source. Le résultat est un fichier XML conforme au schéma XSD FNE qu’on valide avant transmission :
$xml = new DOMDocument('1.0', 'UTF-8');
$xml->loadXML(fne_build_xml($facture));
if (!$xml->schemaValidate('/var/www/dolibarr/documents/fne/fne-1.0.xsd')) {
// log et notifier l'admin, ne pas envoyer
fne_log('XML invalide pour facture '.$facture->ref);
return false;
}
Étape 4 — Signer numériquement et transmettre
La DGI exige une signature XML-DSig (RFC 3275) du document avant transmission, garantissant que la facture vient bien du contribuable identifié et n’a pas été altérée en transit. La librairie PHP robrichards/xmlseclibs est la référence pour cette opération.
composer require robrichards/xmlseclibs // Dans le module Dolibarr use RobRichards\XMLSecLibs\XMLSecurityDSig; use RobRichards\XMLSecLibs\XMLSecurityKey; $objDSig = new XMLSecurityDSig(); $objDSig->setCanonicalMethod(XMLSecurityDSig::EXC_C14N); $objDSig->addReference($xml, XMLSecurityDSig::SHA256, ['http://www.w3.org/2000/09/xmldsig#enveloped-signature']); $objKey = new XMLSecurityKey(XMLSecurityKey::RSA_SHA256, ['type' => 'private']); $objKey->loadKey($privateKey); $objDSig->sign($objKey); $objDSig->add509Cert($publicCert); $objDSig->appendSignature($xml->documentElement); $signedXml = $xml->saveXML();
Transmettre le XML signé à l’API FNE par POST HTTPS. La réponse contient le numéro fiscal unique attribué par la DGI (NUF) et l’URL du QR code de validation. Stocker ces deux éléments dans des champs extra de la facture Dolibarr.
$ch = curl_init(getenv('FNE_API_URL').'/invoices/submit');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $signedXml,
CURLOPT_HTTPHEADER => [
'Content-Type: application/xml',
'X-FNE-Entity-Id: '.getenv('FNE_ENTITY_ID'),
],
CURLOPT_TIMEOUT => 30,
]);
$response = simplexml_load_string(curl_exec($ch));
$facture->array_options['options_fne_nuf'] = (string)$response->NUF;
$facture->array_options['options_fne_qr_url'] = (string)$response->QRCodeURL;
$facture->update($user);
En cas d’erreur (XML invalide, certificat expiré, CC client inexistant), l’API renvoie un code d’erreur précis. Logger systématiquement chaque appel pour faciliter le dépannage avec le support DGI. La facture ne doit jamais être imprimée ni envoyée au client tant que le NUF n’est pas reçu — c’est la règle d’or de la conformité FNE.
Étape 5 — Imprimer la facture finale avec QR code et NUF
Modifier le template ODT/PDF de facture Dolibarr pour ajouter le bloc FNE en bas du document : numéro fiscal NUF en clair, date de validation par la DGI, QR code généré à partir de l’URL de validation. Le client professionnel scanne ce QR code et accède au site DGI qui confirme l’authenticité de la facture en moins d’une seconde.
Le template ODT par défaut azur de Dolibarr accepte des balises de remplacement : {options_fne_nuf}, {options_fne_qr_url}. Pour intégrer le QR code en image, utiliser un hook printPdfFooter qui injecte le PNG généré à la volée. La facture finale est ainsi techniquement valide, fiscalement opposable et conforme aux contrôles DGI.
Erreurs fréquentes
| Erreur | Cause | Solution |
|---|---|---|
| Erreur « CC client invalide » | Saisie incomplète ou client non immatriculé | Vérifier le CC dans l’annuaire DGI, basculer en mode « consommateur final » si non professionnel |
| Signature XML rejetée | Mauvaise méthode de canonicalisation ou clé expirée | Utiliser EXC_C14N strict, vérifier la date d’expiration du certificat |
| Timeout API à la transmission | Charge serveur DGI ou réseau instable | Implémenter une file d’attente avec retry exponentiel (1min, 5min, 30min, 2h) |
| Total TTC différent de la somme des lignes | Arrondis sur la TVA non appliqués sur chaque ligne | Suivre la spec DGI : arrondir TVA par ligne, jamais sur le total |
Adaptation au contexte ouest-africain
Au Sénégal, la DGID prépare une plateforme e-Facture similaire — anticiper en gardant l’architecture FNE modulaire pour basculer rapidement quand la spécification sera publiée. Au Mali, la DGI étudie un projet équivalent à horizon 2027. La meilleure pratique consiste donc à structurer le code avec un adaptateur par pays : une interface PHP commune FacturationFiscale implémentée par FNECoteIvoire, EFactureSenegal, ETaxMali selon les contextes.
Numéro CC client et matricule consommateur final
La FNE distingue deux types de clients qui se traitent différemment dans le XML. Pour un client professionnel ivoirien, le champ obligatoire est le numéro CC (Compte Contribuable) à 10 caractères. Le module doit valider ce numéro avant la transmission : longueur exacte, caractères alphanumériques, présence dans l’annuaire DGI publié sur e-impôts. Une fonction de validation côté Dolibarr consulte une fois par jour l’annuaire DGI (mise à jour incrémentale) et marque les CC inactifs ou suspendus pour éviter les rejets API.
Pour un client particulier ou un professionnel non immatriculé, basculer en mode consommateur final qui accepte une pièce d’identité ou un simple nom-prénom. La FNE traite ces factures différemment : la TVA est facturée mais non récupérable côté client, et la facture finale ne porte pas de QR de validation pour l’acheteur (qui n’en a pas l’usage). Configurer dans Dolibarr deux modèles de facture distincts : FNE-Pro et FNE-Particulier, choisis automatiquement selon la présence ou non d’un CC sur la fiche tiers.
Avoirs et factures rectificatives
La spécification FNE encadre strictement les corrections. Une facture transmise et validée ne peut pas être modifiée — il faut émettre un avoir (note de crédit) qui annule totalement ou partiellement la facture initiale, puis le cas échéant une nouvelle facture corrigée. Le module Dolibarr doit gérer ce workflow avec rigueur : le bouton Annuler sur une facture FNE validée déclenche la création automatique d’un avoir transmis à la FNE, qui reçoit son propre NUF et son QR code de validation.
Pour la traçabilité fiscale, l’avoir doit explicitement référencer le NUF de la facture initiale dans le champ XML InvoiceReference. Sans cette référence, la DGI peut requalifier l’opération en facture indépendante et taxer deux fois le même flux. Implémenter dans le module une vérification automatique avant transmission : tout avoir doit avoir un NUF de référence valide, sinon la transmission est bloquée et l’opérateur reçoit un message d’erreur explicite.
Performance et pic de fin de mois
La DGI subit des pics de charge significatifs en fin de mois quand toutes les PME ivoiriennes envoient leur facturation mensuelle dans la dernière semaine. Pour éviter les timeouts et les rejets en cascade, le module doit implémenter une file d’attente locale avec retry intelligent. Toute facture validée passe d’abord par un statut FNE-Pending, est insérée dans une table de queue, et un worker en arrière-plan tente la transmission API toutes les 30 secondes avec un délai exponentiel en cas d’échec.
Cette architecture asynchrone protège l’expérience utilisateur (le commercial qui valide la facture n’attend jamais la réponse API) et garantit que la facture finit par être transmise même si la DGI est temporairement injoignable. Surveiller la taille de la queue : si elle dépasse 50 factures en attente, alerter l’admin. Cela peut signaler une indisponibilité prolongée de la DGI ou un problème de certificat à corriger.
Conformité et bonne foi en cas de contrôle
Une PME peut être contrôlée par la DGI sur sa conformité FNE. Cinq pièces à pouvoir présenter immédiatement. Premièrement, le certificat fiscal en cours de validité avec sa date d’échéance. Deuxièmement, les logs de transmission des 12 derniers mois : chaque facture émise doit pouvoir être retrouvée avec son NUF, sa date de validation et le timestamp de l’API. Troisièmement, la liste des avoirs avec référence à la facture annulée. Quatrièmement, les rapports d’incidents (transmissions échouées, retransmissions, anomalies) avec actions correctives prises. Cinquièmement, le journal des mises à jour du module (versions installées, dates de déploiement, tests de non-régression).
L’absence d’une de ces pièces ne suffit pas à entraîner une sanction si la PME démontre sa bonne foi (volume cohérent de factures, paiements de TVA réguliers, conformité globale). Mais accumuler les manquements documentaires expose à des redressements significatifs. La règle de prudence : garder ces pièces en double localement et sur un cloud sécurisé, avec rotation annuelle.
Tests automatisés du module FNE
Un module fiscal critique mérite une suite de tests automatisés qui valide chaque scénario à chaque mise à jour. Mettre en place avec PHPUnit (déjà installé avec Dolibarr) une batterie de tests qui couvre : génération XML conforme XSD pour facture pro, idem pour particulier, signature XMLDSig vérifiable, transmission en mode test API, gestion d’un avoir avec référence, retry sur timeout simulé, validation d’un CC connu, rejet d’un CC invalide. Lancer cette suite à chaque déploiement dans le pipeline CI Coolify. Une régression silencieuse sur la génération XML peut passer inaperçue plusieurs jours et accumuler des dizaines de factures non-conformes — les tests automatisés bloquent ce scénario à la racine.
Renouvellement annuel du certificat fiscal
Le certificat FNE délivré par la DGI a une durée de validité limitée — typiquement un an. Sa rupture entraîne une interruption immédiate de la transmission, donc une rupture commerciale directe pour une PME ivoirienne. Anticiper le renouvellement est la responsabilité de l’admin technique et du DPO. Mettre en place dans Dolibarr une alerte automatique 60 jours avant l’expiration : tâche planifiée qui lit le certificat, calcule la date d’expiration, et envoie un e-mail à la direction et au prestataire technique pour déclencher la procédure de renouvellement.
La procédure de renouvellement se fait en agence DGI avec les pièces actualisées. Le nouveau certificat remplace l’ancien : le déposer au même chemin, mettre à jour le mot de passe en variable Coolify, redémarrer le conteneur Dolibarr. Tester immédiatement avec une facture de contrôle de 100 XOF en mode production. Conserver l’ancien certificat pendant six mois supplémentaires comme preuve historique de l’antériorité de la conformité.
Coexistence avec les ventes B2C non-fiscalisées
Certaines petites ventes B2C ne nécessitent pas de transmission FNE : vente comptoir avec ticket de caisse anonyme à montant faible, transactions ne dépassant pas le seuil fiscal défini. Le module doit cohabiter proprement avec ces flux non-FNE. Configurer un type de document Ticket non-FNE dans Dolibarr qui contourne le module FNE : pas de transmission API, pas de NUF, ticket simplifié sans QR. Documenter clairement quels flux sont en FNE et quels sont en non-FNE pour éviter toute confusion lors d’un contrôle.
La règle pratique communément admise par les PME ivoiriennes : passer en FNE toutes les ventes B2B sans exception, et toutes les ventes B2C dépassant 10 000 XOF. Sous ce seuil, ticket simplifié suffit. Cette politique réduit la charge de transmission API tout en restant conforme à la doctrine fiscale dominante.
Pour aller plus loin
🔝 Retour à l’article principal : Dolibarr 23 ERP/CRM pour TPE-PME francophone. Tutoriels précédents : installation Coolify, module Mobile Money. Spécifications officielles FNE : dgi.gouv.ci. Documentation xmlseclibs : github.com/robrichards/xmlseclibs.
Maintenir la conformité FNE dans la durée demande une vigilance opérationnelle : surveiller les communications de la DGI sur les évolutions du schéma XSD, planifier le renouvellement du certificat avant son échéance (généralement annuel), tester chaque mise à jour Dolibarr en bac à sable avant la mise en production pour éviter qu’un changement de comportement de l’ORM ne casse silencieusement la génération XML. Une checklist trimestrielle suffit à éviter les mauvaises surprises et préserve la chaîne fiscale fluide pour la PME.