Module Factur-X TBNETSYS: Difference between revisions

= facturxtbnetsys =

Plugin Dolibarr '''TBNETSYS''' qui régénère chaque facture client au format '''Factur-X''' : un PDF/A-3 avec un XML EN16931 (CII) embarqué, selon les spécifications françaises FNFE (profil EN16931 / Comfort).

Deux backends de génération PDF interchangeables, sélectionnables dans l'onglet Paramétrage section « Pipeline PDF » :

* '''horstoeko/PDF/A-3B portable''' ''(défaut)''. Sous-processus PHP CLI utilisant la librairie <code>horstoeko/zugferd</code> embarquée dans <code>vendor/</code>. '''Aucune dépendance système''' hors php-cli. Validation FNFE/PDP strictement identique au mode 3U. Fonctionne tel quel sur tout hébergement Dolibarr, y compris mutualisé.

* '''Mustang/PDF/A-3U strict'''. Pipeline historique Ghostscript + Mustang CLI. Recommandé pour archivage légal long terme (extractibilité Unicode garantie). Nécessite Ghostscript, Java JRE, Mustang JAR et le profil ICC sRGB sur le serveur (cf. § Installation des prérequis système). À choisir explicitement dans l'onglet Paramétrage.

Côté pilotage de la transmission, le plugin fournit une page '''Dispatch PDP''' qui liste les factures candidates avec leur statut local (SIREN vendeur/acheteur, PDF Factur-X présent) et leur statut côté plateforme (conformité, transmission). Deux actions en série sont proposées avec '''popup de progression en temps réel''' :

* '''« Vérifier la sélection »'''. Interroge SUPERPDP pour chaque facture cochée (validation Factur-X + statut transmission). Compteurs colorés (conformes / non conformes / transmises / en cours / en échec / jamais transmises) et journal détaillé par facture.

* '''« Envoyer au PDP la sélection »'''. Envoie effectivement chaque facture éligible vers SUPERPDP (avec confirmation préalable). Compteurs envoyées / ignorées / en erreur ; les factures déjà transmises ou non éligibles sont automatiquement ignorées.

Dans les deux cas, la popup affiche une barre d'avancement, le numéro de la facture en cours, et un bouton d'annulation. Les résultats sont persistés au fur et à mesure : vous pouvez fermer la popup à mi-parcours et reprendre plus tard sans perdre ce qui a déjà été traité, ce qui rend le contrôle et l'envoi de gros stocks (centaines voire milliers de factures) confortables et résistants aux timeouts.

== Compatibilité ==

! Composant !! Version requise

| Dolibarr || 22.0.3 ou supérieur

| PHP || 8.2 minimum (8.4 recommandé)

| Système d'exploitation cible || Debian 13 (les commandes ci-dessous sont prévues pour Debian/Ubuntu)

| Multi-entité (Multicompany) || Pris en charge. Toutes les requêtes filtrent par <code>entity</code> (<code>getEntity('invoice')</code> / <code>getEntity('bank_account')</code>) et la table de cache PDP <code>llx_facturxtbnetsys_pdp_check</code> porte une colonne <code>entity</code> avec index unique <code>(fk_facture, entity)</code>, ce qui isole les données par société sans collision.

== Choix du moteur PDF. Mustang ou horstoeko ? ==

Le plugin propose '''deux moteurs PDF interchangeables''' au choix de l'utilisateur, sélectionnables dans l'onglet ''Paramétrage'' après installation. Le mode '''horstoeko (PDF/A-3B portable)''' est le '''défaut depuis la version 1.1.0''' : il fonctionne sans aucune dépendance système et couvre la quasi-totalité des cas d'usage. Le mode Mustang reste disponible pour les utilisateurs qui ont besoin d'un archivage légal PDF/A-3U strict avec extractibilité Unicode garantie ; il s'active explicitement dans l'onglet Paramétrage. Avant de poursuivre, choisissez celui qui correspond à votre environnement et à vos contraintes : la suite du README s'organise autour de ce choix.

=== Arbre de décision ===

! Question !! Réponse → Mode à choisir

| '''Votre archivage légal exige-t-il l'extractibilité Unicode du texte (PDF/A-3U strict) ?''' || Non → '''horstoeko''' (défaut, rien à configurer)

| Si oui : avez-vous un accès terminal au serveur avec privilèges sudo ou root ? || Oui → '''Mustang''' recommandé (extractibilité Unicode garantie)

