Metadata-Version: 2.5
Name: facturex
Version: 0.6.3
Summary: Facturation électronique France : lire, valider et générer des factures Factur-X (CII), UBL 2.1 et EN 16931 en Python. Offline-first.
Project-URL: Repository, https://github.com/Kapturo-ai/Librairies-meta-creator
Project-URL: Issues, https://github.com/Kapturo-ai/Librairies-meta-creator/issues
Author: Librairies-meta-creator contributors
License-Expression: MIT
License-File: LICENSE
Keywords: e-invoicing,en16931,factur-x,facturation-electronique,france,invoice,pdp,peppol,ubl,zugferd
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: French
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Accounting
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.5
Provides-Extra: all
Requires-Dist: factur-x>=6.0; extra == 'all'
Requires-Dist: pillow>=10.0; extra == 'all'
Requires-Dist: pypdf>=4.0; extra == 'all'
Requires-Dist: pyyaml>=6.0; extra == 'all'
Requires-Dist: qrcode>=7.4; extra == 'all'
Provides-Extra: builder
Requires-Dist: pyyaml>=6.0; extra == 'builder'
Provides-Extra: dev
Requires-Dist: factur-x>=6.0; extra == 'dev'
Requires-Dist: lxml>=5; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pypdf>=4.0; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: pdf
Requires-Dist: pypdf>=4.0; extra == 'pdf'
Provides-Extra: rich-pdf
Requires-Dist: pillow>=10.0; extra == 'rich-pdf'
Requires-Dist: qrcode>=7.4; extra == 'rich-pdf'
Provides-Extra: strict
Requires-Dist: factur-x>=6.0; extra == 'strict'
Description-Content-Type: text/markdown

# 🇫🇷 facturex-py

[![PyPI](https://img.shields.io/pypi/v/facturex)](https://pypi.org/project/facturex/)
[![Python](https://img.shields.io/pypi/pyversions/facturex)](https://pypi.org/project/facturex/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

```bash
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
```

```yaml
# 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

```python
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)

```python
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)

```bash
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

```bash
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
```

```python
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)

```bash
# 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
```

```python
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 :

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

```python
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="85079917200028", 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 :

```bash
facturex peppol id 85079917200028        # → 0009:85079917200028
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
```

```python
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.

```bash
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

- [x] v0.1 — modèle unifié, parsers, writers, validation, CLI, mode strict
- [x] v0.2 — builder A→Z, carnet clients, numérotation légale, outils, PDF enrichi (QR EPC), serveur MCP
- [x] v0.2.1/0.3.0 — **ledger** (statuts/impayés), **reports** (CA clients, TVA CA3), publication PyPI préparée (trusted publishing)
- [x] v0.4 — **connecteur PDP** (OAuth2 config-driven, statuts Z12-012, webhooks, pont carnet)
- [x] v0.5 — **e-reporting** (flux DGFiP 10.1 ventes / 10.2 paiements)
- [x] 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

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

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