Module UltimateInvoice FR: Difference between revisions

From Dolibarr ERP CRM Wiki
Jump to navigation Jump to search
VisualWikitext
No edit summary
Tags: Reverted 2017 source edit
(Undo revision 66800 by Grandoc (talk))
Tag: Undo
Line 1: Line 1:
=Summary=
=Sommaire=
[[Category:Add-on modules]]
[[Category:Modules complémentaires]]
[[Category:Ultimateinvoice]]
[[Category:Ultimateinvoice]]
{{TemplateDocDev}}
{{TemplateDocDev}}
Line 10: Line 10:
|webbuy={{LinkToPluginDownloadDoliStore|keyword=ultimateinvoice}}
|webbuy={{LinkToPluginDownloadDoliStore|keyword=ultimateinvoice}}
|status=stable
|status=stable
|prerequisites=''Invoices'' module enabled - PHP 7.4 minimum
|prerequisites=Module ''Factures'' activé - PHP 7.4 minimum
|minversion=23.0.x - 24.0.x
|minversion=23.0.x - 24.0.x
|note=
|note=
''[[#Summary|⬆ Back to summary]]''
''[[#Sommaire|⬆ Retour au sommaire]]''
}}
}}


=Features=
=Fonctionnalités=
UltimateInvoice replaces the native Dolibarr PDF template for '''invoices''' with a fully customisable template named '''<code>ultimate_invoice</code>'''. A true Swiss army knife for PDF invoices, it lets you define your own graphic identity (logo, colours, margins, page background, column widths), choose exactly what is printed on the document, append your GSC or additional PDF files, add barcodes and QR codes, and '''digitally sign''' the generated file.
UltimateInvoice remplace le modèle PDF natif de Dolibarr pour les '''factures''' par un modèle entièrement personnalisable, nommé '''<code>ultimate_invoice</code>'''. Véritable couteau suisse de la facture PDF, il permet de définir votre charte graphique (logo, couleurs, marges, fond de page, largeurs de colonnes), de choisir précisément ce qui s'affiche sur le document, d'y joindre vos CGV ou des PDF annexes, d'y ajouter des codes-barres et QR-codes, et de '''signer numériquement''' le fichier généré.


'''UltimateInvoice is the lightweight edition of the [[Module_Ultimatepdf_EN|UltimatePDF]] module''': it covers invoices only. For proposals, orders, contracts, shipments, expense reports, interventions, projects, products/BOMs or supplier documents, the full UltimatePDF edition is required.
'''UltimateInvoice est la version allégée du module [[Module_Ultimatepdf_FR|UltimatePDF]]''' : elle couvre uniquement les factures. Pour les devis, commandes, contrats, expéditions, notes de frais, interventions, projets, produits/nomenclatures ou documents fournisseurs, la version complète UltimatePDF est nécessaire.


===Two levels of configuration===
===Deux niveaux de configuration===


The module is built around two notions that should not be confused<span> </span>:
Le module s'articule autour de deux notions à ne pas confondre<span> </span>:


*The '''Design''' (''Models'' tab) defines '''what the document looks like'''<span> </span>: colours, margins, logo, company alias, page background, column widths. Several Designs can coexist, only one is active by default (<code>ULTIMATE_DESIGN</code> constant), and a selector at the top right of the application lets you switch instantly.
*Le '''Design''' (onglet ''Modèles'') définit '''à quoi ressemble''' le document<span> </span>: couleurs, marges, logo, alias société, fond de page, largeur des colonnes. Plusieurs Designs peuvent coexister, un seul est actif par défaut (constante <code>ULTIMATE_DESIGN</code>), et un sélecteur en haut à droite de l'application permet d'en changer instantanément.
*The '''Options''' and '''Invoices''' pages decide '''what is shown''' on the document<span> </span>: visible columns, address blocks, legal mentions, printed signatures, and so on. They do not affect the graphic design.
*Les pages '''Options''' et '''Factures''' décident '''ce qui s'affiche''' sur le document<span> </span>: colonnes visibles, blocs d'adresses, mentions légales, signatures imprimées, etc. Elles ne touchent pas à l'habillage graphique.


===Graphic customisation (Designs)===
===Personnalisation graphique (Designs)===


*'''Page background'''<span> </span>: background image or background PDF (pre-designed letterhead), with transparency and X/Y positioning.
*'''Fond de page'''<span> </span>: image de fond ou PDF de fond (papier à en-tête déjà maquetté), avec transparence et positionnement X/Y.
*'''Header'''<span> </span>: logo height and width, second logo (partner, certification), sender block width with drag-and-drop preview and a '''French postal standard window envelope''' preset.
*'''En-tête'''<span> </span>: hauteur et largeur du logo, second logo (partenaire, certification), largeur du bloc expéditeur avec aperçu glisser-déposer et préréglage '''enveloppe à fenêtre norme postale française'''.
*'''Company alias'''<span> </span>: prints a company name, address, share capital or VAT number different from the actual legal entity — useful for a trade name or a subsidiary.
*'''Alias société'''<span> </span>: permet d'afficher sur le document une raison sociale, une adresse, un capital ou un n° de TVA différents de l'entité juridique réelle — utile pour une marque commerciale ou une filiale.
*'''Margins and columns'''<span> </span>: PDF margins and the width of each column of the lines table (reference, image, date, type, project, VAT, unit price, quantity, unit, discount), each one resizable with the mouse on a graphic preview.
*'''Marges et colonnes'''<span> </span>: marges du PDF et largeur de chaque colonne du tableau de lignes (référence, image, date, type, projet, TVA, PU, quantité, unité, remise), chacune redimensionnable à la souris sur un aperçu graphique.
*'''Footer'''<span> </span>: font size, height reserved for free text, text and background colours.
*'''Pied de page'''<span> </span>: taille de police, hauteur réservée au texte libre, couleurs du texte et du fond.
*'''Font'''<span> </span>: document font selection (DejaVuSans for extended or Cyrillic character sets).
*'''Police'''<span> </span>: choix de la police du document (DejaVuSans pour les jeux de caractères étendus ou cyrilliques).