| Sinon (pas d'accès root) : || '''horstoeko''' reste le seul choix possible. Mustang nécessite root pour installer Ghostscript / Java / Mustang JAR

=== Comparatif détaillé ===

! Critère !! Mode '''Mustang''' (PDF/A-3U strict) !! Mode '''horstoeko''' (PDF/A-3B portable)

| '''Niveau PDF/A''' || 3U. Extractibilité Unicode garantie (archivage légal long terme, accessibilité, indexation, recherche plein texte) || 3B. Apparence fidèle, validité format Factur-X, archivage acceptable mais sans garantie d'extractibilité Unicode

| '''Validation FNFE / PDP''' || ✓ 0 erreur sur les 189 contrôles XSD CII + EN16931 + BR-FR-CTC-Flux2 || ✓ 0 erreur sur les '''mêmes''' 189 contrôles (validation strictement identique côté SUPERPDP)

| '''XML CII embarqué''' || Identique (généré par le builder du module) || Identique (généré par le builder du module)

| '''Accès terminal serveur requis''' || '''Oui. Sudo ou root indispensable''' pour installer Ghostscript, Java JRE, Mustang JAR, profil ICC sRGB || '''Non. Aucune installation système'''. Le module fonctionne tel quel via PHP CLI

| '''Hébergement mutualisé / instance managée sans SSH''' || ❌ Inadapté || ✓ Pleinement supporté

| '''Empreinte serveur''' || ~50 Mo (Java + Mustang) en plus des paquets système habituels || ~27 Mo de <code>vendor/</code> Composer embarqués dans le module

| '''Robustesse face à un PDF source quelconque''' || Ghostscript ré-encode entièrement le PDF en PDF/A-3 valide, quel que soit le PDF source. Aucune contrainte sur les polices ou les modèles utilisés par Dolibarr ou par d'autres modules || Repose sur le PDF source produit par Dolibarr (modèle « crabe » par défaut). Couvre les cas standards, mais un PDF source produit par un modèle tiers exotique peut donner un PDF/A-3B moins propre

| '''Validation Schematron au niveau pipeline local''' || Oui (Mustang valide XSD + règles métier FNFE en local) || Validation locale par horstoeko/zugferd côté XML uniquement ; la validation Schematron complète est faite côté SUPERPDP via <code>validation_reports</code>

=== Les deux modes peuvent coexister ===

* '''Démarrer en horstoeko''' (défaut, sans rien configurer) pour valider le plugin sans toucher au système (test, validation fonctionnelle)

* '''Basculer vers Mustang''' plus tard si vos exigences d'archivage évoluent. La bascule est instantanée, sans régénérer les anciennes factures

* '''Inversement, dégrader vers horstoeko''' si une migration vers un hébergement mutualisé devient nécessaire

Aucun re-traitement des factures déjà générées n'est requis lors d'un changement de mode : les anciennes factures restent valides, seules les nouvelles seront générées avec le moteur courant.

== Installation des prérequis système. ''Mode Mustang uniquement'' ==

Cette section est conçue pour un utilisateur '''non administrateur système''' mais disposant tout de même d'un '''accès terminal avec privilèges sudo ou root'''. Sans cet accès, le mode Mustang n'est pas installable. Basculer sur le mode horstoeko. Chaque étape est expliquée : à quoi sert l'outil, comment l'installer, comment vérifier qu'il est correctement en place. Suivre les blocs dans l'ordre.

=== Conventions ===

* Toutes les commandes doivent être exécutées '''avec les droits root''' sur le serveur Dolibarr. Si vous n'êtes pas connecté en root, préfixer chaque commande par <code>sudo</code> (par exemple <code>sudo apt install …</code>).

* <code>www-data</code> est l'utilisateur Linux sous lequel le serveur web (Apache/Nginx) exécute Dolibarr. Lorsqu'une commande doit être lancée en tant que <code>www-data</code>, c'est explicitement indiqué.

* <code>#</code> au début d'une ligne signifie « commentaire, ne pas taper ».

* Toujours '''copier-coller''' les commandes : un caractère manquant ou un tiret recopié à la main peut casser l'installation.

=== Étape 1. Mettre à jour la liste des paquets ===

Cette commande ne modifie rien sur le système : elle se contente de télécharger la liste des paquets disponibles. Elle peut afficher quelques avertissements (<code>Different settings for HTTP/HTTPS</code>), c'est normal.

=== Étape 2. Installer Ghostscript ===

'''À quoi ça sert''' : Ghostscript (commande <code>gs</code>) est l'outil qui convertit le PDF généré par Dolibarr en '''PDF/A-3''', le format obligatoire pour qu'un Factur-X soit valide. Sans lui, le PDF n'est pas conforme et le destinataire le rejettera.

'''Vérification''' :

=== Étape 3. Installer Java (JRE) ===

'''À quoi ça sert''' : Mustang (étape suivante) est un programme écrit en Java. Pour pouvoir l'exécuter, il faut une JVM (machine virtuelle Java) installée sur le serveur. On installe le '''JDK headless''' (sans interface graphique, suffisant pour un serveur).

'''Vérification''' :

=== Étape 4. Télécharger Mustang CLI ===

'''À quoi ça sert''' : Mustang est l'outil qui prend le PDF/A-3 fabriqué à l'étape 2 et le XML EN16931 généré par le plugin, puis les fusionne en un véritable PDF Factur-X (avec les bonnes métadonnées XMP, le nom canonique <code>factur-x.xml</code> du fichier embarqué, etc.). Le plugin appelle Mustang en arrière-plan à chaque régénération de facture.

'''Vérification''' :

=== Étape 5. Vérifier la présence du profil ICC sRGB ===

'''À quoi ça sert''' : un PDF/A-3 doit déclarer un '''profil colorimétrique de référence''' (le profil ICC). Le plugin utilise sRGB par défaut, le plus standard. Ce profil est généralement présent par défaut sur Debian via le paquet <code>icc-profiles-free</code>.

* Si le fichier existe : rien à faire.

* Si le fichier est absent (<code>No such file or directory</code>) :

=== Étape 6. Installer les paquets PHP utilisés par Dolibarr ===

'''À quoi ça sert''' : Dolibarr et le plugin s'appuient sur quelques bibliothèques PHP pour manipuler les PDF (TCPDF, FPDI), pour parser des PDF lus (Poppler), et pour quelques utilitaires bas niveau (binutils).

Détail rapide :

! Paquet !! Utilité

| <code>binutils</code> || Outils binaires bas niveau utilisés par certaines libs

| <code>php-tcpdf</code> || Génération PDF côté Dolibarr

| <code>php-fpdi</code> || Lecture/import de PDF existants

| <code>poppler-utils</code> || Outils annexes (<code>pdfinfo</code>, <code>pdftotext</code>)

'''Vérification''' :

== Mode horstoeko. Aucun prérequis système ==

=== Vérification rapide depuis votre Dolibarr ===

Si vous avez accès au serveur en SSH (même sans sudo), vérifier que PHP CLI a SimpleXML :

=== Si vous n'avez pas du tout accès au shell ===

Sur certains hébergements mutualisés, vous n'avez accès qu'au panel d'administration et à un éditeur de fichiers via FTP/SFTP. Dans ce cas :

# [[#Installation du plugin|Installez le plugin]] en uploadant son répertoire dans <code>custom/</code>

# Activez-le dans Dolibarr

# Allez dans '''Diagnostic''' : la page vérifiera '''automatiquement''' que le PHP CLI cible (via la constante <code>FACTURXTBNETSYS_PHP_BIN</code>) a bien SimpleXML

# Si SimpleXML manque côté CLI, le diagnostic vous l'indiquera : il faudra alors demander à votre hébergeur d'activer l'extension <code>simplexml</code> ou de pointer le plugin sur une autre version de PHP CLI qui l'inclut

=== Vendor Composer fourni dans le plugin ===

== Installation du plugin ==

Cette étape est commune aux deux modes. Une fois les prérequis correspondant à votre choix de mode validés :

# Copier le répertoire <code>facturxtbnetsys/</code> dans le dossier <code>custom/</code> de Dolibarr :

#: <syntaxhighlight lang="bash">

# Activer le module dans Dolibarr : '''Accueil > Configuration > Modules > Onglet "Facturation/Comptabilité"''' → activer '''FacturXTbnetsys'''.

# Créer le fichier <code>.secret</code> '''hors de la racine web''' (à côté de <code>htdocs/</code>, ou dans un répertoire dédié aux secrets) et y renseigner les identifiants de connexion à votre PDP, puis indiquer son chemin absolu à Dolibarr dans l'onglet Paramétrage (voir la sous-section [[#Configuration du fichier .secret (credentials PDP)|Configuration du fichier .secret]] ci-dessous).

# Vérifier la santé de l'installation : '''Configuration > Modules > FacturX > onglet Diagnostic'''. La page liste les vérifications avec un code couleur (le contenu varie selon le backend PDF sélectionné) ; toutes doivent être au vert (à l'exception éventuelle de <code>.secret</code> qui peut être marqué « optionnel » tant que vous n'avez pas finalisé la configuration PDP).

=== Configuration du fichier .secret (credentials PDP) ===

<blockquote>'''Sans <code>.secret</code>, le plugin reste fonctionnel''' : la régénération Factur-X (PDF/A-3 + XML EN16931) continue de fonctionner. Seul l'envoi automatique vers la PDP est désactivé. Le diagnostic affiche alors <code>.secret</code> en orange « optionnel ».</blockquote>

Le fichier <code>.secret</code> doit être placé '''en dehors du dossier <code>htdocs/</code>''' (la racine web servie par Apache / Nginx) afin qu'il ne puisse jamais être servi par le serveur HTTP en cas de mauvaise configuration ou de bug. Sur une installation type <code>/var/www/dolibarr/htdocs/</code>, placez-le par exemple :

! Emplacement !! Recommandation

| <code>/var/www/dolibarr/.secret</code> || '''Recommandé'''. Au même niveau d'arborescence que <code>htdocs/</code>, donc inaccessible via HTTP par construction

| <code>/etc/dolibarr-secrets/pdp.secret</code> || '''Recommandé'''. Répertoire système dédié aux secrets, idéal pour gérer plusieurs environnements (<code>pdp-prod.secret</code>, <code>pdp-sandbox.secret</code>)

| <code>/var/www/dolibarr/htdocs/custom/facturxtbnetsys/.secret</code> || '''À éviter'''. Fonctionne (chemin par défaut codé), mais place le fichier sous la racine web : tout problème de configuration serveur peut l'exposer en clair

'''Obtention des identifiants''' : récupérer <code>client_id</code> et <code>client_secret</code> depuis l'espace administrateur de votre PDP. Pour SUPERPDP, l'endpoint d'authentification utilisé par le plugin est <code>api.superpdp.tech/oauth2/token</code>.

'''Format attendu'''. Fichier texte, une clé par ligne, valeur entre guillemets droits (les guillemets sont optionnels). Les lignes vides et celles commençant par <code>#</code> sont ignorées :

'''Création et droits Unix'''. Le plugin fournit un modèle <code>.secret.example</code> à la racine du plugin. Copiez-le '''hors de la racine web''' puis complétez-le :

Puis, dans Dolibarr : '''Configuration > Modules > FacturX > Paramétrage > API PDP > Chemin du fichier <code>.secret</code>''' → saisir <code>/var/www/dolibarr/.secret</code> (adapter à votre installation) et enregistrer.

'''Précautions de sécurité''' :

* '''Placer <code>.secret</code> hors de la racine web''' (cf. tableau ci-dessus) : c'est la garantie la plus solide qu'il ne sera jamais servi en HTTP.

* '''Ne jamais committer <code>.secret</code>''' dans un dépôt git (ajouter <code>.secret</code> au <code>.gitignore</code> du plugin si vous forkez le code).

* '''Ne jamais transmettre le fichier par email/messagerie''' en clair.

* En cas de fuite suspectée, '''révoquer immédiatement le <code>client_secret</code>''' depuis l'admin de la PDP et en générer un nouveau.

* Le fichier doit appartenir à <code>www-data</code> et être en <code>0600</code> : aucun autre utilisateur Unix de la machine ne doit pouvoir le lire.

'''Vérification'''. Après création, ouvrir '''Configuration > Modules > FacturX > Diagnostic''' :

! Ligne diagnostic !! État attendu

| <code>.secret</code> || '''OK''' (vert). Fichier présent et <code>client_id</code> / <code>client_secret</code> non vides

| <code>api.superpdp.tech</code> || '''OK''' (vert). Un Bearer token a été obtenu avec succès

Si <code>.secret</code> ressort « KO » (rouge), le fichier existe mais une des deux clés est absente ou mal formée. Relire le format ci-dessus. Si <code>api.superpdp.tech</code> ressort en erreur, les identifiants sont rejetés par la PDP : vérifier qu'ils sont corrects et actifs côté admin de la plateforme. Les détails de l'erreur sont tracés dans le journal Dolibarr (<code>Accueil > Configuration > Outils > Journaux</code>, préfixe <code>FACTURXTBNETSYS</code>).

=== Sélection du moteur PDF dans Dolibarr ===

Une fois le module activé, aller dans '''Configuration > Modules > FacturX > onglet Paramétrage'''. La section '''« Pipeline PDF »''' propose un radio à deux choix :

* '''horstoeko/zugferd / PDF/A-3B portable'''. Choix par défaut depuis la version 1.1.0. Aucun prérequis système. Sous le radio, un champ '''« Binaire php-cli »''' permet de pointer vers la version de PHP utilisée par le sous-processus (par défaut <code>/usr/bin/php</code>). Si votre <code>/usr/bin/php</code> ne dispose pas de l'extension SimpleXML, indiquer ici une version qui l'inclut, par exemple <code>/usr/bin/php8.4</code>.

* '''Mustang / PDF/A-3U strict'''. Choix optionnel pour archivage légal long terme. Nécessite que la procédure [[#Installation des prérequis système. Mode Mustang uniquement|Installation des prérequis système]] ait été suivie au préalable.

== Vérification finale en une commande ==

=== Mode Mustang ===

Pour vérifier en bloc tous les prérequis Mustang depuis la ligne de commande :

=== Mode horstoeko ===

== Pièges fréquents ==

=== Mode Mustang ===

! Symptôme !! Cause probable !! Solution

| <code>gs: command not found</code> lors de la régénération || Ghostscript pas installé ou pas dans le <code>PATH</code> du serveur web || Re-vérifier l'étape 2. Au besoin, renseigner le chemin absolu dans '''Configuration > Modules > FacturX > Paramétrage''', champ « Binaire Ghostscript »

| <code>Mustang JAR introuvable/illisible</code> || Le fichier n'est pas à <code>/opt/Mustang-CLI-2.22.0.jar</code>, ou pas lisible par <code>www-data</code> || <code>chmod +r /opt/Mustang-CLI-2.22.0.jar</code> ou ajuster le chemin dans '''Configuration > Modules > FacturX > Paramétrage''', champ « Mustang CLI (.jar) »

| <code>java: command not found</code> || JRE non installé || Re-vérifier l'étape 3

| Erreur PDF/A-3 « no ICC profile » || Le profil sRGB n'est pas trouvé || Re-vérifier l'étape 5, ajuster le chemin dans '''Configuration > Modules > FacturX > Paramétrage''', champ « Profil ICC sRGB » si nécessaire

=== Mode horstoeko ===

! Symptôme !! Cause probable !! Solution

| <code>vendor/autoload.php introuvable</code> dans le journal || Le <code>vendor/</code> Composer n'a pas été déployé avec le plugin || Réinstaller le plugin depuis l'archive officielle (qui inclut <code>vendor/</code>) ou exécuter <code>composer install --no-dev --optimize-autoloader</code> à la racine du module

| <code>Binaire php-cli introuvable ou non exécutable</code> || La constante <code>FACTURXTBNETSYS_PHP_BIN</code> pointe sur un chemin invalide || Ajuster dans '''Paramétrage > Pipeline PDF > Binaire php-cli''' (ex. <code>/usr/bin/php8.4</code>)

| <code>extension SimpleXML absente</code> (badge KO dans Diagnostic) || La version de PHP CLI désignée n'a pas l'extension <code>simplexml</code> || Pointer la constante <code>FACTURXTBNETSYS_PHP_BIN</code> sur une autre version de PHP CLI qui inclut SimpleXML, ou demander à l'hébergeur d'activer l'extension côté CLI

| <code>Sous-processus horstoeko a échoué (rc=…)</code> || Erreur dans la lib horstoeko/zugferd ; le PDF source produit par Dolibarr peut être atypique || Consulter le journal Dolibarr (préfixe <code>FACTURXTBNETSYS</code>) ; en dernier recours, basculer temporairement sur le mode Mustang pour identifier si le PDF source est en cause

=== Communs aux deux modes ===

! Symptôme !! Cause probable !! Solution

| <code>proc_open() has been disabled</code> dans le syslog || Le serveur (souvent un VPS mutualisé) interdit l'exécution de processus externes || Demander à l'hébergeur d'autoriser <code>proc_open</code> dans <code>php.ini</code> (<code>disable_functions</code>). '''Les deux modes''' utilisent <code>proc_open</code> (Mustang pour Ghostscript+Java, horstoeko pour le sous-processus PHP). Le plugin '''ne peut pas fonctionner sans'''

| Page Diagnostic affiche tout en vert mais erreur à l'usage || Cache OPcache PHP || Redémarrer Apache/Nginx (<code>systemctl reload apache2</code>)

== Catégories TVA. Comment le plugin classe vos factures ==

À chaque régénération de facture, le plugin détermine '''automatiquement''' le régime TVA applicable à chaque ligne et le code d'exonération correspondant exigé par la norme européenne EN16931. '''Vous n'avez rien à paramétrer''' : tout est déduit de la configuration de votre société, du pays du client et des taux de TVA de la facture.

=== Les 6 cas reconnus (du plus prioritaire au moins prioritaire) ===

==== 1. Vous êtes en franchise en base de TVA (micro-entreprise) ====

'''Condition''' : dans Dolibarr, '''Accueil > Configuration > Société > « Assujetti à la TVA » = Non'''.

<blockquote>Cette règle est prioritaire : si vous êtes en franchise, le plugin ne tient compte ni des taux, ni du pays du client, ni des lignes de débours. Tout sort en franchise.</blockquote>

==== 2. La ligne est un débours (refacturation à l'identique d'un frais) ====

'''Condition''' : la ligne a été saisie via le plugin '''debourstbnetsys''' (refacturation à l'identique au client d'un frais que vous avez avancé pour son compte).

==== 3. La ligne porte un taux de TVA standard ====

'''Condition''' : la ligne a un taux de TVA strictement supérieur à 0 % (5,5 %, 10 %, 20 %, etc.).

==== 4. Vous facturez un client professionnel établi dans l'Union européenne ====

'''Condition''' : le taux est à 0 %, le client est dans un pays UE différent de la France, et '''son numéro de TVA intracommunautaire est renseigné''' dans sa fiche tiers.

==== 5. Vous facturez un client hors Union européenne ====

'''Condition''' : le taux est à 0 % et le client est dans un pays hors UE.

→ La ligne est marquée « export », exonérée au titre de l'''''art. 262 I du CGI'''.

==== 6. Tous les autres cas avec un taux à 0 % ====

'''Condition''' : taux à 0 %, client en France ou client UE sans numéro de TVA intracommunautaire (cas typique : particulier européen).

=== À savoir avant de mettre en service ===

* '''Numéro de TVA intracommunautaire indispensable pour vos clients UE professionnels.''' Si vous facturez un client allemand, italien, espagnol, etc. sans avoir renseigné son n° TVA intra dans Dolibarr, le plugin considérera qu'il s'agit d'un particulier (cas n° 6) au lieu d'une livraison intracommunautaire (cas n° 4). Pensez à compléter la fiche tiers avant la première facture.

* '''Mention « Autoliquidation » à ajouter manuellement.''' Pour les factures intracommunautaires (cas n° 4), la réglementation impose que la facture mentionne explicitement « Autoliquidation ». Le plugin ne l'ajoute pas automatiquement pour l'instant : pensez à le faire dans le libellé de votre facture.

* '''Vérifiez votre statut TVA si vous êtes micro-entreprise.''' Le plugin détecte la franchise via le paramètre Dolibarr '''Configuration > Société > « Assujetti à la TVA »'''. Vérifiez qu'il est bien sur '''Non''' si vous êtes effectivement en franchise. Sinon vos factures sortiront avec un régime TVA classique au lieu de la mention 293 B.

* '''Si vous mettez à jour le plugin depuis une version antérieure''' et que vous émettez régulièrement des factures intracommunautaires ou à l'export : vos prochaines régénérations utiliseront un code TVA plus précis qu'avant (correction de conformité). Les factures déjà émises ne sont pas modifiées. Faites un essai sur une facture représentative pour vérifier qu'elle est bien acceptée par votre PDP avant de regénérer en masse.

== Acomptes. Comment le plugin gère les factures d'acompte et leur imputation ==

Le plugin reconnaît automatiquement les '''factures d'acompte''' que vous émettez dans Dolibarr (type « Acompte ») ainsi que les '''factures finales''' sur lesquelles ces acomptes sont imputés. '''Vous n'avez rien à paramétrer''' : la détection se fait au moment de la régénération.

=== Si vous émettez une facture d'acompte ===

Quand le type de la facture Dolibarr est '''« Acompte »''' :

→ Les mentions légales obligatoires en France (indemnité de recouvrement 40 €, pénalités de retard, escompte) sont conservées : un acompte est une '''facture exigible''' au sens fiscal, la TVA y est exigible.

=== Si vous émettez la facture finale après un ou plusieurs acomptes ===

Quand vous facturez le solde d'une commande déjà partiellement payée par acompte(s) :

=== À savoir avant de mettre en service (acomptes) ===

* '''Bien lier l'acompte à la facture finale dans Dolibarr.''' L'imputation est lue depuis la table standard Dolibarr des « remises et avoirs déjà appliqués ». Si vous saisissez la facture finale sans déclarer explicitement l'acompte précédent (par exemple en passant par les écritures de paiement uniquement, sans utiliser le mécanisme « consommer cet acompte »), le plugin ne pourra pas en tenir compte automatiquement.

* '''Avoirs imputés non comptabilisés en BT-113.''' Si vous imputez un avoir sur une facture finale, le plugin ne l'inclut '''pas''' dans le « total déjà payé » (BT-113). C'est conforme à la norme EN16931 qui réserve cette balise aux '''avances reçues''' (acomptes), pas aux compensations (avoirs). Le solde net reste correct car l'avoir est traité comme un mode de règlement classique côté Dolibarr.

* '''Avoir d'acompte (cas marginal).''' Émettre un avoir qui annule une facture d'acompte fonctionne mais le XML produit ne référence pas explicitement la facture d'acompte annulée. À éviter en l'état si vous avez besoin d'une traçabilité formelle ; sinon le résultat reste valide EN16931.

== Unités de mesure (UN/ECE Rec 20) ==

=== Table de conversion appliquée ===

! Famille !! Dolibarr (<code>code</code>) → UN/ECE Rec 20

| Temps || <code>S</code>→SEC · <code>MI</code>→MIN · <code>H</code>→HUR · <code>D</code>→DAY · <code>W</code>→WEE · <code>MO</code>→MON · <code>Y</code>→ANN

| Poids || <code>T</code>→TNE · <code>KG</code>→KGM · <code>G</code>→GRM · <code>MG</code>→MGM · <code>OZ</code>→ONZ · <code>LB</code>→LBR

| Longueur || <code>M</code>→MTR · <code>DM</code>→DMT · <code>CM</code>→CMT · <code>MM</code>→MMT · <code>FT</code>→FOT · <code>IN</code>→INH

| Surface || <code>M2</code>→MTK · <code>DM2</code>→DMK · <code>CM2</code>→CMK · <code>MM2</code>→MMK · <code>FT2</code>→FTK · <code>IN2</code>→INK

| Volume || <code>M3</code>→MTQ · <code>DM3</code>→DMQ · <code>CM3</code>→CMQ · <code>MM3</code>→MMQ · <code>FT3</code>→FTQ · <code>IN3</code>→INQ · <code>L</code>→LTR · <code>GAL</code>→GLL

| Quantité || <code>P</code>→C62 (un/pièce) · <code>SET</code>→SET

=== Politique de fallback ===

* Ligne sans unité renseignée (<code>fk_unit</code> vide) : code <code>C62</code> (one/each), comportement neutre.

* Unité présente mais désactivée dans <code>llx_c_units</code> (colonne <code>active=0</code>) : code <code>C62</code>.

* Code Dolibarr non couvert par la table (unité personnalisée ajoutée par l'instance) : code <code>C62</code>, et un message <code>LOG_INFO</code> est tracé dans le journal Dolibarr (<code>dol_syslog</code>) pour permettre l'extension de la table.

Aucune configuration n'est nécessaire : le mapping s'applique à la régénération, pour les factures et les avoirs, y compris les lignes débours du plugin <code>debourstbnetsys</code>.

== Paramétrage du plugin dans Dolibarr ==

Une fois l'installation terminée, tout le paramétrage du plugin se fait depuis l'interface Dolibarr. Vous trouverez quatre pages utiles :

* '''Configuration > Modules > FacturX > Paramétrage''' : options principales du plugin. Activer ou non l'envoi des factures vers le PDP, activer ou non la validation à la régénération, taille des pages d'écran, et '''chemins des utilitaires système''' (Ghostscript, Mustang JAR, profil ICC sRGB) si vos outils ne sont pas aux emplacements par défaut.

* '''Configuration > Modules > FacturX > Diagnostic''' : page de contrôle de santé en lecture seule. Affiche en vert/rouge l'état des prérequis (Ghostscript, Java, Mustang, profil ICC, accès à votre PDP…). En cas d'anomalie sur un chemin, l'ajustement se fait dans la page Paramétrage ci-dessus.

* '''Configuration > Modules > FacturX > Adresses Peppol''' : gestion de votre annuaire d'identifiants Peppol/PPF (à utiliser uniquement si vous savez ce que c'est).

* '''FacturX > Dispatch PDP''' (menu principal) : page d'envoi explicite de vos factures vers la plateforme PDP, avec filtres par période, client, état, etc.

=== Mode strict (en cas d'échec du pipeline Factur-X) ===

Sur la page '''Paramétrage''', l'option '''« Mode strict »''' détermine ce qu'il se passe si la conversion en Factur-X plante (Ghostscript indisponible, Mustang qui échoue, profil ICC introuvable, etc.) :

* '''Décoché (recommandé, valeur par défaut)'''. Mode best-effort. Si le pipeline Factur-X échoue, le PDF classique généré par votre modèle de base (par exemple « crabe ») est '''conservé''' et la facture reste utilisable. Un avertissement orange est affiché à l'utilisateur. La facture peut être imprimée et envoyée par email. Elle n'est juste pas au format Factur-X.

* '''Coché'''. Mode strict. Tout échec du pipeline supprime le PDF et fait remonter une erreur côté Dolibarr. Aucune facture n'est livrée tant que le problème technique n'est pas corrigé. À utiliser uniquement si vous voulez la garantie absolue qu'aucun PDF non-Factur-X ne circule (par ex. exigence contractuelle ou réglementaire).

== Source du plugin ==

Le plugin est distribué sur le '''Dolistore''', la place de marché officielle des modules Dolibarr : www.dolistore.com/. C'est la voie recommandée pour les utilisateurs finaux qui souhaitent simplement installer le plugin sur leur Dolibarr.

<blockquote>'''Note documentation''' : ce fichier <code>README.md</code> est repris tel quel dans le wiki Dolibarr de la fiche du plugin. Toute mise à jour du README est donc répercutée par son auteur dans la documentation publique du plugin côté Dolibarr.</blockquote>

== Mise à jour du plugin ==

Pour mettre à jour le plugin vers une nouvelle version :

# '''Télécharger la mise à jour sur le Dolistore''' : www.dolistore.com/. Récupérer l'archive de la dernière version publiée et l'extraire dans le dossier <code>custom/</code> de votre Dolibarr (par-dessus l'installation existante). Ne pas oublier de rétablir les droits :

#: <syntaxhighlight lang="bash">

# '''Désactiver puis réactiver le plugin''' dans '''Accueil > Configuration > Modules''', onglet « Facturation/Comptabilité ». Ce cycle force Dolibarr à recharger les définitions du module (constantes, hooks, menus, droits) et garantit que les éventuelles nouveautés apportées par la mise à jour sont prises en compte. Vos données existantes ne sont pas affectées.

# '''Reparamétrer si nécessaire'''. Si la mise à jour introduit de nouvelles options ou si certains paramétrages ont changé de format, vérifier la page '''Configuration > Modules > FacturX > Paramétrage''' ainsi que la page '''Diagnostic''' (toutes les vérifications doivent rester au vert).

# '''Optionnellement''', lire le fichier <code>ChangeLog.md</code> à la racine du plugin pour prendre connaissance du détail des changements (corrections de bugs, nouvelles fonctionnalités, modifications de comportement, éventuelles actions manuelles requises).

== Signalement de bugs ==

Le plugin est maintenu par son auteur qui assure la '''correction des anomalies''' rencontrées par ses utilisateurs. Pour signaler un bug, utilisez le '''formulaire de contact''' : www.tbnetsys.fr/contact/.

'''Ce canal est dédié exclusivement aux corrections de bugs''', c'est-à-dire à des comportements du plugin qui ne sont pas conformes à ce que décrit cette documentation ou à la norme Factur-X / EN16931. Il ne s'agit '''pas d'un service d'assistance utilisateur''' : les questions d'installation Dolibarr, de paramétrage métier, de fiscalité, ou plus généralement « comment faire X dans Dolibarr » ne relèvent pas de ce canal et ne recevront pas de réponse.

Pour qu'un signalement soit exploitable, soyez '''précis et clair''' dans la description du problème. Un bon rapport de bug contient au minimum :

* '''Versions''' : version de Dolibarr, version de PHP, version du plugin (visible sur la page Configuration > Modules), système d'exploitation du serveur.

* '''Contexte précis''' : sur quelle facture (type : standard, acompte, avoir ; pays du client ; régime TVA), à quelle étape (régénération PDF, envoi PDP, validation Mustang…).

* '''Comportement observé''' : message d'erreur exact (copier-coller, pas une reformulation), capture d'écran si pertinent.

* '''Comportement attendu''' : ce qui aurait dû se produire à la place.

* '''Reproductibilité''' : le bug se produit-il à chaque tentative ou de manière intermittente ? sur toutes les factures ou seulement certaines ?

* '''Journaux Dolibarr''' : extrait du journal (<code>Accueil > Configuration > Outils > Journaux</code>) filtré sur le préfixe <code>FACTURXTBNETSYS</code> au moment de l'incident.

== Clause de non responsabilité ==

'''Ni l'auteur, ni TBNETSYS, ni les contributeurs ne pourront en aucun cas être tenus responsables''' d'un quelconque dommage direct ou indirect (notamment, mais sans s'y limiter : perte de données, perte de chiffre d'affaires, perte d'exploitation, rejet de factures par un destinataire ou par un PDP, redressement fiscal, sanction administrative, dommage matériel, immatériel ou moral) résultant de l'installation, de l'utilisation, du dysfonctionnement ou de l'impossibilité d'utiliser le plugin, même dans l'hypothèse où l'auteur, TBNETSYS ou un contributeur auraient été informés de l'éventualité d'un tel dommage.

== Auteur et licence ==

Auteur : '''Thierry Bazzanella'''<br/>

Contact : www.tbnetsys.fr/contact/<br/>

(La nuit, Marvin, le bot gérant le formulaire de contact, dort, lui aussi. Comme vous)<br/>

(c) 2026 TBNETSYS. All rights reserved<br/>

Licence : GPL-3.0-or-later<br/>

== Contributeurs et béta-testeurs ==

Un '''environnement dédié et privé sous GitLab''' est mis à disposition pour ce plugin : il regroupe le code source, le suivi des tickets, les branches de travail et les itérations de test. L'environnement est très '''orienté développement et cycle de vie logiciel''' (branches, revues, intégration continue, jalons, releases). Il s'adresse donc à des intervenants à l'aise avec ces pratiques.

La documentation du code source est intégrée à celui-ci au format PhpDoc. L'outil de développement recommandé est '''Visual Studio Code''' avec les extensions '''PHP Intelephense''' (éditeur : Intelephense) et '''PHP Debug''' (éditeur : Xdebug).

La '''communication entre tous les intervenants se fait principalement par ticket''' (issues GitLab) : signalement, discussion technique, suivi d'avancement, validation. Cela garantit la traçabilité des décisions et permet à chacun de retrouver le contexte d'un changement à tout moment.

Pour rejoindre l'environnement contributeurs/béta-testeurs, prendre contact via le formulaire : www.tbnetsys.fr/contact/.

== Prix du plugin ==

! Période !! Prix

| Tarif de lancement, jusqu'au 31 août 2026 || '''149 € TTC'''

| À compter du 1er septembre 2026 || '''199 € TTC'''

L'auteur n'est pas assujetti à la TVA (franchise en base, art. 293 B du CGI). Les prix indiqués sont nets de taxe : aucun montant de TVA ne s'ajoute au prix affiché.

'''Mises à jour à vie incluses.''' Chaque acquéreur reçoit toutes les versions futures du plugin sans frais supplémentaire : corrections de bugs, mises en conformité réglementaire, nouvelles fonctionnalités, nouveaux profils EN16931, prise en charge des futures versions de Dolibarr. Une seule acquisition couvre l'usage du plugin sur la durée.

'''Aucune obligation, d'aucune sorte, de l'auteur ni des contributeurs.''' Les mises à jour à vie comme la correction des bugs sont fournies dans la mesure des moyens et de la disponibilité de l'auteur et de ses éventuels contributeurs, sans engagement d'aucune sorte : ni de fréquence, ni de délai, ni de périmètre, ni de résultat, ni de continuité de service. L'acquisition du plugin n'ouvre droit à aucune prestation contractuelle de maintenance, de support ou d'évolution. Le plugin est fourni « en l'état » conformément à la § Clause de non responsabilité, qui prévaut sur la présente section en cas de divergence d'interprétation.

=== Support payant (optionnel) ===

'''Tarif horaire : 85 € TTC / heure.''' L'auteur n'étant pas assujetti à la TVA (franchise en base, art. 293 B du CGI), aucun montant de TVA ne s'ajoute au prix affiché.

'''Périmètre.''' À distance uniquement : email, formulaire de contact, partage d'écran ou accès SSH ponctuel sur autorisation explicite et révocable de l'utilisateur. La prestation porte exclusivement sur le plugin FacturXTbnetsys et son intégration dans Dolibarr (paramétrage, diagnostic, accompagnement à l'installation, analyse de cas particuliers et lecture de journaux). Sont exclus du périmètre : l'administration Dolibarr générale, le conseil fiscal, le conseil métier, l'intervention sur d'autres modules tiers et le développement spécifique non directement lié à une anomalie du plugin.

! Jour !! Plage horaire

| Lundi à vendredi || 9h–12h et 14h–18h

| Samedi, dimanche, jours fériés légaux français || Fermé

'''Délais cibles de prise en charge.''' Les délais ci-dessous courent à compter de la réception de la demande pendant les heures ouvrées : une demande arrivée hors plage est réputée reçue à l'ouverture suivante. Ces délais sont des '''objectifs cibles à effort raisonnable, jamais des engagements contractuels chiffrés opposables'''.

! Niveau de gravité !! Définition !! Objectif cible de prise en charge

| Critique || Production de factures Factur-X totalement interrompue, aucun contournement disponible || 4 heures ouvrées

| Majeur || Fonctionnalité importante dégradée mais contournement possible (par exemple : mode Mustang en échec mais mode horstoeko fonctionnel) || 1 jour ouvré

| Mineur || Gêne ponctuelle, question, optimisation, demande de paramétrage ou d'éclaircissement || 3 jours ouvrés

'''Obligation de moyen, à l'exclusion de toute obligation de résultat.''' Le support payant constitue une '''prestation de services''' au sens du droit français, exécutée selon une '''obligation de moyen uniquement'''. L'auteur s'engage à mettre en œuvre ses compétences professionnelles et le temps nécessaire pour tenter d'apporter une réponse ou une résolution, '''sans garantir aucun résultat''' : ni la résolution effective de la difficulté signalée, ni le respect des délais cibles ci-dessus, ni l'absence de récidive, ni la compatibilité avec l'environnement particulier de l'utilisateur. Les délais cibles ne sont assortis d''''aucune pénalité''' et n'ouvrent droit à '''aucune indemnité, remise ou avoir''' en cas de dépassement. Cette obligation de moyen prévaut sur toute interprétation contraire pouvant résulter de la rédaction de la présente section.

'''Exclusivement et uniquement sous forme de services.''' La prestation ne comprend ni produit logiciel additionnel, ni licence supplémentaire, ni garantie, ni assurance, ni cession de droits, ni livrable autre que le '''compte-rendu d'intervention'''. Ce compte-rendu mentionne au minimum : la nature des vérifications effectuées, les éléments diagnostiqués, les actions menées, les points restant ouverts ainsi que les recommandations à destination de l'utilisateur. Il est remis quel que soit le résultat constaté. Le règlement rémunère exclusivement le '''temps de travail effectivement passé''' en assistance, indépendamment du résultat constaté à l'issue de l'intervention.

'''Procédure d'accès au support payant.''' Le support payant n'est pas accessible directement sur facture spontanée. Il suppose au préalable :

# Un '''premier contact via le formulaire''' : www.tbnetsys.fr/contact/, en présentant le contexte de la demande (instance Dolibarr, version du plugin, nature du besoin d'accompagnement).

# La '''signature d'un contrat de support''' entre l'utilisateur (en qualité de professionnel) et TBNETSYS, qui formalise le tarif horaire, les modalités de facturation, le périmètre, les délais cibles, l'obligation de moyen, l'exclusion de l'obligation de résultat ainsi que les autres conditions rappelées dans la présente section.

# L''''acceptation écrite d'un devis''' propre à chaque intervention, dans le cadre du contrat ainsi signé.