FacturX API

requests + retry, async possible via httpx, parfait pour orchestrer vos batchs EN16931.

Intégrer FacturX API avec Python

Compatible scripts CLI, worker Celery, pipelines Airflow ou FastAPI.

Support sync/async
Idéal pour pipelines data et automatisations
Hash request_id pour tracer les factures

Exemple cURL /convert

multipart/form-data — /convert + invoice_data 
curl -X POST https://api.facturxapi.com/api/v1/convert \
  -H "Authorization: Bearer $FACTURX_API_KEY" \
  -H "Accept-Language: fr" \
  -F "file=@./facture-x.pdf" \
  -F "output=facturx_pdfa3" \
  -F "validation_target=en16931" \
  -F 'invoice_data={"invoice_number":"FA-2026-042","issue_date":"2026-04-01","invoice_type":"380","currency":"EUR","seller":{"name":"Ma Societe SAS","siret":"10000000900017","vat_id":"FR88100000009","address":{"street":"10 rue de Rivoli","city":"Paris","postal_code":"75001","country":"FR"}},"buyer":{"name":"Client SA","siret":"10000001700010","address":{"street":"20 rue de la Republique","city":"Lyon","postal_code":"69002","country":"FR"}},"references":{"buyer_reference":"SERVICE-ACHATS","purchase_order_reference":"PO-2026-0017","contract_reference":"CTR-2026-04"},"totals":{"net":"970.00","tax":"194.00","gross":"1164.00","prepaid_amount":"100.00","rounding_amount":"0.00","due":"1064.00"},"tax_breakdown":[{"rate":"20.00","category":"S","base":"970.00","amount":"194.00"}],"line_items":[{"number":"1","description":"Prestation conseil","quantity":"10","unit":"C62","unit_price":"100.00","net_amount":"970.00","vat_rate":"20.00","vat_category":"S","purchase_order_line_reference":"10","gross_unit_price":"120.00","price_discount":"20.00","allowances":[{"amount":"50.00","reason":"Remise ligne","reason_code":"95"}],"charges":[{"amount":"20.00","reason":"Supplement urgent"}]}],"payment":{"due_date":"2026-05-01","terms":"Paiement a 30 jours","iban":"FR7630006000011234567890189"},"delivery":{"date":"2026-04-01","address":{"street":"20 rue de la Republique","city":"Lyon","postal_code":"69002","country":"FR"}},"invoicing_period":{"start_date":"2026-04-01","end_date":"2026-04-30"}}'

Snippet Python

requests — génération /api/v1/convert 
import os
import json
import requests

API_KEY = os.environ['FACTURX_API_KEY']
API_URL = 'https://api.facturxapi.com/api/v1/convert'

invoice_data = {
  "invoice_number": "FA-2026-042",
  "issue_date": "2026-04-01",
  "invoice_type": "380",
  "currency": "EUR",
  "seller": {
    "name": "Ma Societe SAS",
    "siret": "10000000900017",
    "vat_id": "FR88100000009",
    "address": {
      "street": "10 rue de Rivoli",
      "city": "Paris",
      "postal_code": "75001",
      "country": "FR"
    }
  },
  "buyer": {
    "name": "Client SA",
    "siret": "10000001700010",
    "address": {
      "street": "20 rue de la Republique",
      "city": "Lyon",
      "postal_code": "69002",
      "country": "FR"
    }
  },
  "references": {
    "buyer_reference": "SERVICE-ACHATS",
    "purchase_order_reference": "PO-2026-0017",
    "contract_reference": "CTR-2026-04"
  },
  "totals": {
    "net": "970.00",
    "tax": "194.00",
    "gross": "1164.00",
    "prepaid_amount": "100.00",
    "rounding_amount": "0.00",
    "due": "1064.00"
  },
  "tax_breakdown": [
    {
      "rate": "20.00",
      "category": "S",
      "base": "970.00",
      "amount": "194.00"
    }
  ],
  "line_items": [
    {
      "number": "1",
      "description": "Prestation conseil",
      "quantity": "10",
      "unit": "C62",
      "unit_price": "100.00",
      "net_amount": "970.00",
      "vat_rate": "20.00",
      "vat_category": "S",
      "purchase_order_line_reference": "10",
      "gross_unit_price": "120.00",
      "price_discount": "20.00",
      "allowances": [
        {
          "amount": "50.00",
          "reason": "Remise ligne",
          "reason_code": "95"
        }
      ],
      "charges": [
        {
          "amount": "20.00",
          "reason": "Supplement urgent"
        }
      ]
    }
  ],
  "payment": {
    "due_date": "2026-05-01",
    "terms": "Paiement a 30 jours",
    "iban": "FR7630006000011234567890189"
  },
  "delivery": {
    "date": "2026-04-01",
    "address": {
      "street": "20 rue de la Republique",
      "city": "Lyon",
      "postal_code": "69002",
      "country": "FR"
    }
  },
  "invoicing_period": {
    "start_date": "2026-04-01",
    "end_date": "2026-04-30"
  }
}

files = {
    'file': open('invoices/FX-2024-0001.pdf', 'rb'),
}

response = requests.post(
    API_URL,
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Accept-Language': 'fr',
    },
    files=files,
    data={
        'output': 'facturx_pdfa3',
        'validation_target': 'en16931',
        'invoice_data': json.dumps(invoice_data),
    },
    timeout=20,
)

data = response.json()
if not data.get('success'):
    print('Conversion non vérifiée:', data.get('target'), data.get('issues', []))

Parcours conseillé — générer puis contrôler

Commencez par /convert pour produire un livrable Factur-X contrôlé, puis utilisez /validate comme précontrôle ou contrôle indépendant.

