Rendez conformes les Factur-X de vos clients.

Introduction

L'API FacturX permet de traiter des factures électroniques au format Factur-X (PDF hybride avec XML embarqué) ou XML standalone selon les standards EN16931.

Quatre endpoints sont disponibles :

• Validate : Validation XSD + Schematron complète d'un PDF Factur-X ou XML CII
• Extract : Extraction du XML CII embarqué dans un PDF Factur-X
• Convert : Conversion d'un PDF classique en Factur-X PDF/A-3 conforme
• Repair : Correction automatique déterministe d'un XML CII invalide

Qu'est-ce que Factur-X ?

Factur-X est un format de facture électronique hybride franco-allemand, également connu sous le nom de ZUGFeRD 2.x en Allemagne.

Une facture Factur-X combine deux éléments :

• Un PDF lisible : La facture visuelle classique, imprimable et lisible par l'humain
• Un fichier XML embarqué : Les données structurées de la facture, lisibles par les machines

Cette approche hybride permet une transition progressive vers la facturation électronique : les comptables peuvent continuer à lire les PDF, tandis que les systèmes informatiques peuvent extraire automatiquement les données.

Profils Factur-X

Factur-X définit plusieurs profils correspondant à différents niveaux de détail :

• Minimum : Données minimales (montants, dates, parties)
• Basic : Informations de base pour le traitement automatisé
• EN16931 : Conformité complète à la norme européenne (recommandé)
• Extended : Champs additionnels pour besoins spécifiques

L'API détecte automatiquement le profil de votre facture et applique les règles de validation correspondantes.

Structure d'un PDF Factur-X

Un PDF Factur-X valide doit contenir un fichier XML en pièce jointe (embedded file). Ce fichier est généralement nommé factur-x.xml ou zugferd-invoice.xml.

Comment vérifier manuellement ?

Dans Adobe Acrobat ou un lecteur PDF compatible :

1. Ouvrez le PDF
2. Allez dans le panneau des pièces jointes (icône trombone)
3. Vérifiez la présence d'un fichier .xml

Si aucun fichier XML n'est présent, il s'agit d'un PDF classique, pas d'une facture Factur-X.

Erreur "No Factur-X XML found"

Cette erreur signifie que le PDF uploadé ne contient pas de XML embarqué. Causes possibles :

• Le PDF a été généré par un outil qui ne supporte pas Factur-X
• Le XML a été supprimé lors d'une modification du PDF
• Le fichier est un PDF classique, pas une facture Factur-X

Comment créer une facture Factur-X ?

Plusieurs options s'offrent à vous pour générer des factures Factur-X :

Logiciels de facturation

La plupart des logiciels de comptabilité modernes supportent l'export Factur-X :

• Sage, Cegid, EBP (éditeurs français)
• SAP, Oracle (ERP)
• QuickBooks, Xero (avec plugins)

Bibliothèques open-source

Pour les développeurs souhaitant générer des Factur-X programmatiquement :

• Python : factur-x (Akretion)
• Java : Mustang Project
• PHP : horstoeko/zugferd
• .NET : ZUGFeRD-csharp

Plateformes Agréées (PA, ex-PDP)

Dans le cadre de la réforme française 2026-2027 (réception obligatoire au 1er septembre 2026, puis émission PME/TPE au 1er septembre 2027), les Plateformes Agréées assurent la transmission et le routage réglementaire. FacturX API prépare, valide et répare le document en amont, avant que votre ERP ou votre client ne le remette à sa PA.

Règles métier EN16931

La norme EN16931 définit plus de 200 règles métier (Business Rules) que doit respecter une facture électronique. Ces règles sont vérifiées via Schematron.

Catégories de règles

• BR-xx : Règles de base (champs obligatoires, formats)
• BR-CO-xx : Règles de cohérence (calculs, totaux)
• BR-S-xx : Règles spécifiques aux régimes de TVA
• BR-CL-xx : Règles sur les codes et listes de valeurs

Exemples de règles courantes

Lorsqu'une règle est violée, l'API retourne une erreur de type schematron_failed_assert avec le code de la règle concernée.

Sécurité & RGPD

La protection de vos données est notre priorité. Voici comment nous assurons la sécurité de vos factures.

Infrastructure

• Hébergement : Cloudflare Pages (front) + Railway (API). Voir la politique de confidentialité pour la liste complète des sous-traitants et leur localisation.
• Chiffrement en transit : TLS sur toutes les communications (HTTPS obligatoire).
• Chiffrement au repos : AES-256 pour le stockage temporaire.

Traitement des données

