🇫🇷 facturex-py

mcp-name: io.github.kapturo-ai/facturex

L'atelier de facturation électronique française en Python — lire, valider, créer, gérer. Factur-X (CII), UBL 2.1, EN 16931. Offline-first, modulaire.

La réforme est en vigueur : réception obligatoire pour toutes les entreprises assujetties à la TVA depuis le 1er septembre 2026, émission pour les TPE/PME au 1er septembre 2027. facturex-py couvre tout le cycle : du fichier fournisseur qu'on vérifie… à la facture client qu'on émet.

pip install "facturex-py[all]"
facturex init                                    # atelier : config, carnet clients, exemple
facturex build facture-exemple.yaml              # créer + valider + générer (XML + PDF)
facturex validate facture_fournisseur.pdf        # vérifier une facture reçue

# facture-exemple.yaml — du français, pas des codes techniques
client: exemple-client               # clé du carnet clients.yaml
lignes:
  - { designation: "Prestation de conseil", quantite: 2, unite: jour, prix: 650.00 }
  - { designation: "Support mensuel",       quantite: 1, unite: mois, prix: 120.00 }
paiement: { delai: 30j, iban: FR7630006000011234567890189, moyen: virement }

→ Émetteur repris de config.yaml, TVA dérivée du SIRET, numéro attribué par le compteur légal (séquence continue, SQLite), échéance calculée, mentions obligatoires ajoutées (pénalités, indemnité 40 €, art. 293 B si micro), facture validée avant écriture, PDF avec QR de paiement SEPA.

Modules (chaque brique marche seule)

Les 3 usages en 30 secondes

1. Vérifier une facture reçue

from facturex import parse, validate
rapport = validate(parse("facture_fournisseur.pdf"))
print(rapport.to_text())
# ❌ BR-CO-10 [total_line_net] : total des lignes (150.00) ≠ Σ montants de ligne (100.00)
# ❌ FR-SIRET-1 [buyer.siret] : SIRET acheteur invalide : échec de la clef de contrôle (Luhn)

2. Créer de A à Z (builder)

from facturex.builder import build_file
resultat = build_file("facture.yaml")     # defaults + validation intégrés
print(resultat.invoice.number, resultat.warnings)

Puis facturex build facture.yaml --theme moderne --logo logo.png → FA-2026-0001.cii.xml + .pdf.

Sections reconnues : numero (auto = compteur légal), date, type (facture/avoir/acompte…), devise, emetteur (ou repris de config.yaml), client (clé du carnet ou inline), lignes (designation, quantite, prix, unite, taux, remise), paiement (delai 30j/30jfm/45j le 5, iban, moyen), references, mentions, options (micro, taux_tva_defaut, numero_motif).

Modèles prêts : prestation.yaml, abonnement.yaml, avoir.yaml, acompte.yaml.

3. Piloter son activité (ledger + reports)

facturex build facture.yaml --record            # enregistre au carnet en même temps
facturex book overdue                            # impayés + jours de retard
facturex report --trimestre T3                   # CA du trimestre + clients + TVA
facturex report --tva --annee 2026 --json        # ventilation TVA (CA3) en JSON

(modules Python : from facturex.ledger import Ledger · from facturex.reports import Reports)

4. Boîte à outils & agents

facturex tools siren 81234567600017   # → TVA intracom. FR19812345676
facturex tools ht 2136.00 --taux 20   # → HT 1780.00, TVA 356.00
facturex mcp                          # serveur MCP pour Claude/Cursor

from facturex.tools import iban_valid, echeance, Sequence
Sequence().next_number("FA-{year}-")          # FA-2026-0001 (réservé, persistant)

5. Envoyer à une Plateforme Agréée (PDP)

# boucle complète en local : PA factice, carnet tenu à jour
facturex build facture.yaml -o facture.pdf
facturex pdp send facture.pdf --connector mock --record
facturex pdp sync                      # le carnet suit les statuts
facturex pdp webhook                   # ou : mises à jour en temps réel

from facturex.pdp import AFNORConnector, MockPDPConnector, sync_to_ledger

pa = AFNORConnector(  # identifiants via env FACTUREX_PDP_CLIENT_ID/SECRET/SCOPE
    base_url="https://pdp.exemple.fr",
)
recu = pa.send_invoice(facture, fmt="cii")   # FlowReceipt(flow_id, status, raw)
print(recu.flow_id, recu.status)

Identifiants : variables d'environnement FACTUREX_PDP_BASE_URL, FACTUREX_PDP_CLIENT_ID, FACTUREX_PDP_CLIENT_SECRET, FACTUREX_PDP_SCOPE. Les routes par défaut (/oauth/token, /healthcheck, /flows, /flows/{id}) suivent le modèle AFNOR Z12-013 et se surchargent via routes= — chaque PA ayant sa propre API, alignez-les sur le Swagger de votre plateforme. Statuts normalisés AFNOR XP Z12-012 (FlowStatus), alias français acceptés ("encaissée", "refusée"…), pont automatique vers le carnet.

