Skip to main content

🇫🇷 facturex-py

PyPI Python License: MIT

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)

Module Rôle Extra
models Modèle unifié typé Invoice/Party/LineItem (pydantic v2, Decimal) —
parsers Lecture CII (Factur-X), UBL 2.1, PDF (XML embarqué), auto-détection [pdf]
writers Génération CII (EN 16931), UBL 2.1, PDF [pdf]
validation Règles BR officielles CEN + règles FR-* (Luhn, TVA, art. 293 B), messages en français —
strict XSD + Schematron officiels (délégation factur-x/Saxon), PDF/A-3 [strict]
builder A→Z sans effort : YAML/TOML/JSON → facture conforme, sections, defaults, carnet clients, numérotation légale, mentions auto [builder]
tools Boîte à outils : SIREN/SIRET (Luhn), TVA FR ↔ SIREN, IBAN/BIC (mod-97), HT↔TVA↔TTC, échéances (30j, 30jfm, 45j le 5), compteur de séquence —
pdfgen PDF pro : multi-pages, thèmes (sobre/moderne), logo, QR de paiement EPC, mentions qrcode[pil] opt.
ledger Carnet des factures émises : statuts, encaissements partiels, impayés + retards, totaux —
reports CA par période/client, ventilation TVA prête pour la déclaration (avoirs déduits) —
mcp Serveur MCP (stdio JSON-RPC, zéro dépendance) : parse / validate / build / write pour agents IA —
cli facturex init · build · validate · inspect · convert · sample · tools · mcp —

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).

Metadata

Release files for facturex 0.6.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for facturex 0.6.4
File Size Uploaded Provenance Actions
facturex-0.6.4.tar.gz 102.9 kB With provenance Details for facturex-0.6.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for facturex 0.6.4
File Interpreter ABI Platform Actions
facturex-0.6.4-py3-none-any.whl Python 3 none any Details for facturex-0.6.4-py3-none-any.whl

Total release size: 202.6 kB

Release files / facturex-0.6.4.tar.gz

Download URL facturex-0.6.4.tar.gz
Size 102.9 kB
Tags Source
SHA-256 checksum
How to use checksums
debeb14323dc360c20357bacacb3ff6bbea95bbdf0b59e427896d7755657adec
BLAKE2b-256 checksum
How to use checksums
30744dd9f962120ce9d6240348e9362b2af43573cf6b464ff967521557549504
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.

Transparency log

Release files / facturex-0.6.4-py3-none-any.whl

Download URL facturex-0.6.4-py3-none-any.whl
Size 99.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
041d69d965a49ce5d7c50dc29fc2f004a435f5f77af7364002505e3470f5d378
BLAKE2b-256 checksum
How to use checksums
61d3d26fb56a9f3834a8a95c3feb3553a2e724c33f5999afdc218d07d6fde55f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.

Transparency log

Security for facturex 0.6.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for facturex-0.6.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page