facturx

package module

v0.2.0 Latest Latest Go to latest Published: Jul 31, 2026 License: MIT Imports: 10 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/surfeur5/facturx-go

Links

Open Source Insights

README ¶

facturx-go

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.2.0 — Attach() et Generate() opérationnels. Le pipeline complet (Generate XML CII typé → Attach dans un PDF) produit un fichier reconnu comme CrossIndustryInvoice par le validator SuperPDP, sans erreurs XSD. Extract() et Validate() restent à faire.

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 Generate() — génération XML CII depuis struct Go typée (ordre XSD garanti par les types)
v0.3.0 Extract() — extraction du XML embarqué
v0.3.0 Validate() — validation XSD + EN16931 + BR-FR
v0.4.0 Conformité PDF/A-3 stricte (metadata XMP, OutputIntent, fonts embarqués)

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.

Constants ¶

View Source

const GuidelineFacturXEN16931 = "urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:en16931"

GuidelineFacturXEN16931 est l'identifiant EN16931 profil Factur-X.

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.

func Generate ¶ added in v0.2.0

func Generate(inv Invoice) ([]byte, error)

Generate produit le XML CII conforme EN 16931 pour l'Invoice fournie. L'ordre des éléments est garanti conforme au schéma XSD par la structure des types internes xml*.

Retourne le XML avec le prologue <?xml version="1.0" encoding="UTF-8"?>.

Types ¶

type Address ¶ added in v0.2.0

type Address struct {
	LineOne     string // BT-35 / BT-50
	LineTwo     string // BT-36 / BT-51, optionnel
	PostCode    string // BT-38 / BT-53
	CityName    string // BT-37 / BT-52
	CountryCode string // BT-40 / BT-55 (alpha-2)
}

Address = PostalTradeAddress (BG-5 / BG-8).

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 Invoice ¶ added in v0.2.0

type Invoice struct {
	// GuidelineID identifie le profil Factur-X. Défaut = EN 16931 conformant.
	// Cf. spec Factur-X 1.0.7 § 3 / BT-24.
	GuidelineID string

	// BusinessProcess (BT-23), ex "A1". Optionnel.
	BusinessProcess string

	// BT-1 : numéro de facture.
	Number string
	// BT-3 : code type document (voir constants InvoiceType*).
	TypeCode InvoiceType
	// BT-2 : date d'émission.
	IssueDate time.Time

	// Notes rattachées à l'en-tête (BG-1). Optionnel.
	Notes []Note

	// Lignes de facture (BG-25). Ordre = ordre d'apparition.
	Lines []Line

	// Vendeur (BG-4).
	Seller Party
	// Acheteur (BG-7).
	Buyer Party

	// BT-5 : monnaie de facturation.
	Currency string
	// BT-9 : date d'échéance de paiement. Optionnel.
	DueDate *time.Time

	// Ventilation par taux TVA (BG-23). Une entrée par taux distinct.
	VATBreakdowns []VATBreakdown

	// Totaux monétaires (BG-22).
	Totals Totals
}

Invoice est le modèle sémantique EN 16931 d'une facture, agnostique de la représentation XML. Passer à Generate() pour obtenir le XML CII.

type InvoiceType ¶ added in v0.2.0

type InvoiceType string

InvoiceType est le code UNTDID 1001. Voir constants InvoiceType*.

const (
	// InvoiceTypeCommercial : facture commerciale (BT-3 = 380).
	InvoiceTypeCommercial InvoiceType = "380"
	// InvoiceTypeCreditNote : avoir (BT-3 = 381).
	InvoiceTypeCreditNote InvoiceType = "381"
)

type Line ¶ added in v0.2.0

type Line struct {
	// ID : identifiant local de ligne (BT-126), ex "1", "2".
	ID string
	// SellerAssignedID (BT-155) — référence article vendeur. Optionnel.
	SellerAssignedID string
	// ProductName (BT-153) — désignation.
	ProductName string
	// UnitPrice (BT-146) — prix unitaire net HT.
	UnitPrice float64
	// Quantity (BT-129) — quantité facturée.
	Quantity float64
	// UnitCode (BT-130) — unité UN/ECE Rec 20, défaut "C62" (unité).
	UnitCode string
	// VATRate (BT-152) — taux TVA en pourcentage (20.0 = 20 %).
	VATRate float64
	// VATCategoryCode (BT-151) — S / Z / E / AE / K / G / O / L / M.
	VATCategoryCode string
	// LineTotal (BT-131) — total net HT de la ligne.
	LineTotal float64
}

Line est une ligne de facture (BG-25).

type Note ¶ added in v0.2.0

type Note struct {
	// Content : contenu textuel (BT-22).
	Content string
	// SubjectCode : code sujet (BT-21), ex "AAB", "PMT", "PMD". Optionnel.
	SubjectCode string
}

Note attachée à l'en-tête.

type Party ¶ added in v0.2.0

type Party struct {
	// Name obligatoire (BT-27 / BT-44).
	Name string
	// PostalAddress obligatoire pour EN 16931.
	PostalAddress Address
	// VATID (BT-31 / BT-48), format ISO 3166 alpha-2 + n° (ex "FR12345678901").
	// Utilisé comme schemeID="VA" dans SpecifiedTaxRegistration.
	VATID string
	// LegalID (BT-30 / BT-47) — SIREN, DUNS, etc. Optionnel.
	LegalID string
	// LegalIDScheme (BT-30-1 / BT-47-1) — "0002" pour SIREN. Requis si LegalID.
	LegalIDScheme string
}

Party représente le vendeur ou l'acheteur.

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 Totals ¶ added in v0.2.0

type Totals struct {
	// LineTotal (BT-106) — somme des LineTotal.
	LineTotal float64
	// TaxBasisTotal (BT-109) — base HT totale.
	TaxBasisTotal float64
	// TaxTotal (BT-110) — TVA totale.
	TaxTotal float64
	// GrandTotal (BT-112) — total TTC.
	GrandTotal float64
	// DuePayable (BT-115) — net à payer.
	DuePayable float64
}

Totals contient les totaux monétaires (BG-22).

type VATBreakdown ¶ added in v0.2.0

type VATBreakdown struct {
	// CalculatedAmount (BT-117) — montant TVA calculé pour la catégorie.
	CalculatedAmount float64
	// TypeCode : toujours "VAT" pour la TVA française.
	TypeCode string
	// BasisAmount (BT-116) — base HT taxée.
	BasisAmount float64
	// CategoryCode (BT-118) — S / Z / E / AE / K / G / O / L / M.
	CategoryCode string
	// RatePercent (BT-119) — taux en pourcentage.
	RatePercent float64
	// ExemptionReason (BT-120) — texte motif d'exonération (ex "Art. 293 B CGI"
	// pour la franchise en base). Optionnel.
	ExemptionReason string
}

VATBreakdown est une ligne de la ventilation TVA (BG-23).

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 :

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