Every block of the form has its own '''Save''' button<span> </span>: you validate block by block without losing your input in the others.
Chaque bloc du formulaire possède son propre bouton '''Enregistrer'''<span> </span>: vous validez bloc par bloc sans perdre votre saisie sur les autres.


===Invoice content===
===Contenu de la facture===


*Line columns<span> </span>: numbering, product photo, unit price excl. tax, discount, unit price after discount, quantity, weight and total weight, unit.
*Colonnes de lignes<span> </span>: numérotation, photo produit, PU HT, remise, PU après remise, quantité, poids et poids total, unité.
*Address blocks<span> </span>: recipient, customer and sales representative details, professional IDs (company registration numbers...), intra-community VAT number, vertical stacking of contact blocks.
*Blocs d'adresses<span> </span>: coordonnées destinataire, client, commercial suiveur, identifiants professionnels (SIRET...), n° de TVA intracommunautaire, empilement vertical des blocs de contacts.
*Layout<span> </span>: header not repeated on every page, folding mark, text next to the date, paper format.
*Mise en page<span> </span>: en-tête non répété sur chaque page, repère de pliage, texte associé à la date, format de papier.
*Invoice specific<span> </span>: linked shipments, payment terms, situation invoice, online payment link, customer outstanding amount, amount in words, total incl. tax line, generation without the VAT column.
*Spécifique factures<span> </span>: expéditions liées, conditions de paiement, facture de situation, lien de paiement en ligne, encours client, montant en toutes lettres, ligne de total TTC, génération sans colonne TVA.
*'''Printed''' signatures<span> </span>: manager signature on the document and sales representative signature in the note. These are '''images''' added to the PDF, not to be confused with the cryptographic signature described below.
*Signatures '''imprimées'''<span> </span>: signature du responsable sur le document et signature du commercial suiveur dans la note. Ce sont des '''images''' ajoutées au PDF, à ne pas confondre avec la signature cryptographique décrite plus bas.


===PDF merging and GSC===
===Fusion de PDF et CGV===


*'''GSC'''<span> </span>: a general sales conditions PDF file is uploaded from the ''Options'' page and appended to the invoice, with an optional default preselection.
*'''CGV'''<span> </span>: un fichier de conditions générales de vente est téléversé depuis la page ''Options'' puis ajouté à la suite de la facture, avec présélection par défaut possible.
*'''Additional files'''<span> </span>: once the matching option is enabled on the ''Invoices'' page, one or several arbitrary PDF files can be merged into the document straight from the invoice card.
*'''Fichiers additionnels'''<span> </span>: après activation de l'option correspondante sur la page ''Factures'', un ou plusieurs PDF quelconques peuvent être fusionnés au document depuis la fiche de la facture.


===Electronic signature of invoices (PAdES)===
===Signature électronique des factures (PAdES)===