• Stockage temporaire : Les fichiers sont supprimés automatiquement après validation
• Pas d'analyse métier : Nous ne lisons pas le contenu commercial de vos factures
• Pas de partage : Vos données ne sont jamais partagées avec des tiers
• Logs minimaux : Seules les métadonnées techniques sont conservées (horodatage, taille, résultat)

Conformité

• RGPD : Conforme au Règlement Général sur la Protection des Données
• DPA : Accord de traitement des données sur demande, selon le contexte client

Pour plus de détails, consultez notre politique de confidentialité.

Base URL

https://api-staging.facturxapi.com

Authentication

Toutes les requêtes nécessitent une clé API envoyée via le header Authorization :

Authorization: Bearer YOUR_API_KEY

Obtenez votre clé API gratuitement (10 factures traitées / mois).

Endpoints

L'API expose quatre endpoints. Côté produit, retenez une règle simple : 1 appel API = 1 facture traitée.

POST /api/v1/validate

Valide un fichier Factur-X (PDF ou XML) selon les standards EN16931. Vérifie la structure XSD et les règles métier Schematron.

Paramètres

• file (multipart, requis) : Fichier PDF Factur-X ou XML CII
• lang (query, optionnel) : Langue de la réponse (en / fr)
• legacy (query, optionnel, défaut : false) : Retourner l'ancien format court si votre intégration historique en dépend encore

Décompte

1 facture traitée par requête.

Exemple curl

curl -X POST https://api-staging.facturxapi.com/api/v1/validate \
  -H "Authorization: Bearer votre-cle-api" \
  -F "file=@./facture.pdf"

Réponse par défaut (200)

{
  "valid": true,
  "validatedAt": "2026-04-28T10:00:00.000Z",
  "filename": "facture.xml",
  "profile": "EN16931",
  "durationMs": 124,
  "summary": {
    "errorCount": 0,
    "warningCount": 0
  },
  "issues": [],
  "stages": {
    "pdfa": {
      "passed": true,
      "skipped": true,
      "skip_reason": "XML file - PDF/A validation not applicable",
      "error_count": 0,
      "warning_count": 0,
      "info_count": 0,
      "issues": []
    },
    "facturx_pdf": {
      "passed": true,
      "skipped": true,
      "skip_reason": "XML file - PDF checks not applicable",
      "error_count": 0,
      "warning_count": 0,
      "info_count": 0,
      "issues": []
    },
    "xsd": {
      "passed": true,
      "skipped": false,
      "skip_reason": null,
      "error_count": 0,
      "warning_count": 0,
      "info_count": 0,
      "issues": []
    },
    "schematron": {
      "passed": true,
      "skipped": false,
      "skip_reason": null,
      "error_count": 0,
      "warning_count": 0,
      "info_count": 0,
      "issues": []
    }
  },
  "errors": [],
  "warnings": []
}

Réponse legacy (?legacy=true)

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "profile": "EN16931",
  "message": "Validation completed"
}

Codes d'erreur spécifiques

• 400 : Fichier vide ou invalide
• 415 : Format non supporté (ni PDF, ni XML)

POST /api/v1/extract

Extrait le fichier XML embarqué (factur-x.xml) d'un PDF Factur-X et retourne les données structurées. Optionnellement, valide le XML extrait.

Paramètres

• file (multipart, requis) : Fichier PDF Factur-X
• validate (query, optionnel, défaut : false) : Ajouter une validation complète du XML extrait dans la même réponse
• lang (query, optionnel) : Langue de la réponse (en / fr)

Décompte

1 facture traitée par requête.

Exemple curl

curl -X POST https://api-staging.facturxapi.com/api/v1/extract \
  -H "Authorization: Bearer votre-cle-api" \
  -F "file=@./facture-facturx.pdf"

Réponse (200)

{
  "xml": "PD94bWwgdmVyc2lvbj0iMS4wIj8+...",
  "xmlSize": 2048,
  "profile": "EN16931",
  "filename": "facture.pdf",
  "extractedAt": "2026-04-01T12:00:00Z",
  "durationMs": 42
}

Codes d'erreur spécifiques

• 415 : Le fichier n'est pas un PDF
• 422 : Aucun XML embarqué trouvé dans le PDF

POST /api/v1/convert

Convertit un PDF de facture classique en document Factur-X conforme (PDF/A-3 avec XML CII embarqué). Deux modes sont disponibles : extraction automatique depuis le texte du PDF, ou données structurées fournies depuis l'ERP via le champ invoice_data.

Paramètres

• file (multipart, requis) : Fichier PDF de la facture
• options (form field, optionnel) : Options de conversion au format JSON
  • output_profile : Profil Factur-X cible (défaut : "EN16931")
  • confidence_mode : "strict" (défaut) ou "lenient" pour l'OCR