OpenAPI ↓ Postman ↓

POST /api/v1/convert

PDF → Factur-X PDF/A-3

Génère un Factur-X PDF/A-3 à partir d'un PDF visuel et de données invoice_data. Les livrables ne sont exposés que si la cible demandée est vérifiée.

curl -X POST https://api.facturxapi.com/api/v1/convert \
  -H "Authorization: Bearer $KEY" \
  -H "Accept-Language: fr" \
  -F "file=@./facture.pdf" \
  -F "output=facturx_pdfa3" \
  -F "validation_target=en16931" \
  -F 'invoice_data={"invoice_number":"FA-2026-042","issue_date":"2026-04-01","invoice_type":"380","currency":"EUR","seller":{"name":"Ma Societe SAS","siret":"10000000900017","vat_id":"FR88100000009","address":{"street":"10 rue de Rivoli","city":"Paris","postal_code":"75001","country":"FR"}},"buyer":{"name":"Client SA","siret":"10000001700010","address":{"street":"20 rue de la Republique","city":"Lyon","postal_code":"69002","country":"FR"}},"references":{"buyer_reference":"SERVICE-ACHATS","purchase_order_reference":"PO-2026-0017","contract_reference":"CTR-2026-04"},"totals":{"net":"970.00","tax":"194.00","gross":"1164.00","prepaid_amount":"100.00","rounding_amount":"0.00","due":"1064.00"},"tax_breakdown":[{"rate":"20.00","category":"S","base":"970.00","amount":"194.00"}],"line_items":[{"number":"1","description":"Prestation conseil","quantity":"10","unit":"C62","unit_price":"100.00","net_amount":"970.00","vat_rate":"20.00","vat_category":"S","purchase_order_line_reference":"10","gross_unit_price":"120.00","price_discount":"20.00","allowances":[{"amount":"50.00","reason":"Remise ligne","reason_code":"95"}],"charges":[{"amount":"20.00","reason":"Supplement urgent"}]}],"payment":{"due_date":"2026-05-01","terms":"Paiement a 30 jours","iban":"FR7630006000011234567890189"},"delivery":{"date":"2026-04-01","address":{"street":"20 rue de la Republique","city":"Lyon","postal_code":"69002","country":"FR"}},"invoicing_period":{"start_date":"2026-04-01","end_date":"2026-04-30"}}'

POST /api/v1/validate

Précontrôle technique

Contrôle un PDF Factur-X ou un XML CII déjà produit. Retourne un rapport JSON structuré avec codes BR-* par ligne/champ.

curl -X POST https://api.facturxapi.com/api/v1/validate?validation_target=en16931 \
  -H "Authorization: Bearer $KEY" \
  -F "file=@./facture.pdf"

POST /api/v1/extract

XML CII embarqué → JSON

Extrait le XML CII d'un PDF Factur-X reçu. Paramètre validate=true combine extraction + validation en une requête.

curl -X POST "https://api.facturxapi.com/api/v1/extract?validate=true&lang=fr" \
  -H "Authorization: Bearer $KEY" \
  -F "file=@./facture-recue.pdf"

POST /api/v1/repair

Corrections déterministes

Corrige automatiquement les erreurs réparables d'un XML CII (dates, décimaux, namespaces, schemeID). Retour : diff + XML réparé.

curl -X POST https://api.facturxapi.com/api/v1/repair \
  -H "Authorization: Bearer $KEY" \
  -F "file=@./facture-invalide.xml"

Checklist intégration

  • ✓

    Uploader depuis un dossier temporaire protégé (pas de /tmp partagé)

  • ✓

    Utiliser retrying ou tenacity pour gérer 429/500

  • ✓

    Anonymiser les logs (pas de PDF complet en clair)

Retries & timeouts

Utilisez tenacity ou httpx.Retry avec jitter pour protéger vos workers.

  • • Timeout côté requests : 20 s
  • • Limiter la concurrence via semaphore pour éviter 429
  • • Réémettre seulement les requêtes réseau safe (POST idem que file)

Erreurs fréquentes

Mappez vos logs sans confondre codes API publics, exceptions client locales et règles métier EN16931.

Code API public

415 unsupported_media_type

Extension ou type de fichier non supporté.

💡 Filtrer les uploads côté CLI et imposer PDF ou XML uniquement.

Exception client locale

Timeout client ou proxy

Le worker Python coupe la requête avant la réponse API.

💡 Augmentez le timeout client et mettez la facture en retry différé avec jitter.

Code API public

402 quota_exceeded

Quota mensuel dépassé.

💡 Arrêter le retry automatique et alerter l’équipe sur le besoin de capacité.

FAQ

Puis-je traiter un lot depuis Pandas ?

Oui, bouclez sur vos lignes et envoyez les fichiers un par un (max 3 en parallèle).

Comment stocker le rapport ?

Sauvegardez le JSON de réponse dans S3 ou Postgres avec le hash de la facture.

Guide EN16931

Comprendre les profils et règles

Vérifier une facture en ligne

Déposer rapidement un échantillon

Tarifs

Anticiper vos lots mensuels

Et après ?

Passer en production

Choisissez l'étape suivante pour activer FacturX API sur votre stack. Tous les liens sont internes pour garder le suivi clair.

🔑

Activer ma clé API

Clé Sandbox par email + clés distinctes pour dev/staging.

💶

Choisir un plan

Comparer les offres actuelles : Sandbox, Launch, Scale, Business et Pilote accompagné.

📘

Lire la documentation

Endpoints détaillés + schémas JSON pour parser les réponses.

🧪

Vérifier une facture

Déposer un fichier depuis l'UI pour comparer le diagnostic avec la réponse API.