Metadata-Version: 2.4
Name: ads-facturx
Version: 0.4.6
Summary: 
License-Expression: MIT
Author: antoineducoulombier
Author-email: antoine.ducoulombier@alchimiedatasolutions.com
Requires-Python: >=3.12,<4
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: factur-x (>=3.15,<4.0)
Requires-Dist: pydantic (>=2.12.5,<3.0.0)
Requires-Dist: reportlab (>=4.4.9,<5.0.0)
Requires-Dist: saxonche (>=12.9.0,<13.0.0)
Description-Content-Type: text/markdown

<h1 align="center">eFacturePy — <code>ads-facturx</code></h1>

<p align="center">
  <em>Génération, validation et assemblage de factures électroniques <b>Factur-X / EN 16931</b> en Python.</em>
</p>

<p align="center">
  <img alt="Python" src="https://img.shields.io/badge/python-%E2%89%A53.12-blue">
  <img alt="Version" src="https://img.shields.io/badge/ads--facturx-0.4.3-success">
  <img alt="Build" src="https://img.shields.io/badge/build-poetry-60A5FA">
  <img alt="Status" src="https://img.shields.io/badge/status-active-brightgreen">
</p>

---

## 🧭 Sommaire

- [À propos](#-à-propos)
- [Fonctionnalités](#-fonctionnalités)
- [Architecture du dépôt](#-architecture-du-dépôt)
- [Installation](#-installation)
- [Démarrage rapide](#-démarrage-rapide)
- [API publique](#-api-publique)
- [Modèle de données](#-modèle-de-données)
- [Validation EN 16931](#-validation-en-16931)
- [Développement](#-développement)
- [Tests](#-tests)
- [Dépendances](#-dépendances)
- [Auteur](#-auteur)

---

## 📖 À propos

**eFacturePy** est le dépôt de travail du package Python **[`ads-facturx`](./ads_facturx)**, un outil qui permet de :

- produire un **XML Cross Industry Invoice** conforme au profil `urn:cen.eu:en16931:2017` ;
- générer le **PDF/A-3** associé à l’aide de [ReportLab](https://www.reportlab.com/) ;
- **embarquer** ce XML dans le PDF pour obtenir une **Factur-X** valide (via [`factur-x`](https://pypi.org/project/factur-x/)) ;
- **valider** la facture via XSD (EN16931) et **Schematron** (moteur [SaxonC-HE](https://pypi.org/project/saxonche/)).

---

## ✨ Fonctionnalités

- ✅ Génération d’un XML Factur-X / EN 16931 à partir d’un `dict` métier
- ✅ Génération d’un PDF de facture (template par défaut + logo personnalisable)
- ✅ Fusion PDF + XML → fichier Factur-X conforme
- ✅ Validation **XSD** (profil `en16931`)
- ✅ Validation **Schematron** via XSLT précompilé (SaxonC)
- ✅ Modèles **Pydantic v2** pour typer et valider les données métier

---

## 🏗️ Architecture du dépôt

```text
eFacturePy/
├─ ads_facturx/              # Package distribué sur PyPI
│  ├─ Builders/              # Génération XML + PDF + Factur-X
│  ├─ Validators/            # XSD + Schematron (XSLT EN16931-CII)
│  ├─ models/                # Schémas Pydantic (DevisData, Invoice, …)
│  ├─ Samples/               # Jeu de données et XML de référence
│  └─ tests/                 # Tests unitaires pytest
├─ eFacturePy/               # Sorties d’exemple (PDF/XML générés)
├─ archive/                  # Ressources brutes : XSD, XSL, Schematron, Saxon
├─ dist/                     # Wheels et sdist historiques                   
├─ pyproject.toml            # Configuration Poetry
└─ poetry.lock
```

---

## 📦 Installation

Depuis PyPI :

```bash
pip install ads-facturx
```

> **Prérequis :** Python **≥ 3.12**. SaxonC-HE est installé automatiquement via la dépendance `saxonche`.

---

## 🚀 Démarrage rapide

```python
from ads_facturx import (
    generate_xml, write_xml_from_string,
    xml_check_xsd, xml_check_schematron,
    generate_invoice, generate_facturx,
)
from ads_facturx.Samples.data import sample_raw_data as data

DESTINATION = "eFacturePy"

xml_string = generate_xml(data)
xml_path   = write_xml_from_string(xml_string, DESTINATION, "my_first_xml")

xml_check_xsd(xml_string)
report = xml_check_schematron(xml_path=xml_path)
print(report)

generate_invoice(file_name="my_first_invoice.pdf",
                 destination_folder=DESTINATION,
                 data=data, title="Ma facture",
                 logopath="TA_logo_reduced.jpg")

generate_facturx(file_name="my_first_invoice.pdf",
                 destination_folder=DESTINATION,
                 xml=xml_string)
```
---

## 🔌 API publique

Exposée via `from ads_facturx import ...` :

| Fonction                  | Rôle                                                                 |
|---------------------------|----------------------------------------------------------------------|
| `generate_xml(data)`      | Construit la chaîne XML CII EN 16931 à partir d’un `dict`.           |
| `write_xml_from_string`   | Sérialise l’XML sur disque (`destination_folder`, `file_name`).      |
| `xml_check_xsd`           | Valide l’XML avec le XSD `facturx` / niveau `en16931`.               |
| `xml_check_schematron`    | Applique les règles Schematron EN16931-CII via SaxonC.               |
| `generate_invoice`        | Génère le PDF de facture (ReportLab, logo + annexes optionnels).     |
| `generate_facturx`        | Embarque le XML dans le PDF pour produire la Factur-X finale.        |

---

## 🧾 Modèle de données

Le package fournit des schémas **Pydantic v2** dans [`ads_facturx/models`](./ads_facturx/models) (notamment `DevisData`, `Invoice`, `InvoiceLine`, `Company`, `Partner`, …). `generate_invoice` valide les données via `DevisData.model_validate(data)` et applique des règles EN 16931 critiques (ex. obligation du numéro de TVA vendeur pour la catégorie `S`).

Un exemple complet de payload est fourni dans [`ads_facturx/Samples/data.py`](./ads_facturx/Samples/data.py).

---

## ✅ Validation EN 16931

- **XSD** : `xml_check_xsd` s’appuie sur `factur-x` (`flavor="facturx"`, `level="en16931"`).
- **Schematron** : `xml_check_schematron` exécute `Validators/xslt/EN16931-CII-validation.xslt` avec SaxonC et renvoie la liste des `failed-assert` (id, location, message).

---

## 📚 Dépendances

`factur-x`, `saxonche`, `pydantic`, `reportlab` (voir [`pyproject.toml`](./pyproject.toml) et [`poetry.lock`](./poetry.lock)).

## 👤 Auteur

**Antoine Ducoulombier** — [Alchimie Data Solutions](http://www.alchimiedatasolutions.com) · `antoine.ducoulombier@alchimiedatasolutions.com`