UltimateInvoice can apply a '''digital signature''' to the PDF as it is generated. It guarantees authenticity to the recipient (the document really comes from you) and integrity (it has not been modified since). Adobe Acrobat Reader shows it in its ''Signatures'' panel, and a '''visible signature box''' is drawn at the bottom right of the last page.
UltimateInvoice peut apposer une '''signature numérique''' sur le PDF au moment de sa génération. Elle garantit au destinataire l'authenticité (le document vient bien de vous) et l'intégrité (il n'a pas été modifié depuis). Adobe Acrobat Reader l'affiche dans son panneau ''Signatures'', et un '''cadre de signature visible''' est dessiné en bas à droite de la dernière page.


{| class="wikitable"
{| class="wikitable"
! Aspect !! Detail
! Aspect !! Détail
|-
|-
| What the feature does || Detached PKCS#7 cryptographic signature, equivalent to '''PAdES-B-B''', natively embedded in the PDF, with a visible and clickable box
| Ce que la fonctionnalité fait || Signature cryptographique PKCS#7 détachée, équivalent '''PAdES-B-B''', intégrée nativement au PDF, avec cadre visible et cliquable
|-
|-
| What it does not do || No qualified timestamp (RFC 3161), no LTV/long-term archiving, '''no qualified eIDAS legal value'''
| Ce qu'elle ne fait pas || Pas d'horodatage qualifié (RFC 3161), pas de LTV/archivage long terme, '''pas de valeur probante eIDAS qualifiée'''
|-
|-
| What it does not replace || Neither electronic invoicing (Factur-X / PDF-A3), nor a qualified signature issued by a trust service provider
| Ce qu'elle ne remplace pas || Ni la facturation électronique (Factur-X / PDF-A3), ni une signature qualifiée délivrée par un prestataire de confiance
|}
|}


Accepted certificate formats<span> </span>: '''<code>.pem</code>, <code>.crt</code>, <code>.p12</code>, <code>.pfx</code>'''. The file must contain '''both the certificate and the private key'''. It is stored in the Dolibarr ''documents'' directory, outside the module web folder<span> </span>: it therefore cannot be downloaded from a browser.
Formats de certificat acceptés<span> </span>: '''<code>.pem</code>, <code>.crt</code>, <code>.p12</code>, <code>.pfx</code>'''. Le fichier doit contenir '''le certificat et la clé privée'''. Il est stocké dans le répertoire ''documents'' de Dolibarr, hors du dossier web du module<span> </span>: il n'est donc pas téléchargeable depuis un navigateur.


'''Important limitation'''<span> </span>: merging additional files rewrites the PDF after it has been generated, which would break the signature. On an invoice where files are merged, the signature is therefore '''automatically skipped''' (a warning is written to the Dolibarr log) rather than produced invalid. GSC merging, on the other hand, remains compatible.
'''Limite importante'''<span> </span>: la fusion de fichiers additionnels réécrit le PDF après sa génération et casserait la signature. Sur une facture où des fichiers sont fusionnés, la signature est donc '''automatiquement ignorée''' (un avertissement est écrit dans le journal Dolibarr) plutôt que produite invalide. La fusion des CGV, elle, reste compatible.


===Barcodes, QR codes and Swiss QR-bill===
===Codes-barres, QR-codes et QR-facture suisse===


*'''Barcodes''' for products (EAN13 with check digit, CODE128, CODE39) and for third parties, at the top or at the bottom of the page.
*'''Codes-barres''' produits (EAN13 avec clé de contrôle, CODE128, CODE39) et codes-barres tiers, en haut ou en bas de page.
*'''QR codes''' for the company (MyCompany), the third party, or the invoice.
*'''QR-codes''' société (MyCompany), tiers, ou facture.
*'''SEPA payment QR code''' (EPC069-12 standard) and '''Swiss QR-bill''', including the full payment slip on a dedicated page. Please note<span> </span>: both settings belong to the '''Dolibarr core''' (''Home - Setup - PDF - Specific parameters tab'', ''Invoices'' section) and not to the module, which simply honours them when generating the document.
*'''QR-code de paiement SEPA''' (norme EPC069-12) et '''QR-facture suisse''' (Swiss QR-bill), y compris le bulletin de versement complet sur une page dédiée. Attention<span> </span>: ces deux réglages appartiennent au '''cœur de Dolibarr''' (''Accueil - Configuration - PDF - onglet Paramètres spécifiques'', section ''Factures'') et non au module, qui se contente de les respecter lors de la génération.


For the full Swiss payment slip, the payment mode must be '''bank transfer''', a bank account must be set on the invoice, your company address must be complete and the IBAN valid (QR-IBANs are not supported yet). The electronic signature box is deliberately drawn on the last page of the invoice, '''before''' the slip is appended, since the slip layout is normative.
Pour le bulletin de versement suisse complet, le mode de règlement doit être le '''virement bancaire''', un compte bancaire doit être renseigné sur la facture, l'adresse de votre société doit être complète et l'IBAN valide (les QR-IBAN ne sont pas encore gérés). Le cadre de signature électronique est volontairement dessiné sur la dernière page de la facture, '''avant''' l'ajout du bulletin, dont la mise en page est normative.


===Compatibility with the Milestone module===
===Compatibilité avec le module Milestone===


UltimateInvoice recognises the milestone lines of the [[Module_Milestone_EN|Milestone]] module (<code>product_type = 9</code>)<span> </span>: they are not handled as regular product lines when computing the line weight and the unit price after discount, and they keep their own formatting in the PDF.
UltimateInvoice reconnaît les lignes jalons du module [[Module_Jalon_FR|Milestone]] (<code>product_type = 9</code>)<span> </span>: elles ne sont pas traitées comme des lignes produit classiques dans le calcul du poids de ligne et du prix unitaire après remise, et conservent leur mise en forme propre dans le PDF.


===Built-in user guide===
===Guide d'utilisation intégré===


A complete guide, in French and in English, can be read directly from the module setup, '''User guide''' tab. It is updated with every release and details every option.
Un guide complet en français et en anglais est consultable directement depuis la configuration du module, onglet '''Guide d'utilisation'''. Il est mis à jour à chaque version et détaille chaque option.


''[[#Summary|⬆ Back to summary]]''
''[[#Sommaire|⬆ Retour au sommaire]]''


==Prerequisites==
==Prérequis==
'''Dolibarr<span> </span>:'''  Supported versions<span> </span>:
'''Dolibarr<span> </span>:'''  Versions supportées<span> </span>:


*'''23.x'''
*'''23.x'''
*'''24.x'''
*'''24.x'''


'''PHP<span> </span>:''' version 7.4 minimum. The full Swiss payment slip on a dedicated page requires PHP 8.1 or later.
'''PHP<span> </span>:''' version 7.4 minimum. Le bulletin de versement suisse complet en page dédiée nécessite PHP 8.1 ou supérieur.


'''Dolibarr modules<span> </span>:''' the '''Invoices''' module must be enabled.
'''Modules Dolibarr<span> </span>:''' le module '''Factures''' doit être activé.


=⚙️ Installation procedure=
=⚙️ Procédure d'installation=


===⚙️ Manual installation===
===⚙️ Installation manuelle===


#'''Download''' the module archive file (.zip).
#'''Télécharger''' le fichier archive du module (.zip).
#'''Put''' the file into the Dolibarr root directory.
#'''Placer''' le fichier dans le répertoire racine de Dolibarr.
#'''Unzip''' the file with the command<span> </span>:
#'''Décompresser''' le fichier zip avec la commande<span> </span>:


<code>unzip module_ultimateinvoice-X.0.0.zip</code>
<code>unzip module_ultimateinvoice-X.0.0.zip</code>


#'''Check''' that the correct module location is<span> </span>:
#'''Vérifier''' que l'emplacement correct du module est<span> </span>:


<code>htdocs/custom/ultimateinvoice</code>
<code>htdocs/custom/ultimateinvoice</code>


#'''The module is now available''' and can be enabled from Dolibarr.
#'''Le module est maintenant disponible''' et peut être activé depuis Dolibarr.


''[[#Summary|⬆ Back to summary]]''
''[[#Sommaire|⬆ Retour au sommaire]]''
=Setup=
=Configuration=
To use this module, you must first enable it. To do so, once logged in with an administrator account,
Pour utiliser ce module, il vous faut d'abord l'activer. Pour cela, après s'être connecté avec un compte administrateur,
go to the "'''Home - Setup - Modules'''" page.
allez sur la page "'''Accueil - Configuration - Modules'''".
The module appears in the "'''Atoo-Net'''" tab, click on "Enable".
Le module apparait dans l'onglet "'''Atoo-Net'''", cliquez sur "Activer".
An icon appears at the end of the module line, click on it to reach the setup pages specific to this module.
Un pictogramme apparait à la fin de la ligne du module, cliquez dessus pour accéder aux pages de paramétrage spécifiques à ce module.


All the administration pages of the module are protected by the <code>ultimateinvoice -> config</code> permission<span> </span>: only users holding this permission (usually administrators) can access them. Other users simply see the <code>ultimate_invoice</code> template appear in the "Models" dropdown list of the invoice card.
Toutes les pages d'administration du module sont protégées par le droit <code>ultimateinvoice -> config</code><span> </span>: seuls les utilisateurs disposant de ce droit (généralement les administrateurs) peuvent y accéder. Les autres utilisateurs voient simplement le modèle <code>ultimate_invoice</code> apparaître dans la liste déroulante "Modèles" de la fiche facture.


The setup consists of five tabs<span> </span>: '''Models''', '''Options''', '''Invoices''', '''User guide''' and '''About'''.
La configuration se compose de cinq onglets<span> </span>: '''Modèles''', '''Options''', '''Factures''', '''Guide d'utilisation''' et '''À propos'''.


==Models tab (Designs)==
==Onglet Modèles (Designs)==


This is where you build the graphic identity shared by all your documents.
C'est ici que se crée l'habillage graphique commun à tous vos documents.


[[File:slide_01_invoice.png|800px]]
[[File:slide_01_invoice.png|800px]]


  - The list shows every existing Design<span> </span>: label, description, border type, colours, status and a "Default" badge for the one currently in use.
  - La liste affiche tous les Designs existants<span> </span>: libellé, description, type de bordure, couleurs, statut et badge "Défaut" pour celui actuellement utilisé.


  - Click on '''Add a design''' to create a new one, or on the pencil to edit an existing design.
  - Cliquez sur '''Ajouter un design''' pour en créer un nouveau, ou sur le crayon pour modifier un design existant.


[[File:slide_02_invoice.png|800px]]
[[File:slide_02_invoice.png|800px]]


  - Fill in block by block<span> </span>: template information and font, page background, header and logos, company alias, central block, margins and column widths, footer. '''Each block has its own Save button.'''
  - Renseignez bloc par bloc<span> </span>: informations du modèle et police, fond de page, en-tête et logos, alias société, bloc central, marges et largeurs de colonnes, pied de page. '''Chaque bloc dispose de son propre bouton Enregistrer.'''


  - A disabled Design no longer appears in selection lists. The "Master template" and the default Design cannot be deleted, so that document generation can never be broken.
  - Un Design désactivé n'apparaît plus dans les listes de sélection. Le "Modèle maître" et le Design par défaut ne peuvent pas être supprimés, afin de ne jamais casser la génération de documents.


'''Important'''<span> </span>: after modifying a Design, if the generated document does not seem to have changed, check that this Design is the one carrying the "Default" badge.
'''Important'''<span> </span>: après modification d'un Design, si le document généré ne semble pas avoir changé, vérifiez que c'est bien ce Design qui porte le badge "Défaut".


==Options tab (global settings)==
==Onglet Options (réglages globaux)==


These settings apply to every document, whatever the chosen Design<span> </span>: logos, address blocks and professional IDs, page background, line content, GSC, bank details, signing certificate, paper format.
Ces réglages s'appliquent à tous les documents, indépendamment du Design choisi<span> </span>: logos, blocs d'adresses et identifiants professionnels, fond de page, contenu des lignes, CGV, coordonnées bancaires, certificat de signature, format de papier.


[[File:slide_03_invoice.png|800px]]
[[File:slide_03_invoice.png|800px]]


Most settings are on/off switches applied immediately<span> </span>; the paper format and the professional IDs are validated with a dedicated '''Save''' button.
La plupart des réglages sont des interrupteurs on/off appliqués immédiatement<span> </span>; le format de papier et les identifiants professionnels se valident avec un bouton '''Enregistrer''' dédié.


===Uploading the GSC===
===Téléversement des CGV===


In the dedicated block, select your general sales conditions PDF file and send it. It will then appear in a dropdown list next to the '''Generate''' button of the invoice card, and can be preselected by default.
Dans le bloc dédié, sélectionnez votre fichier PDF de conditions générales de vente et envoyez-le. Il apparaîtra ensuite dans une liste déroulante près du bouton '''Générer''' de la fiche facture, et peut être présélectionné par défaut.


===Setting up the electronic signature===
===Mise en service de la signature électronique===


In the '''Signing certificate''' block, at the bottom of the Options page<span> </span>:
Dans le bloc '''Certificat de signature''', en bas de la page Options<span> </span>:


#'''Upload''' your certificate file (<code>.pem</code>, <code>.crt</code>, <code>.p12</code> or <code>.pfx</code>) containing both the certificate and the private key.
#'''Téléversez''' votre fichier certificat (<code>.pem</code>, <code>.crt</code>, <code>.p12</code> ou <code>.pfx</code>) contenant le certificat et la clé privée.
#'''Enter the reason''' for the signature (free text shown in the PDF signature properties, for instance "Invoice certified true").
#'''Renseignez le motif''' de la signature (texte libre visible dans les propriétés de signature du PDF, par exemple "Facture certifiée conforme").
#'''Enter the password''' of the private key if it is protected, then save.
#'''Renseignez le mot de passe''' de la clé privée si elle est protégée, puis enregistrez.
#'''Turn on''' the "Electronically sign the invoice PDF" switch.
#'''Activez''' l'interrupteur "Signer électroniquement le PDF de facture".
#'''Generate an invoice''' and open it in Acrobat Reader<span> </span>: the ''Signatures'' panel must show the signature and the visible box appears at the bottom right of the last page.
#'''Générez une facture''' et ouvrez-la dans Acrobat Reader<span> </span>: le panneau ''Signatures'' doit afficher la signature et le cadre visible apparaît en bas à droite de la dernière page.


Only one certificate at a time is taken into account<span> </span>: delete the old one before uploading a new one.
Un seul certificat à la fois est pris en compte<span> </span>: supprimez l'ancien avant d'en téléverser un nouveau.


For '''testing''', a self-signed certificate is enough<span> </span>:
Pour '''tester''', un certificat auto-signé suffit<span> </span>:


<code>openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout signature.key -out signature.crt</code>
<code>openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout signature.key -out signature.crt</code>
Line 173: Line 173:
<code>cat signature.crt signature.key > signature.pem</code>
<code>cat signature.crt signature.key > signature.pem</code>


Acrobat will then display the signature as "present but not trusted"<span> </span>: this is expected, since the authority is not recognised. In production, use a certificate issued by a certification authority.
Acrobat affichera alors la signature comme "présente mais non fiable"<span> </span>: c'est normal, l'autorité n'étant pas reconnue. En production, utilisez un certificat délivré par une autorité de certification.


'''To know before deploying'''<span> </span>: the private key password is stored in clear text in the Dolibarr constants table, as there is no native secret vault. Restrict access to the database and to backups accordingly, and apply strict file permissions on the certificate storage directory.
'''À savoir avant de déployer'''<span> </span>: le mot de passe de la clé privée est stocké en clair dans la table des constantes de Dolibarr, faute de coffre-fort de secrets natif. Restreignez l'accès à la base et aux sauvegardes en conséquence, et appliquez des droits fichiers stricts sur le répertoire de stockage du certificat.


==Invoices tab==
==Onglet Factures==


This page gathers the settings specific to the invoice content<span> </span>: addresses, barcodes and QR codes, linked project, header and layout, line columns, printed signatures, PDF merging and invoice specific settings (linked shipments, situation invoice, online payment link, customer outstanding amount, amount in words...).
Cette page regroupe les réglages propres au contenu de la facture<span> </span>: adresses, codes-barres et QR-codes, projet lié, en-tête et mise en page, colonnes de lignes, signatures imprimées, fusion de PDF et réglages spécifiques aux factures (expéditions liées, facture de situation, lien de paiement en ligne, encours client, montant en toutes lettres...).


[[File:slide_04_invoice.png|800px]]
[[File:slide_04_invoice.png|800px]]


==User guide tab==
==Onglet Guide d'utilisation==


Displays the complete module guide in the language of the interface (French or English). It is the reference documentation, more detailed than this page.
Affiche le guide complet du module dans la langue de l'interface (français ou anglais). C'est la documentation de référence, plus détaillée que cette page.


[[File:slide_05_invoice.png|800px]]
[[File:slide_05_invoice.png|800px]]


''[[#Summary|⬆ Back to summary]]''
''[[#Sommaire|⬆ Retour au sommaire]]''


=Usage=
=Utilisation=


  - Open the '''invoice''' card, then, in the '''Documents''' block at the bottom of the card, choose the '''<code>ultimate_invoice</code>''' template in the "Models" dropdown list and click on '''Generate'''.
  - Ouvrez la fiche de la '''facture''', puis, dans le bloc '''Documents''' en bas de fiche, choisissez le modèle '''<code>ultimate_invoice</code>''' dans la liste déroulante "Modèles" et cliquez sur '''Générer'''.


  - The PDF appears in the list of attached files<span> </span>: it can be downloaded, previewed or sent by e-mail.
  - Le PDF apparaît dans la liste des fichiers joints<span> </span>: il peut être téléchargé, prévisualisé ou envoyé par e-mail.


  - '''Switch Design quickly'''<span> </span>: use the dedicated selector in the menu at the top right of the application, without going back to the full setup.
  - '''Changer de Design rapidement'''<span> </span>: utilisez le sélecteur dédié dans le menu en haut à droite de l'application, sans repasser par la configuration complète.


  - '''Append the GSC'''<span> </span>: select the GSC file in the dropdown list next to the Generate button.
  - '''Ajouter les CGV'''<span> </span>: sélectionnez le fichier CGV dans la liste déroulante située près du bouton Générer.


  - '''Merge an additional PDF'''<span> </span>: once the option is enabled on the ''Invoices'' page, select the file(s) to merge from the invoice card. On those invoices, the electronic signature is automatically skipped.
  - '''Fusionner un PDF annexe'''<span> </span>: après activation de l'option sur la page ''Factures'', sélectionnez le ou les fichiers à fusionner depuis la fiche de la facture. Sur ces factures, la signature électronique est automatiquement ignorée.


==Troubleshooting==
==Dépannage==


{| class="wikitable"
{| class="wikitable"
! Symptom !! Likely cause
! Symptôme !! Cause probable
|-
|-
| The <code>ultimate_invoice</code> template is missing from the list || The UltimateInvoice module or the ''Invoices'' module is not enabled
| Le modèle <code>ultimate_invoice</code> n'apparaît pas dans la liste || Le module UltimateInvoice ou le module ''Factures'' n'est pas activé
|-
|-
| The document does not reflect the changes made to a Design || This Design is not the one carrying the "Default" badge
| Le document ne reflète pas les modifications d'un Design || Ce Design n'est pas celui qui porte le badge "Défaut"
|-
|-
| No signature and no visible box on the PDF || No certificate uploaded, or unrecognised extension
| Aucune signature ni cadre visible sur le PDF || Aucun certificat téléversé, ou extension non reconnue
|-
|-
| Log<span> </span>: ''skipped: additional files merging is active'' || Additional files are merged into this invoice, both features are mutually exclusive
| Journal<span> </span>: ''skipped: additional files merging is active'' || Des fichiers additionnels sont fusionnés à cette facture, les deux fonctions s'excluent
|-
|-
| Acrobat shows "signature not valid" || Self-signed certificate<span> </span>: expected while testing, use a certificate from a recognised authority in production
| Acrobat affiche "signature non valide" || Certificat auto-signé<span> </span>: normal en test, utilisez un certificat d'une autorité reconnue en production
|-
|-
| Log<span> </span>: ''Error getting private key'' || Private key password missing or wrong, or file without the private key
| Journal<span> </span>: ''Error getting private key'' || Mot de passe de la clé privée absent ou erroné, ou fichier sans clé privée
|-
|-
| The Swiss payment slip does not show up || See the <code>SwissQr*</code> messages in the Dolibarr log<span> </span>: payment mode other than bank transfer, non compliant address or IBAN, QR-IBAN not supported
| Le bulletin de versement suisse n'apparaît pas || Voir les messages <code>SwissQr*</code> dans le journal Dolibarr<span> </span>: mode de règlement autre que le virement, adresse ou IBAN non conformes, QR-IBAN non géré
|}
|}


The Dolibarr log ('''Home - Setup - Other - Logs''') traces every generation and every signature attempt.
Le journal Dolibarr ('''Accueil - Configuration - Autres - Journaux''') trace chaque génération et chaque tentative de signature.


''[[#Summary|⬆ Back to summary]]''
''[[#Sommaire|⬆ Retour au sommaire]]''

Revision as of 12:48, 28 July 2026

Sommaire

Retour index
Documentation développeur

File Doc dev.png

Retour index
Documentation Utilisateur
File Doc user.png

Informations


Module name UltimateInvoice
Editor / Editeur Logo atoonet.jpg
Download or buy page / Page achat ou téléchargement External module - www.dolistore.com
Status / Statut / Estado Stable
Prerequisites / Prérequis Module Factures activé - PHP 7.4 minimum

Dolibarr min version: See on Dolistore    Dolibarr max version: See on Dolistore

Last update date / Date mise à jour fiche / Fecha última actualización 2026-07-28
Note / Nota ⬆ Retour au sommaire

Fonctionnalités

UltimateInvoice remplace le modèle PDF natif de Dolibarr pour les factures par un modèle entièrement personnalisable, nommé ultimate_invoice. Véritable couteau suisse de la facture PDF, il permet de définir votre charte graphique (logo, couleurs, marges, fond de page, largeurs de colonnes), de choisir précisément ce qui s'affiche sur le document, d'y joindre vos CGV ou des PDF annexes, d'y ajouter des codes-barres et QR-codes, et de signer numériquement le fichier généré.

UltimateInvoice est la version allégée du module UltimatePDF : elle couvre uniquement les factures. Pour les devis, commandes, contrats, expéditions, notes de frais, interventions, projets, produits/nomenclatures ou documents fournisseurs, la version complète UltimatePDF est nécessaire.

Deux niveaux de configuration

Le module s'articule autour de deux notions à ne pas confondre :

  • Le Design (onglet Modèles) définit à quoi ressemble le document : couleurs, marges, logo, alias société, fond de page, largeur des colonnes. Plusieurs Designs peuvent coexister, un seul est actif par défaut (constante ULTIMATE_DESIGN), et un sélecteur en haut à droite de l'application permet d'en changer instantanément.
  • Les pages Options et Factures décident ce qui s'affiche sur le document : colonnes visibles, blocs d'adresses, mentions légales, signatures imprimées, etc. Elles ne touchent pas à l'habillage graphique.

Personnalisation graphique (Designs)

  • Fond de page : image de fond ou PDF de fond (papier à en-tête déjà maquetté), avec transparence et positionnement X/Y.
  • En-tête : hauteur et largeur du logo, second logo (partenaire, certification), largeur du bloc expéditeur avec aperçu glisser-déposer et préréglage enveloppe à fenêtre norme postale française.
  • Alias société : permet d'afficher sur le document une raison sociale, une adresse, un capital ou un n° de TVA différents de l'entité juridique réelle — utile pour une marque commerciale ou une filiale.
  • Marges et colonnes : marges du PDF et largeur de chaque colonne du tableau de lignes (référence, image, date, type, projet, TVA, PU, quantité, unité, remise), chacune redimensionnable à la souris sur un aperçu graphique.
  • Pied de page : taille de police, hauteur réservée au texte libre, couleurs du texte et du fond.
  • Police : choix de la police du document (DejaVuSans pour les jeux de caractères étendus ou cyrilliques).

Chaque bloc du formulaire possède son propre bouton Enregistrer : vous validez bloc par bloc sans perdre votre saisie sur les autres.

Contenu de la facture

  • Colonnes de lignes : numérotation, photo produit, PU HT, remise, PU après remise, quantité, poids et poids total, unité.
  • Blocs d'adresses : coordonnées destinataire, client, commercial suiveur, identifiants professionnels (SIRET...), n° de TVA intracommunautaire, empilement vertical des blocs de contacts.
  • Mise en page : en-tête non répété sur chaque page, repère de pliage, texte associé à la date, format de papier.
  • Spécifique factures : expéditions liées, conditions de paiement, facture de situation, lien de paiement en ligne, encours client, montant en toutes lettres, ligne de total TTC, génération sans colonne TVA.
  • Signatures imprimées : signature du responsable sur le document et signature du commercial suiveur dans la note. Ce sont des images ajoutées au PDF, à ne pas confondre avec la signature cryptographique décrite plus bas.

Fusion de PDF et CGV

  • CGV : un fichier de conditions générales de vente est téléversé depuis la page Options puis ajouté à la suite de la facture, avec présélection par défaut possible.
  • Fichiers additionnels : après activation de l'option correspondante sur la page Factures, un ou plusieurs PDF quelconques peuvent être fusionnés au document depuis la fiche de la facture.

Signature électronique des factures (PAdES)

UltimateInvoice peut apposer une signature numérique sur le PDF au moment de sa génération. Elle garantit au destinataire l'authenticité (le document vient bien de vous) et l'intégrité (il n'a pas été modifié depuis). Adobe Acrobat Reader l'affiche dans son panneau Signatures, et un cadre de signature visible est dessiné en bas à droite de la dernière page.

Aspect Détail
Ce que la fonctionnalité fait Signature cryptographique PKCS#7 détachée, équivalent PAdES-B-B, intégrée nativement au PDF, avec cadre visible et cliquable
Ce qu'elle ne fait pas Pas d'horodatage qualifié (RFC 3161), pas de LTV/archivage long terme, pas de valeur probante eIDAS qualifiée
Ce qu'elle ne remplace pas Ni la facturation électronique (Factur-X / PDF-A3), ni une signature qualifiée délivrée par un prestataire de confiance

Formats de certificat acceptés : .pem, .crt, .p12, .pfx. Le fichier doit contenir le certificat et la clé privée. Il est stocké dans le répertoire documents de Dolibarr, hors du dossier web du module : il n'est donc pas téléchargeable depuis un navigateur.

Limite importante : la fusion de fichiers additionnels réécrit le PDF après sa génération et casserait la signature. Sur une facture où des fichiers sont fusionnés, la signature est donc automatiquement ignorée (un avertissement est écrit dans le journal Dolibarr) plutôt que produite invalide. La fusion des CGV, elle, reste compatible.

Codes-barres, QR-codes et QR-facture suisse

  • Codes-barres produits (EAN13 avec clé de contrôle, CODE128, CODE39) et codes-barres tiers, en haut ou en bas de page.
  • QR-codes société (MyCompany), tiers, ou facture.
  • QR-code de paiement SEPA (norme EPC069-12) et QR-facture suisse (Swiss QR-bill), y compris le bulletin de versement complet sur une page dédiée. Attention : ces deux réglages appartiennent au cœur de Dolibarr (Accueil - Configuration - PDF - onglet Paramètres spécifiques, section Factures) et non au module, qui se contente de les respecter lors de la génération.

Pour le bulletin de versement suisse complet, le mode de règlement doit être le virement bancaire, un compte bancaire doit être renseigné sur la facture, l'adresse de votre société doit être complète et l'IBAN valide (les QR-IBAN ne sont pas encore gérés). Le cadre de signature électronique est volontairement dessiné sur la dernière page de la facture, avant l'ajout du bulletin, dont la mise en page est normative.

Compatibilité avec le module Milestone

UltimateInvoice reconnaît les lignes jalons du module Milestone (product_type = 9) : elles ne sont pas traitées comme des lignes produit classiques dans le calcul du poids de ligne et du prix unitaire après remise, et conservent leur mise en forme propre dans le PDF.

Guide d'utilisation intégré

Un guide complet en français et en anglais est consultable directement depuis la configuration du module, onglet Guide d'utilisation. Il est mis à jour à chaque version et détaille chaque option.

⬆ Retour au sommaire

Prérequis

Dolibarr : Versions supportées :

  • 23.x
  • 24.x

PHP : version 7.4 minimum. Le bulletin de versement suisse complet en page dédiée nécessite PHP 8.1 ou supérieur.

Modules Dolibarr : le module Factures doit être activé.

⚙️ Procédure d'installation

⚙️ Installation manuelle

  1. Télécharger le fichier archive du module (.zip).
  2. Placer le fichier dans le répertoire racine de Dolibarr.
  3. Décompresser le fichier zip avec la commande :

unzip module_ultimateinvoice-X.0.0.zip

  1. Vérifier que l'emplacement correct du module est :

htdocs/custom/ultimateinvoice

  1. Le module est maintenant disponible et peut être activé depuis Dolibarr.

⬆ Retour au sommaire

Configuration

Pour utiliser ce module, il vous faut d'abord l'activer. Pour cela, après s'être connecté avec un compte administrateur, allez sur la page "Accueil - Configuration - Modules". Le module apparait dans l'onglet "Atoo-Net", cliquez sur "Activer". Un pictogramme apparait à la fin de la ligne du module, cliquez dessus pour accéder aux pages de paramétrage spécifiques à ce module.

Toutes les pages d'administration du module sont protégées par le droit ultimateinvoice -> config : seuls les utilisateurs disposant de ce droit (généralement les administrateurs) peuvent y accéder. Les autres utilisateurs voient simplement le modèle ultimate_invoice apparaître dans la liste déroulante "Modèles" de la fiche facture.

La configuration se compose de cinq onglets : Modèles, Options, Factures, Guide d'utilisation et À propos.

Onglet Modèles (Designs)

C'est ici que se crée l'habillage graphique commun à tous vos documents.

Slide 01 invoice.png 

- La liste affiche tous les Designs existants : libellé, description, type de bordure, couleurs, statut et badge "Défaut" pour celui actuellement utilisé.

- Cliquez sur Ajouter un design pour en créer un nouveau, ou sur le crayon pour modifier un design existant.

Slide 02 invoice.png 

- Renseignez bloc par bloc : informations du modèle et police, fond de page, en-tête et logos, alias société, bloc central, marges et largeurs de colonnes, pied de page. Chaque bloc dispose de son propre bouton Enregistrer.

- Un Design désactivé n'apparaît plus dans les listes de sélection. Le "Modèle maître" et le Design par défaut ne peuvent pas être supprimés, afin de ne jamais casser la génération de documents.

Important : après modification d'un Design, si le document généré ne semble pas avoir changé, vérifiez que c'est bien ce Design qui porte le badge "Défaut".

Onglet Options (réglages globaux)

Ces réglages s'appliquent à tous les documents, indépendamment du Design choisi : logos, blocs d'adresses et identifiants professionnels, fond de page, contenu des lignes, CGV, coordonnées bancaires, certificat de signature, format de papier.

Slide 03 invoice.png

La plupart des réglages sont des interrupteurs on/off appliqués immédiatement ; le format de papier et les identifiants professionnels se valident avec un bouton Enregistrer dédié.

Téléversement des CGV

Dans le bloc dédié, sélectionnez votre fichier PDF de conditions générales de vente et envoyez-le. Il apparaîtra ensuite dans une liste déroulante près du bouton Générer de la fiche facture, et peut être présélectionné par défaut.

Mise en service de la signature électronique

Dans le bloc Certificat de signature, en bas de la page Options :

  1. Téléversez votre fichier certificat (.pem, .crt, .p12 ou .pfx) contenant le certificat et la clé privée.
  2. Renseignez le motif de la signature (texte libre visible dans les propriétés de signature du PDF, par exemple "Facture certifiée conforme").
  3. Renseignez le mot de passe de la clé privée si elle est protégée, puis enregistrez.
  4. Activez l'interrupteur "Signer électroniquement le PDF de facture".
  5. Générez une facture et ouvrez-la dans Acrobat Reader : le panneau Signatures doit afficher la signature et le cadre visible apparaît en bas à droite de la dernière page.

Un seul certificat à la fois est pris en compte : supprimez l'ancien avant d'en téléverser un nouveau.

Pour tester, un certificat auto-signé suffit :

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout signature.key -out signature.crt

cat signature.crt signature.key > signature.pem

Acrobat affichera alors la signature comme "présente mais non fiable" : c'est normal, l'autorité n'étant pas reconnue. En production, utilisez un certificat délivré par une autorité de certification.

À savoir avant de déployer : le mot de passe de la clé privée est stocké en clair dans la table des constantes de Dolibarr, faute de coffre-fort de secrets natif. Restreignez l'accès à la base et aux sauvegardes en conséquence, et appliquez des droits fichiers stricts sur le répertoire de stockage du certificat.

Onglet Factures

Cette page regroupe les réglages propres au contenu de la facture : adresses, codes-barres et QR-codes, projet lié, en-tête et mise en page, colonnes de lignes, signatures imprimées, fusion de PDF et réglages spécifiques aux factures (expéditions liées, facture de situation, lien de paiement en ligne, encours client, montant en toutes lettres...).

Slide 04 invoice.png

Onglet Guide d'utilisation

Affiche le guide complet du module dans la langue de l'interface (français ou anglais). C'est la documentation de référence, plus détaillée que cette page.

Slide 05 invoice.png

⬆ Retour au sommaire

Utilisation

- Ouvrez la fiche de la facture, puis, dans le bloc Documents en bas de fiche, choisissez le modèle ultimate_invoice dans la liste déroulante "Modèles" et cliquez sur Générer.

- Le PDF apparaît dans la liste des fichiers joints : il peut être téléchargé, prévisualisé ou envoyé par e-mail.

- Changer de Design rapidement : utilisez le sélecteur dédié dans le menu en haut à droite de l'application, sans repasser par la configuration complète.

- Ajouter les CGV : sélectionnez le fichier CGV dans la liste déroulante située près du bouton Générer.

- Fusionner un PDF annexe : après activation de l'option sur la page Factures, sélectionnez le ou les fichiers à fusionner depuis la fiche de la facture. Sur ces factures, la signature électronique est automatiquement ignorée.

Dépannage

Symptôme Cause probable
Le modèle ultimate_invoice n'apparaît pas dans la liste Le module UltimateInvoice ou le module Factures n'est pas activé
Le document ne reflète pas les modifications d'un Design Ce Design n'est pas celui qui porte le badge "Défaut"
Aucune signature ni cadre visible sur le PDF Aucun certificat téléversé, ou extension non reconnue
Journal : skipped: additional files merging is active Des fichiers additionnels sont fusionnés à cette facture, les deux fonctions s'excluent
Acrobat affiche "signature non valide" Certificat auto-signé : normal en test, utilisez un certificat d'une autorité reconnue en production
Journal : Error getting private key Mot de passe de la clé privée absent ou erroné, ou fichier sans clé privée
Le bulletin de versement suisse n'apparaît pas Voir les messages SwissQr* dans le journal Dolibarr : mode de règlement autre que le virement, adresse ou IBAN non conformes, QR-IBAN non géré

Le journal Dolibarr (Accueil - Configuration - Autres - Journaux) trace chaque génération et chaque tentative de signature.

⬆ Retour au sommaire

Retrieved from "https://wiki.dolibarr.org/index.php?title=Module_UltimateInvoice_FR&oldid=66801"