Documentation API

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 opérations 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 de dématérialisation (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 de Dématérialisation Partenaires (PDP) agréées peuvent générer et transmettre des factures Factur-X vers Chorus Pro.

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 UE : Serveurs Cloudflare en Europe (RGPD-compliant)
• Chiffrement TLS : Toutes les communications sont chiffrées (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 disponible pour les clients Business

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

Base URL

https://api.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 validations/mois).

Endpoints

L'API expose quatre endpoints. Chaque requête consomme un certain nombre d'unités de quota selon l'opération.

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)

Quota

1 unité par requête.

Exemple curl

curl -X POST https://api.facturxapi.com/api/v1/validate \
  -H "X-API-Key: votre-cle-api" \
  -F "[email protected]"

Réponse (200)

{
  "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) : Lancer une validation complète après extraction (consomme 2 unités de quota au lieu de 1)
• lang (query, optionnel) : Langue de la réponse (en / fr)

Quota

1 unité (2 avec validate=true).

Exemple curl

curl -X POST https://api.facturxapi.com/api/v1/extract \
  -H "X-API-Key: votre-cle-api" \
  -F "[email protected]"

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

Quota

5 unités (texte natif) à 15 unités (OCR selon le nombre de pages).

Exemple curl (mode ERP — recommandé)

curl -X POST https://api.facturxapi.com/api/v1/convert \
  -H "X-API-Key: votre-cle-api" \
  -F "[email protected]" \
  -F 'invoice_data={"invoiceNumber":"FA-2026-042","issueDate":"20260401","seller":{"name":"Ma Société SAS","vatId":"FR12345678901","address":{"street":"10 Rue de Rivoli","city":"Paris","postalCode":"75001","country":"FR"}},"buyer":{"name":"Client SA","address":{"country":"FR"}},"currencyCode":"EUR","lines":[{"description":"Prestation conseil","quantity":1,"unitPrice":1000,"vatRate":20,"vatCategory":"S"}],"totals":{"netAmount":1000,"vatAmount":200,"grossAmount":1200,"dueAmount":1200}}'

Exemple curl (mode extraction texte)

curl -X POST https://api.facturxapi.com/api/v1/convert \
  -H "X-API-Key: votre-cle-api" \
  -F "[email protected]"

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

Quota

2 unités par requête.

Exemple curl

curl -X POST https://api.facturxapi.com/api/v1/repair \
  -H "X-API-Key: votre-cle-api" \
  -F "[email protected]"

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. Voici le format commun pour l'endpoint de validation.

Validation — Succès (200 OK)

La réponse contient toujours un objet JSON avec les champs suivants :

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

Champs

• valid (boolean) : true si la facture est valide, false sinon
• errors (array) : Liste des erreurs de validation
• warnings (array) : Liste des avertissements (non-bloquants)
• profile (string|null) : Profil Factur-X détecté (EN16931, Basic, Minimum, Extended)
• message (string|null) : Message de synthèse

Structure d'une erreur

{
  "type": "xsd_validation_error",
  "message": "Element 'invoice': Missing child element(s). Expected is ( number ).",
  "line": "5"
}

Types d'erreurs

• xsd_validation_error : Erreur de structure XML (schéma XSD)
• schematron_failed_assert : Erreur de règle métier EN16931
• pdf_processing_error : Erreur d'extraction XML depuis PDF

Exemples de code

curl -X POST https://api.facturxapi.com/api/v1/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

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

const response = await fetch('https://api.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.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

Quotas

Chaque opération consomme un nombre d'unités de quota. Le quota mensuel dépend de votre plan :

• Free : 10 unités / mois
• Pro : 1 000 unités / mois
• Business : 10 000 unités / mois

Coût par opération

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 : [email protected]