{"id":39792888,"url":"https://github.com/facturx-engine/facturx-engine","last_synced_at":"2026-03-06T21:02:57.447Z","repository":{"id":333097153,"uuid":"1136191719","full_name":"facturx-engine/facturx-engine","owner":"facturx-engine","description":"API REST self-hosted pour générer des factures Factur-X / ZUGFeRD 2.4 (EN 16931). Moteur léger Docker-ready, conforme PDF/A-3, validation XML intégrée.","archived":false,"fork":false,"pushed_at":"2026-02-25T14:26:22.000Z","size":53756,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-25T17:59:00.464Z","etag":null,"topics":["air-gapped","cra-compliance","docker","en16931","factur-x","fastapi","gdpr-compliant","invoice-validation","offline","pdf-a3","self-hosted","xrechnung","zugferd"],"latest_commit_sha":null,"homepage":"https://facturx-engine.lemonsqueezy.com","language":"XSLT","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/facturx-engine.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"docs/security/sbom.json","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":"codemeta.json","zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-17T08:28:00.000Z","updated_at":"2026-02-25T14:26:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/facturx-engine/facturx-engine","commit_stats":null,"previous_names":["facturx-engine/facturx-engine"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/facturx-engine/facturx-engine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facturx-engine%2Ffacturx-engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facturx-engine%2Ffacturx-engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facturx-engine%2Ffacturx-engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facturx-engine%2Ffacturx-engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/facturx-engine","download_url":"https://codeload.github.com/facturx-engine/facturx-engine/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facturx-engine%2Ffacturx-engine/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29895895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T12:09:13.686Z","status":"ssl_error","status_checked_at":"2026-02-27T12:09:13.282Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["air-gapped","cra-compliance","docker","en16931","factur-x","fastapi","gdpr-compliant","invoice-validation","offline","pdf-a3","self-hosted","xrechnung","zugferd"],"created_at":"2026-01-18T12:18:30.437Z","updated_at":"2026-03-06T21:02:57.436Z","avatar_url":"https://github.com/facturx-engine.png","language":"XSLT","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Factur-X Engine\n\n\u003e **The Privacy-First Invoicing Engine.** 100% Air-gapped, Official Saxon-HE Validation. Generate and Validate Factur-X, ZUGFeRD 2.x, and XRechnung without cloud dependencies.\n\n![Docker Pulls](https://img.shields.io/docker/pulls/facturxengine/facturx-engine) [![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Live%20Demo-blue)](https://huggingface.co/spaces/Facturx-engine/factur-x-engine-demo) [![GitHub](https://img.shields.io/badge/github-repo-181717?logo=github)](https://github.com/facturx-engine/facturx-engine) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT) ![Standard](https://img.shields.io/badge/standard-EN16931-green.svg) ![Privacy First](https://img.shields.io/badge/Privacy-Air_Gapped-success?logo=shield-dog) ![Saxon-HE](https://img.shields.io/badge/Powered_By-Saxon--HE-blue)\n\n---\n\n## Why Factur-X Engine?\n\n- **Air-Gapped by Design**: 100% offline execution. No outbound network calls. GDPR/DORA compliant.\n- **Official Saxon-HE Validation**: Same EN16931 Schematron rules used by **Chorus Pro (France)** and **KoSIT (Germany)** — including BR-FR CTC v1.2.0 (FNFE/DGFIP) for French invoices. Full parity requires Saxon-HE (bundled in Docker image); check `validation_completeness` in API responses to confirm.\n- **Smart Diagnostics Engine (Pro)**: Proactively detects \"Angles Morts\" (e.g. invalid IBANs, \u003e2 decimals, bizarre dates) that technically pass standard validation but fail on governmental platforms.\n- **Mandate Ready**: Compliant with **France 2026 (PDP/PPF)** and **Germany 2025** electronic invoicing requirements.\n\n### Architecture Decisions (Zero Memory Leaks)\n\n- **Isolated Java Subprocesses**: Unlike traditional Python/Java wrappers that suffer from fatal JVM memory leaks under load, Factur-X Engine executes Schematron (Saxon-HE) and PDF/A-3 (VeraPDF) validations as isolated, sandboxed subprocesses. Memory is instantly reclaimed by the OS, guaranteeing enterprise-grade stability.\n- **Air-Gap First**: To guarantee stability in secure environments (Banking, Defense), we do not use auto-updates or cloud \"phone-homing\". Licensing is verified via offline cryptographic signatures (Ed25519).\n\n---\n\n## Quickstart\n\n```bash\ndocker run -d -p 8000:8000 --name facturx-engine facturxengine/facturx-engine:latest\n```\n\n### Core Workflows\n\n#### 1. Validate — Compliance Gate\n\nCheck any CII or UBL invoice (PDF or XML) against EN 16931 before sending to PDP/PPF.\n\n```bash\ncurl -X POST \"http://localhost:8000/v1/validate\" \\\n  -F \"file=@invoice.xml\"\n```\n\n#### 2. Generate XML — Business Data to CII\n\nTransform your ERP JSON metadata into a Cross-Industry Invoice XML.\n\n```bash\ncurl -X POST \"http://localhost:8000/v1/xml\" \\\n  -F \"metadata=$(cat examples/simple_invoice.json)\" \\\n  -o invoice.xml\n```\n\n#### 3. Merge — Assemble PDF + XML\n\nEmbed an existing XML (Factur-X, ZUGFeRD, XRechnung) into a PDF/A-3b container.\n\n```bash\ncurl -X POST \"http://localhost:8000/v1/merge\" \\\n  -F \"pdf=@examples/invoice_raw.pdf\" \\\n  -F \"xml=@invoice.xml\" \\\n  --output invoice_compliant.pdf\n```\n\n#### 4. Extract — Receive Supplier Invoices\n\nPull structured invoice data from a received Factur-X/ZUGFeRD PDF.\n\n```bash\ncurl -X POST \"http://localhost:8000/v1/extract\" \\\n  -F \"file=@invoice.pdf\"\n```\n\n### Advanced Capabilities\n\n#### `/v1/convert` — One-Step PDF Generation\n\nConvenience shortcut that generates XML from JSON metadata and embeds it into your PDF in a single call.\n\n```bash\ncurl -X POST \"http://localhost:8000/v1/convert\" \\\n  -F \"pdf=@examples/invoice_raw.pdf\" \\\n  -F \"metadata=$(cat examples/simple_invoice.json)\" \\\n  --output invoice_compliant.pdf\n```\n\n#### `/v1/serialize` — ERP-Ready JSON (Pro)\n\nReturns a normalized, typed JSON object ready to import directly into any ERP or accounting system. See [details below](#v1serialize--erp-ready-json-pro-1).\n\n```bash\ncurl -X POST \"http://localhost:8000/v1/serialize\" \\\n  -F \"file=@invoice.pdf\"\n```\n\n**Windows users:** Replace `curl` with `curl.exe` and use PowerShell syntax for file reading.\n\n---\n\n## Documentation\n\n**[Full API Reference](https://facturx-engine.github.io/facturx-engine/ref/api-reference.html)** - All endpoints, parameters, and response formats  \n**[Integration Recipes](https://facturx-engine.github.io/facturx-engine/#api)** - Python, Node.js, PHP integration guides  \n**[FAQ \u0026 Troubleshooting](https://facturx-engine.github.io/facturx-engine/guides/error-codes.html)** - Common issues and error codes  \n**[OpenAPI Specification](https://raw.githubusercontent.com/facturx-engine/facturx-engine/main/docs/openapi.json)** - Machine-readable API spec\n**[Changelog](https://github.com/facturx-engine/facturx-engine/releases)** - Version history and release notes\n\n---\n\n## Community vs Pro\n\nThis **Community** version is production-ready. The code is Open Core (transparent Python).\n\n| Feature | Community Edition | Pro Edition | OEM Edition | Enterprise |\n| :--- | :--- | :--- | :--- | :--- |\n| **Pricing** | **Free** (MIT) | **990€ / year** | **2490€ / year** | **Contact Us** |\n| **Usage** | Internal Use | Internal Use | **Redistribution** | High Volume |\n| **Data Format** | `/v1/extract` (raw XML fields) | **`/v1/serialize` (ERP-Ready JSON)** | **`/v1/serialize` (ERP-Ready JSON)** | Custom |\n| **XML Validation** | Structural \u0026 Business Rules (Raw) | **Smart Diagnostics** (Pre-Clearance Audit) | **Smart Diagnostics** (Pre-Clearance Audit) | Custom Rules |\n| **PDF Compliance** | ❌ | **VeraPDF (PDF/A-3)** | **VeraPDF (PDF/A-3)** | **VeraPDF (PDF/A-3)** |\n| **Support** | Community | **Priority** | **SLA** | Dedicated |\n\n### `/v1/serialize` — ERP-Ready JSON (Pro)\n\nUnlike raw XML extraction, `/v1/serialize` returns a normalized, typed JSON object ready to import directly into any ERP or accounting system:\n\n```json\n{\n  \"success\": true,\n  \"invoice\": {\n    \"invoice_number\": \"INV-2025-0042\",\n    \"invoice_date\": \"2025-03-01\",\n    \"due_date\": \"2025-03-31\",\n    \"currency\": \"EUR\",\n    \"seller\": { \"name\": \"ACME SAS\", \"vat_number\": \"FR12345678901\", \"siret\": \"12345678900012\" },\n    \"buyer\": { \"name\": \"Client Corp\", \"buyer_reference\": \"PO-9981\" },\n    \"line_items\": [\n      { \"name\": \"Consulting services\", \"quantity\": 5, \"unit_code\": \"HUR\", \"net_price\": 150.00, \"line_total\": 750.00, \"vat_rate\": 20.0 }\n    ],\n    \"tax_breakdown\": [{ \"category\": \"S\", \"rate\": 20.0, \"basis_amount\": 750.00, \"tax_amount\": 150.00 }],\n    \"total_net_amount\": 750.00,\n    \"total_tax_amount\": 150.00,\n    \"total_gross_amount\": 900.00,\n    \"amount_due\": 900.00,\n    \"format\": \"factur-x\",\n    \"profile\": \"en16931\"\n  }\n}\n```\n\n### `/v1/validate` — Smart Diagnostics Engine (Pro)\n\nWhile the Community edition runs standard EN 16931 Schematron validation, the **Pro Edition** features a Smart Diagnostics engine that translates cryptic XPath errors into human-readable actions, and runs a **Proactive Scan** for silent platform killers:\n\n- `INVALID-IBAN`: Catches malformed IBAN sequences.\n- `TOO-MANY-DECIMALS`: Rejects amounts with `\u003e2` fractional digits (e.g. `100.005`) that cause arithmetic truncation errors on Chorus Pro.\n- `INVALID-DATE`: Flags dates from the distant past or future.\n- `TYPE-AMOUNT-MISMATCH`: Detects negative invoice totals masquerading as standard invoices (instead of credit notes).\n\n### 30-Day Evaluation (Product-Led Growth)\n\nTest **100% of the Pro features (VeraPDF, Smart Diagnostics, and ERP Serialization)** on your own files, within your own infrastructure, during a 30-Day Evaluation period.\n\n1. Request your evaluation key at **[Factur-X Engine on Lemon Squeezy](https://facturx-engine.lemonsqueezy.com)** (Zero friction, instant delivery).\n2. VeraPDF and Saxon-HE are **already bundled** inside the Docker image. Just inject your key:\n\n   ```bash\n   docker run -d -p 8000:8000 \\\n     -e LICENSE_KEY='YOUR_KEY' \\\n     facturxengine/facturx-engine:latest\n   ```\n\n3. After 30 days, the engine smoothly transitions back to the Community Edition. No aggressive locks, your internal validation flows continue to operate.\n\n### Configuration (Environment Variables)\n\nThe API behaves according to standard Linux paradigms. It accepts the following variables:\n\n| Variable | Default | Description |\n| :--- | :--- | :--- |\n| `LICENSE_KEY` | *(empty)* | Activates Pro Features. Leave empty for Community Edition. |\n| `MAX_UPLOAD_SIZE_MB` | `10` | Defence-in-depth size limit for payload processing. |\n| `FX_VALIDATION_TIMEOUT` | `30` | Timeout in seconds for subprocess validators (Saxon/VeraPDF). |\n| `VERAPDF_ENABLED` | `true` | System-wide toggle for PDF/A-3b validation (**Pro only**, requires `VERAPDF_JAR`). Has no effect in Community Edition. |\n| `VERAPDF_JAR` | *(empty)* | **REQUIRED FOR PRO**: Absolute path to the VeraPDF Greenfield JAR. |\n| `SAXON_JAR` | *(empty)* | Absolute path to the Saxon-HE JAR for Schematron evaluation. |\n| `METRICS_ENABLED` | `false` | Enables the `/metrics` endpoint in Pro Mode. |\n| `METRICS_TOKEN` | *(empty)* | Bearer token required for `/metrics` access in Pro Mode. |\n| `CORS_ORIGINS` | *(empty)* | Comma-separated list of allowed origins (e.g., `http://localhost:3000,https://app.example.com`). |\n| `WORKERS` | `4` | Number of Gunicorn worker processes (adjust based on CPU cores). |\n\n---\n\n## Operations \u0026 Monitoring\n\nThe container exposes endpoints designed for DevOps and infrastructure teams:\n\n| Endpoint | Purpose | Availability |\n| :--- | :--- | :--- |\n| `GET /health` | Liveness probe (Kubernetes). Returns 200 OK immediately — no subprocess overhead. | All Editions |\n| `GET /healthz` | Readiness probe. Checks JRE, VeraPDF, and Saxon-HE availability. Returns 503 if degraded. | All Editions |\n| `GET /diagnostics` | Full system dump (versions, memory, config). | All Editions |\n| `GET /metrics` | Prometheus metrics scrape target. | Pro Edition Only |\n\n### Security Hardening (Prometheus Metrics)\n\nThe `/metrics` endpoint requires explicit activation and authentication to prevent business intelligence leakage.\n\n1. **Activation**: Must set `METRICS_ENABLED=true`\n2. **Authentication**: Must define `METRICS_TOKEN=your_secure_random_string`\n3. **Scraping**: Configure Prometheus to pass the Authorization header: `Authorization: Bearer your_secure_random_string`\n\n### Recommended Reverse-Proxy Configuration\n\nEven with token authentication, it is an industry best practice to restrict access to the `/metrics` endpoint to your internal monitoring infrastructure (e.g., `127.0.0.1` or a specific VPC subnet).\n\n**Nginx Example:**\n\n```nginx\nlocation /metrics {\n    allow 127.0.0.1;\n    allow 10.0.0.0/8;\n    deny all;\n    proxy_pass http://facturx-engine:8000;\n}\n```\n\n---\n\n## Legal \u0026 Compliance\n\n**Vendor**: NexaFlow\n**License**: [MIT](https://opensource.org/licenses/MIT) (Community) / Commercial (Pro)\n**Compliance**: Designed to respect the EU **Cyber Resilience Act (CRA)**\n\n\u003e **IMPORTANT**: This software is a technical tool for data formatting. It does not replace professional tax advice. Users retain full responsibility for fiscal accuracy. See [full legal disclaimer](https://facturx-engine.github.io/facturx-engine/).\n\n---\n\n*Maintained by the Factur-X Engine Team.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacturx-engine%2Ffacturx-engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffacturx-engine%2Ffacturx-engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacturx-engine%2Ffacturx-engine/lists"}