6. E-reporting (flux DGFiP 10.1 / 10.2)

Les transactions qui ne passent pas par l'e-invoicing B2B (B2C, clients étrangers) doivent être déclarées à la DGFiP :

facturex ereporting flux-101          # ventes B2C (agrégées/jour) + B2B international
facturex ereporting flux-102          # paiements de ces transactions

from facturex.ereporting import (
    build_flux_101, transactions_from_ledger, paiements_from_ledger,
)

xml = build_flux_101(
    transactions_from_ledger(carnet, annee=2026),
    siret_emetteur="81234567600017", periode="2026-09",
)

B2C agrégé par jour (HT + TVA par taux), B2B international facture par facture (identifiant fiscal, pays, devise), avoirs 381 en négatif. Client sans pays ou en France → B2C ; sinon B2B international. Les encaissements des factures passées par une PA ne vont pas dans le 10.2 (la PA les déclare via le statut « encaissée »).

7. Peppol (BIS Billing 3.0, sidecar AS4)

Pour facturer sur le réseau Peppol sans implémenter AS4 en Python : le transport est délégué à un point d'accès Java (Oxalis en Docker, oxalispeppol/oxalis — 8181 REST), facturex prépare, valide et transmet :

facturex peppol id 81234567600017        # → 0009:81234567600017
facturex peppol check facture-ubl.xml    # profil BIS 3.0 (BT-10, BT-34/49…)
facturex peppol lookup 0088:3103565000003 --sml prod   # endpoint AS4 du client
facturex peppol send facture.yaml --to 0009:SIRET-DU-CLIENT

from facturex.peppol import OxalisConnector, lookup_endpoint, participant_id

ap = lookup_endpoint("0088:3103565000003")   # Endpoint(ap_url, certificate…)
recu = OxalisConnector("http://127.0.0.1:8181").send_invoice(
    facture, receiver=participant_id(siret_client),
)

Test gratuit : testbed.peppol.eu (certificats OpenPeppol de test) ; en production, passer par un AP existant ou adhérer (AP ~2 950 €/an).

8. Skills & plugins pour agents IA

facturex se branche nativement sur les agents : skill universel (standard Agent Skills), serveur MCP intégré (facturex mcp), marketplace Claude Code.

libs/facturex-py/skills/install.sh --all   # Claude Code, Codex, Hermes, OpenClaw
claude mcp add facturex -- facturex mcp    # outils MCP (Codex : codex mcp add …)
/plugin marketplace add Kapturo-ai/Librairies-meta-creator   # plugin Claude Code

Détails : plugins/facturex/skills/facturex/SKILL.md et idees/11-skills-plugins-agents.md.

Garanties qualité

• 102 tests verts, dont le XML généré validé contre la XSD officielle Factur-X 1.0.9 et le Schematron officiel EN 16931 (Saxon) à chaque commit
• CI GitHub Actions Python 3.10 → 3.13, ruff clean, typing (py.typed)
• Montants en Decimal (jamais de float), arrondis facturiers ROUND_HALF_UP

Limites (assumées)

Remises/charges au niveau document (BT-92/BT-102) non modélisées · profils Factur-X < EN 16931 en lecture seule · pas de vérification de signature · client PDP piloté par configuration (routes à aligner sur le Swagger de votre PA — modèle AFNOR Z12-013) · e-reporting et Peppol à venir.

Roadmap

• v0.1 — modèle unifié, parsers, writers, validation, CLI, mode strict
• v0.2 — builder A→Z, carnet clients, numérotation légale, outils, PDF enrichi (QR EPC), serveur MCP
• v0.2.1/0.3.0 — ledger (statuts/impayés), reports (CA clients, TVA CA3), publication PyPI préparée (trusted publishing)
• v0.4 — connecteur PDP (OAuth2 config-driven, statuts Z12-012, webhooks, pont carnet)
• v0.5 — e-reporting (flux DGFiP 10.1 ventes / 10.2 paiements)
• v0.6 — Peppol BIS 3.0 (identifiants, SML/SMP, sidecar Oxalis)
• v0.7 — export FEC, relances automatiques
• v0.6 — Peppol BIS 3.0 (sidecar Oxalis)
• v1.0 (avant sept. 2027) — signatures, conformité réception (PUY)

Développement

pip install -e ".[dev]" saxonche qrcode pillow
pytest -v

Fait partie du programme Librairies-meta-creator (fiche : idees/07-einvoicing-fr.md).