• invoice_data (form field, optionnel) : Données structurées de la facture au format JSON depuis l'ERP. Quand fourni, l'extraction texte du PDF est ignorée — c'est le mode recommandé pour la production.
• lang (query, optionnel) : Langue de la réponse (en / fr)
• Idempotency-Key (header, optionnel) : Clé d'idempotence pour les retries

Décompte

1 facture traitée par requête.

Exemple curl (mode ERP — recommandé)

curl -X POST https://api-staging.facturxapi.com/api/v1/convert \
  -H "Authorization: Bearer votre-cle-api" \
  -F "file=@./facture.pdf" \
  -F 'invoice_data={
  "invoice_number": "FA-2026-042",
  "issue_date": "2026-04-01",
  "invoice_type": "380",
  "currency": "EUR",
  "seller": {
    "name": "Ma Societe SAS",
    "siret": "12345678900012",
    "vat_id": "FR12345678901",
    "address": {
      "street": "10 rue de Rivoli",
      "city": "Paris",
      "postal_code": "75001",
      "country": "FR"
    }
  },
  "buyer": {
    "name": "Client SA",
    "siret": "98765432100019",
    "address": {
      "city": "Lyon",
      "postal_code": "69002",
      "country": "FR"
    }
  },
  "totals": {
    "net": "1000.00",
    "tax": "200.00",
    "gross": "1200.00",
    "due": "1200.00"
  },
  "tax_breakdown": [
    {
      "rate": "20.00",
      "category": "S",
      "base": "1000.00",
      "amount": "200.00"
    }
  ],
  "line_items": [
    {
      "number": "1",
      "description": "Prestation conseil",
      "quantity": "1",
      "unit": "C62",
      "unit_price": "1000.00",
      "net_amount": "1000.00",
      "vat_rate": "20.00",
      "vat_category": "S"
    }
  ],
  "payment": {
    "due_date": "2026-05-01",
    "terms": "Paiement a 30 jours",
    "iban": "FR7630006000011234567890189"
  }
}'

Exemple curl (mode extraction texte)

curl -X POST https://api-staging.facturxapi.com/api/v1/convert \
  -H "Authorization: Bearer votre-cle-api" \
  -F "file=@./facture.pdf"

Réponse (200)

{
  "success": true,
  "result": {
    "durationMs": 2500,
    "targetProfile": "EN16931",
    "conversionSuccessful": true,
    "xml": "PD94bWwg...",
    "xmlSize": 4096,
    "pdf": "JVBERi0x...",
    "pdfSize": 102400,
    "extraction": {
      "sourceType": "native_text",
      "pageCount": 1
    },
    "validation": {
      "valid": true,
      "profile": "EN16931"
    }
  }
}

Codes d'erreur spécifiques

• 415 : Le fichier n'est pas un PDF
• 422 : Données insuffisantes (insufficient_data) ou confiance OCR trop basse (ocr_confidence_too_low)
• 503 : Service OCR indisponible

POST /api/v1/repair

Analyse un fichier XML CII et applique des corrections automatiques déterministes (format de date, décimaux, namespaces, schemeID manquants, casse devise). Retourne le XML corrigé avec un diff détaillé et la validation avant/après.

Paramètres

• file (multipart, requis) : Fichier XML CII à corriger
• constraints (form field, optionnel) : Contraintes de réparation au format JSON
  • max_changes_allowed : Nombre max de modifications (0–1000)
  • do_not_modify_amounts : Ne pas toucher aux montants (booléen)
  • do_not_invent_missing_parties : Ne pas inventer les parties manquantes (booléen)
• target_profile (query, optionnel) : Profil Factur-X cible
• lang (query, optionnel) : Langue de la réponse (en / fr)
• Idempotency-Key (header, optionnel) : Clé d'idempotence pour les retries

Décompte

1 facture traitée par requête.

Exemple curl

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

Réponse (200)

{
  "durationMs": 124,
  "repaired_xml": "PD94bWwg...",
  "diff_summary": [
    {
      "code": "format_corrected",
      "path": "/rsm:CrossIndustryInvoice/.../ram:IssueDateTime",
      "message": "Corrected date format from '2024-01-15' to '20240115'",
      "ruleReference": "R001"
    }
  ],
  "validation_before": {
    "valid": false,
    "summary": {
      "errorCount": 2,
      "warningCount": 0
    }
  },
  "validation_after": {
    "valid": true,
    "summary": {
      "errorCount": 0,
      "warningCount": 0
    }
  }
}

Codes d'erreur spécifiques

• 415 : Le fichier n'est pas du XML
• 422 : Erreur de parsing XML ou contrainte de réparation dépassée

Format de réponse

Chaque endpoint retourne un objet JSON. Les formats de réponse spécifiques sont documentés dans chaque section d'endpoint ci-dessus. Pour /validate, le format par défaut est le rapport unifié multi-étapes.

