Help us shape the future of Go! Take the 2026 Go Developer Survey

facturx

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 29, 2026 License: MIT Imports: 8 Imported by: 0

README

facturx-go

Go Reference Go Report Card

Bibliothèque Go pour manipuler des factures Factur-X (norme franco-allemande de facturation électronique hybride, PDF/A-3 avec XML CII embarqué, EN 16931).

Status : v0.1.0 — Attach() opérationnel, validé end-to-end contre le validator SuperPDP (le PDF post-processé passe le check basique « factur-x.xml embarqué trouvé »). Extract() et Validate() restent à faire (roadmap v0.2.0).

Contexte

La réforme française de la facturation électronique (obligation généralisée dès septembre 2026 pour la réception, septembre 2027 pour l'émission PME) impose l'utilisation de formats structurés pour les échanges B2B. Factur-X est le format hybride le plus répandu en France : un PDF humainement lisible avec un XML CII (Cross Industry Invoice) embarqué comme fichier associé (AssociatedFile).

À la différence de Python (akretion/factur-x), Node (jslno/node-zugferd) ou PHP (atgp/factur-x), il n'existe pas de bibliothèque Go mature pour Factur-X. Cette lib comble ce manque.

Objectifs

  • Prendre un PDF classique (généré par gofpdf, unipdf, chromedp, etc.) et y embarquer un XML CII en tant que fichier associé (/AF, /AFRelationship)
  • Générer un XML CII conforme EN 16931 à partir d'une struct Go simple
  • Valider un Factur-X existant contre les règles XSD + EN16931 + BR-FR
  • Extraire le XML depuis un Factur-X reçu

Installation

go get github.com/surfeur5/facturx-go

Usage

Attacher un XML CII à un PDF existant
import "github.com/surfeur5/facturx-go"

// Ton PDF de base + le XML CII conforme EN 16931
pdfBytes := ...   // bytes du PDF de base (gofpdf, etc.)
xmlBytes := ...   // XML CII généré par ton code

// Attacher en tant que fichier associé Factur-X
facturxPDF, err := facturx.Attach(pdfBytes, xmlBytes, facturx.AttachOptions{
    Filename:       "factur-x.xml",
    Relationship:   facturx.RelationshipAlternative,
    ConformanceLevel: facturx.LevelEN16931,
})
Extraire le XML d'un Factur-X reçu
xmlBytes, err := facturx.Extract(pdfBytes)
Valider un Factur-X
report, err := facturx.Validate(pdfBytes)
if !report.IsValid {
    for _, f := range report.Failures {
        fmt.Println(f.Message)
    }
}

Niveaux de conformité Factur-X

Niveau Description
MINIMUM Champs minimaux (facture simplifiée)
BASIC_WL Basic sans lignes de facture (WL = Without Lines)
BASIC Basic avec lignes
EN16931 Conforme EN 16931 (norme européenne) — niveau visé par défaut
EXTENDED Extension française avec champs additionnels

Statut d'implémentation

  • v0.1.0 Attach() — MVP : ajout de /AF + /AFRelationship sur PDF existant, testé contre le validator SuperPDP
  • v0.2.0 Extract() — extraction du XML embarqué
  • v0.2.0 Validate() — validation XSD + EN16931 + BR-FR
  • v0.3.0 Conformité PDF/A-3 stricte (metadata XMP, OutputIntent, fonts embarqués)
  • v0.4.0 Generate() — génération XML CII depuis struct Go typée

Contexte de création

Extrait du projet ev2c (plateforme e-commerce EV2C — Maison EV2C, Sotteville-les-Rouen). L'audit du générateur Factur-X interne (basé sur gofpdf) contre le validator SuperPDP a révélé l'absence des markers /AF requis par la spec. Cette lib est le fix propre, open-sourcé.

License

MIT — voir LICENSE.

Références

Documentation

Overview

Package facturx manipule des factures Factur-X — le format hybride franco-allemand de facturation électronique (PDF/A-3 avec XML CII embarqué comme fichier associé, conforme EN 16931).

Cette bibliothèque comble l'absence de lib Go mature pour Factur-X (les implémentations de référence sont en Python, Node, PHP et .NET).

Statut : WIP. Ne pas utiliser en production tant qu'une release n'est pas taggée sur https://github.com/surfeur5/facturx-go.

Index

Constants

This section is empty.

Variables

View Source 
var ErrNotImplemented = errors.New("facturx: not implemented yet — see roadmap")

ErrNotImplemented indique qu'une fonction n'est pas encore implémentée dans la version actuelle. Suivre la roadmap dans README.md.

Functions

func Attach 

func Attach(pdfBytes, xmlBytes []byte, opts AttachOptions) ([]byte, error)

Attach embarque un XML CII dans un PDF existant en tant que fichier associé Factur-X. Le PDF de sortie contient les markers /AF (catalog) et /AFRelationship (filespec) requis par la spec PDF/A-3 § 6.8.

pdfBytes : bytes du PDF de base (généré par gofpdf, unipdf, chromedp…). xmlBytes : XML CII conforme EN 16931 (généré par l'appelant).

Si le PDF de base contient déjà un attachment du même nom, il est remplacé. Le PDF résultant n'est pas garanti PDF/A-3 stricte (XMP metadata, OutputIntent, fonts embarquées) — c'est la roadmap v0.3.0.

func Extract 

func Extract(pdfBytes []byte) ([]byte, error)

Extract retourne le XML CII embarqué dans un Factur-X. Cherche d'abord un fichier associé avec /AFRelationship, puis fallback sur l'attachment nommé "factur-x.xml" ou "xrechnung.xml".

Statut : WIP.

Types

type AttachOptions 

type AttachOptions struct {
	// Filename du fichier embarqué. Défaut : "factur-x.xml".
	Filename string

	// Description humaine de l'attachment. Défaut : "Factur-X invoice".
	Description string

	// Relationship = /AFRelationship du filespec. Défaut : Alternative
	// (recommandation Factur-X : le XML et le PDF sont équivalents).
	Relationship Relationship

	// ConformanceLevel du XML CII. Utilisé pour les métadonnées XMP quand
	// PDF/A-3 sera pleinement supporté (roadmap). Défaut : LevelEN16931.
	ConformanceLevel ConformanceLevel

	// MimeType du fichier. Défaut : "application/xml" (Factur-X exige text/xml
	// ou application/xml selon les versions).
	MimeType string
}

AttachOptions paramètre l'opération Attach.

type ConformanceLevel 

type ConformanceLevel string

ConformanceLevel indique le profil Factur-X du XML CII embarqué. Voir FNFE-MPE Factur-X spec §2.2. 

const (
	// LevelMinimum — profil minimal (comptable simplifié, non EN 16931).
	LevelMinimum ConformanceLevel = "MINIMUM"

	// LevelBasicWL — Basic sans lignes (WL = Without Lines).
	LevelBasicWL ConformanceLevel = "BASIC WL"

	// LevelBasic — Basic avec lignes (subset EN 16931).
	LevelBasic ConformanceLevel = "BASIC"

	// LevelEN16931 — conforme EN 16931 (norme européenne). Niveau visé par
	// défaut pour la facturation électronique française B2B.
	LevelEN16931 ConformanceLevel = "EN 16931"

	// LevelExtended — EN 16931 + extensions françaises.
	LevelExtended ConformanceLevel = "EXTENDED"
)

type Relationship 

type Relationship string

Relationship est le type de relation entre le PDF et le fichier associé (attribut /AFRelationship du filespec dans le catalog PDF). Voir ISO 14289-1 (PDF/A-3) et FNFE-MPE Factur-X spec. 

const (
	// RelationshipAlternative — le fichier associé est une représentation
	// alternative du contenu (cas normal pour Factur-X : le XML CII et le PDF
	// représentent la même facture).
	RelationshipAlternative Relationship = "Alternative"

	// RelationshipData — le fichier contient des données référencées par le PDF.
	RelationshipData Relationship = "Data"

	// RelationshipSource — le fichier est la source à partir de laquelle le PDF
	// a été généré.
	RelationshipSource Relationship = "Source"

	// RelationshipSupplement — le fichier complète le contenu du PDF.
	RelationshipSupplement Relationship = "Supplement"

	// RelationshipUnspecified — relation non spécifiée.
	RelationshipUnspecified Relationship = "Unspecified"
)

type ValidationFailure 

type ValidationFailure struct {
	Validator string // nom du validator (XSD, EN16931, BR-FR)
	Location  string // XPath ou emplacement dans le document
	Message   string
	Raw       string
}

ValidationFailure est un échec de validation (règle non respectée).

type ValidationMessage 

type ValidationMessage = ValidationFailure

ValidationMessage est un message informatif (warning, info).

type ValidationReport 

type ValidationReport struct {
	IsValid  bool
	Format   string // ex: "urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100"
	Failures []ValidationFailure
	Messages []ValidationMessage
}

ValidationReport est le résultat d'une validation Factur-X.

func Validate 

func Validate(pdfBytes []byte) (*ValidationReport, error)

Validate vérifie qu'un Factur-X est conforme :

  1. XSD Cross-Industry Invoice
  2. Schematron EN 16931
  3. Règles françaises BR-FR (PPF/Flux2)

Statut : WIP.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.