Prérequis

  • Système : Microsoft Windows.
  • Microsoft Excel, version de bureau : Factur-Xray pilote Excel pour ouvrir les exemples, suivre la cellule active et lire les valeurs. Excel en ligne ne convient pas.
  • Aucune connexion Internet ni aucun compte n'est nécessaire.

Installation

  1. Téléchargez l'archive de la dernière version sur la page des versions GitHub.
  2. Décompressez-la dans le dossier de votre choix (par exemple Documents\Factur-Xray). Le dossier contient l'exécutable, le répertoire exemples (index et classeurs), le répertoire factures où seront écrites les factures générées, ainsi que les fichiers de licence.
  3. Lancez l'exécutable. Aucune installation n'est requise ; Windows peut afficher un avertissement lors du premier lancement d'une application téléchargée.

L'interface

Factur-Xray se présente comme une petite fenêtre placée dans le coin inférieur droit de l'écran, qui reste à côté d'Excel :

Les commandes de la fenêtre principale
CommandeRôle
OuvrirOuvre le classeur d'index ou l'une des neuf familles d'exemples
AideOuvre la documentation en ligne
Générer la factureProduit le Factur-X et le XML de l'onglet actif
Rayons X (BT et XML)Ouvre le panneau qui décrit la cellule sélectionnée

Une zone de messages, sous les boutons, indique le résultat des opérations. À la fermeture, Factur-Xray demande confirmation car les classeurs d'exemples ouverts sont fermés sans enregistrement.

Utilisation pas à pas

  1. Ouvrir un classeur. Choisissez l'index pour une vue d'ensemble, ou directement une famille. Le classeur s'ouvre en lecture seule : vous pouvez modifier des valeurs pour expérimenter, les fichiers d'origine ne sont jamais écrasés.
  2. Choisir un cas. Chaque onglet Excel correspond à un cas ; son nom reprend le numéro et l'intitulé du cas.
  3. Passer aux rayons X. Ouvrez le panneau et cliquez dans la facture : le panneau suit la cellule active (voir ci-dessous).
  4. Générer la facture. Le bouton produit le Factur-X de l'onglet actif, puis l'ouvre dans votre lecteur PDF.
  5. Contrôler. Ouvrez la facture générée dans Fchecker pour la valider.

Lire un onglet d'exemple

Chaque onglet comporte deux zones.

La facture

La zone imprimable présente la facture telle qu'un client la recevrait : blocs d'en-tête (vendeur, acheteur, références, livraison, paiement), tableau des lignes, récapitulatif de TVA, totaux et notes. Les montants sont calculés par des formules Excel : modifier une quantité ou un prix met à jour toute la facture.

Les données hors impression

À droite de la facture, hors de la zone imprimée, figurent :

  • les données présentes dans le XML mais pas sur le papier : l'identifiant de spécification (BT-24), les adresses électroniques du vendeur (BT-34) et de l'acheteur (BT-49) ;
  • la fiche du cas : descriptif, type de document, cadre de facturation, référence du cas d'usage, profil et points d'attention avec les règles concernées (par exemple BR-FR-05 pour les notes obligatoires).

Les conventions

  • Chaque cellule de donnée est une cellule nommée d'après son BT : la cellule du numéro de facture s'appelle BT_1, celle du nom du vendeur BT_27. Le nom apparaît dans la zone Nom d'Excel.
  • Chaque en-tête de colonne des tableaux se termine par l'identifiant de la donnée, par exemple « Quantité (BT-129) ».
  • Le XML reprend les valeurs telles qu'elles sont affichées, sans aucun recalcul : une erreur saisie dans Excel se retrouve dans la facture électronique.

Le panneau Rayons X

Le panneau « Rayons X — le BT derrière la cellule » reste au premier plan et se met à jour lorsque vous changez de cellule. Pour la cellule active, il affiche :

  • l'identifiant de la donnée (BT ou BG) et son libellé ;
  • son bloc, le profil minimal qui la contient et le nom de la cellule ;
  • un aperçu de la balise CII avec la valeur courante ;
  • le chemin XML de la balise ;
  • le commentaire propre au cas lorsque la donnée joue un rôle particulier dans l'exemple étudié.

Sur une cellule de la fiche du cas, le panneau affiche le titre, les codes et le profil du cas.

L'interrupteur « Colorer les données par bloc et ajouter une note au survol » attribue une couleur à chaque bloc de données (la légende apparaît dans le panneau) et pose sur chaque cellule une note visible au survol. Désactivez-le pour retrouver l'aspect d'origine.

Excel est occupé ?

Pendant une saisie dans une cellule, Excel n'accepte pas d'être piloté. Validez ou annulez la saisie en cours, puis réessayez.

Générer un Factur-X

Le bouton Générer la facture lit l'onglet actif et produit deux fichiers :

factures\<classeur>\<onglet>.pdf   Factur-X : PDF/A-3 avec le XML CII intégré
factures\<classeur>\<onglet>.xml   le XML CII seul

Le profil est déterminé automatiquement :

  • EN 16931 lorsque seules des données de la norme européenne sont renseignées (identifiant urn:cen.eu:en16931:2017) ;
  • EXTENDED dès qu'une donnée étendue ou une extension française est renseignée (identifiant urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:extended).