Validation — format unifié par défaut (200 OK)

La réponse détaille le verdict global, le temps de traitement, le résumé et les étapes PDF/A-3, Factur-X PDF, XSD et Schematron. Le champ message n'existe que dans le mode legacy.

{
  "valid": true,
  "validatedAt": "2026-04-28T10:00:00.000Z",
  "filename": "facture.xml",
  "profile": "EN16931",
  "durationMs": 124,
  "summary": {
    "errorCount": 0,
    "warningCount": 0
  },
  "issues": [],
  "stages": {
    "pdfa": {
      "passed": true,
      "skipped": true,
      "skip_reason": "XML file - PDF/A validation not applicable",
      "error_count": 0,
      "warning_count": 0,
      "info_count": 0,
      "issues": []
    },
    "facturx_pdf": {
      "passed": true,
      "skipped": true,
      "skip_reason": "XML file - PDF checks not applicable",
      "error_count": 0,
      "warning_count": 0,
      "info_count": 0,
      "issues": []
    },
    "xsd": {
      "passed": true,
      "skipped": false,
      "skip_reason": null,
      "error_count": 0,
      "warning_count": 0,
      "info_count": 0,
      "issues": []
    },
    "schematron": {
      "passed": true,
      "skipped": false,
      "skip_reason": null,
      "error_count": 0,
      "warning_count": 0,
      "info_count": 0,
      "issues": []
    }
  },
  "errors": [],
  "warnings": []
}

Champs

• valid (boolean) : true si la facture est valide, false sinon
• validatedAt (string) : Horodatage ISO du diagnostic
• filename (string|null) : Nom du fichier analysé
• durationMs (number) : Durée du traitement
• summary (object) : Compteurs errorCount et warningCount
• issues (array) : Liste plate des erreurs, avertissements et informations
• stages (object) : Résultat détaillé par étape de validation
• profile (string|null) : Profil Factur-X détecté (EN16931, Basic, Minimum, Extended)
• errors / warnings (array) : Champs de compatibilité pour les anciens clients

Format court legacy (?legacy=true)

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "profile": "EN16931",
  "message": "Validation completed"
}

Structure d'une issue

{
  "code": "BR-CO-10",
  "severity": "error",
  "stage": "schematron",
  "message": "Sum of invoice line net amounts must equal invoice total net amount.",
  "line": 42,
  "location": "line 42",
  "ruleId": "BR-CO-10",
  "xpath": "/rsm:CrossIndustryInvoice/.../ram:SpecifiedTradeSettlementHeaderMonetarySummation"
}

Types d'erreurs

• stage: "pdfa" : conformité PDF/A-3 du conteneur
• stage: "facturx_pdf" : présence et cohérence des métadonnées Factur-X dans le PDF
• stage: "xsd" : structure XML CII
• stage: "schematron" : règles métier EN16931 et profil Factur-X

Exemples de code

curl -X POST https://api-staging.facturxapi.com/api/v1/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./facture.pdf"

// Avec fetch API
const formData = new FormData();
formData.append('file', file);

const response = await fetch('https://api-staging.facturxapi.com/api/v1/validate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});

const result = await response.json();
console.log(result.valid ? '✅ Valid' : '❌ Invalid');
console.log('Errors:', result.errors);
console.log('Profile:', result.profile);

import requests

# Upload et validation
with open('facture.pdf', 'rb') as f:
    response = requests.post(
        'https://api-staging.facturxapi.com/api/v1/validate',
        headers={'Authorization': 'Bearer YOUR_API_KEY'},
        files={'file': f}
    )

result = response.json()
print('✅ Valid' if result['valid'] else '❌ Invalid')
print('Errors:', result['errors'])
print('Profile:', result['profile'])

Codes d'erreur HTTP

Limites

Quota mensuel

Le quota mensuel dépend du rail choisi. En public, retenez surtout : Free = 10 factures traitées / mois, Integration = 500 factures traitées / mois. Les rails guidés (Design Partner, Production Core, SC Partner) se qualifient au cas par cas.

Taille fichier

Taille maximale par défaut : 10 MB

Timeout

Timeout de traitement : 30 secondes (60 secondes pour la conversion avec OCR)

Bonnes pratiques

• Toujours vérifier le champ valid avant de traiter la réponse
• Logger les erreurs de type schematron_failed_assert pour analyse métier
• Gérer les timeouts et les erreurs réseau (429, 500, timeout)
• Ne pas stocker la clé API en dur dans le code (variables d'environnement)
• Implémenter un retry avec backoff exponentiel en cas d'erreur 500 ou 429

Support

Besoin d'aide ? Contactez-nous :

• Email : contact@facturxapi.com