Le PDF reçoit un profil colorimétrique sRGB et des métadonnées XMP cohérentes avec le XML, conformément aux exigences PDF/A-3 et Factur-X.

Aucune validation à la génération

Factur-Xray génère la facture correspondant à ce qui est saisi, même si ce contenu est incorrect. C'est voulu : on peut ainsi introduire une erreur et observer sa détection. Pour contrôler une facture, ouvrez-la dans Fchecker.

Catalogue des 50 cas

Le type de document correspond au code BT-3, le cadre de facturation à la nature de l'opération et au traitement du paiement (B pour les biens, S pour les services, M pour les opérations mixtes). Le cas 30 comporte deux documents (30a et 30b).

Les cas d'exemple de Factur-Xray
N°CasTypeCadreProfil
A. Factures de base
01Facture de vente de biens380B1EN 16931
02Facture de prestation de services, TVA à l'encaissement380S1EN 16931
03Facture de prestation de services, option TVA sur les débits380S1EN 16931
04Facture mixte biens et services380M1EN 16931
05Facture déjà payée à l'émission380B2EN 16931
06Facture multi-commandes, multi-livraisons380B1EXTENDED
07Facture périodique ou d'abonnement380S1EN 16931
B. Acomptes
08Facture d'acompte386S1EN 16931
09Facture d'acompte déjà encaissé386S2EN 16931
10Facture définitive après acompte380S4EN 16931
11Avoir sur facture d'acompte503S1EN 16931
C. Corrections : rectificatives, avoirs, notes de débit
12Facture rectificative384B1EN 16931
13Avoir d'annulation totale381B1EN 16931
14Avoir partiel (rabais, retour)381B1EN 16931
15Avoir de remise globale (RFA)262B1EN 16931
16Avoir net de taxe381B1EN 16931
17Note de débit380S1EN 16931
D. Affacturage
18Facture affacturée393B1EN 16931
19Avoir affacturé396B1EN 16931
20Facture rectificative affacturée472B1EN 16931
21Affacturage décidé après émission380B1EN 16931
E. Mandat de facturation et autofacturation
22Facture émise sous mandat (pour ordre et pour compte)380B1EXTENDED
23Autofacture389B1EN 16931
24Autofacture d'acompte500S1EN 16931
25Avoir autofacturé261B1EN 16931
26Autofacture rectificative471B1EN 16931
27Autofacture affacturée501B1EN 16931
28Autofacturation avec un particulier389B1EN 16931
29Autofacture bidirectionnelle389S9EXTENDED
30Autofacture compensée avec une facture croisée389B1EN 16931 / EXTENDED
F. Tiers payeurs et intermédiaires
31Facture payée par un tiers payeur380S1EXTENDED
32Facture prise en charge partiellement par un tiers380S1EXTENDED
33Facture à payer à un tiers bénéficiaire380B1EN 16931
34Facture reçue par un tiers pour le compte de l'acheteur380B1EXTENDED
35Facture avec débours380S1EN 16931
36Facture marketplace sous mandat380B1EXTENDED
G. BTP, sous-traitance, cotraitance
37Facture de sous-traitant en autoliquidation380S1EN 16931
38Facture de sous-traitant avec paiement direct380S5EXTENDED
39Facture du titulaire après paiement direct380S1EN 16931
40Facture de cotraitant380S6EXTENDED
41Demande de paiement de sous-traitance (B2G)380S3EXTENDED
H. TVA et régimes particuliers
42Facture avec escompte pour paiement anticipé380S1EN 16931
43Facture exonérée de TVA380S1EN 16931
44Facture en franchise en base de TVA380S1EN 16931
45Facture sous régime de TVA sur la marge380B1EN 16931
46Facture d'un membre d'assujetti unique380B1EN 16931
47Facture en devise étrangère380B1EN 16931
48Facture après ticket déjà déclaré en B2C380S7EN 16931
I. Structure de facture avancée
49Facture avec sous-lignes380B1EXTENDED
50Facture multi-vendeurs380S8EXTENDED

Limites connues

  • Factur-Xray ne valide pas les factures qu'il génère (voir Générer un Factur-X).
  • Le codage du cas 28 (autofacturation avec un particulier, sans SIREN) reste à confirmer : la facture générée ne passe pas tous les contrôles.
  • L'application nécessite Windows et Excel de bureau.

Travailler à partir des sources

Le code source est publié sur GitHub. Il nécessite Python 3.13 :

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
python main.py

Les tests, qui ne nécessitent pas Excel, vérifient le catalogue des données, le rendu et la validité XSD des factures à partir d'instantanés des exemples :

pytest generation/tests xray/tests

Les exemples sont décrits dans des fichiers YAML (un fichier par famille, limité à ce qui distingue chaque cas, plus un fichier commun pour les parties fictives) et les classeurs Excel en sont générés. Le README du dépôt détaille la procédure de régénération et de compilation de l'exécutable.

Licence

Factur-Xray est distribué sous licence Apache 2.0 par Siadeo. Il s'appuie sur des composants open source tiers, dont la liste et les licences sont fournies avec l'application. Toutes les données des exemples (entreprises, SIREN, numéros de TVA, IBAN) sont fictives ; les identifiants ont des clés de contrôle valides pour passer les vérifications de format.