Préparez les Factur-X de vos clients avant le parcours PA/SC.

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.

Référence rapide des URN, schémas XSD et règles Schematron par profil : URN, XSD et Schematron Factur-X.

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.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).

Scan public

Le scan public disponible sur /scan est un diagnostic sans compte. Il ne soumet pas la facture à une Plateforme Agréée et ne doit pas être interprété comme une acceptation PA.

• Le scan peut conclure que le socle Factur-X / EN16931 est exploitable tout en indiquant que France 2026 / France CTC demande des compléments.
• Les compléments listés sont actionnables via /convert uniquement si conversionInputRecipe les expose comme supportés par l'API actuelle.
• Un champ marqué api_gap (limite produit signalée par l’API) est une limite du flux courant, pas une promesse de correction automatique.
• Le statut PA reste non soumis tant qu'aucun retour réel de Plateforme Agréée n'a été reçu.

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

Produit un diagnostic technique pour un PDF Factur-X ou un XML CII. Sans cible France explicite, le socle affiché est Factur-X / EN16931 (PDF/A-3 et XML embarqué pour les PDF, XSD et Schematron EN16931 pour l’XML). La cible France 2026 / France CTC n’est incluse que lorsqu’elle est demandée et exécutable par le runtime.

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
• validation_profile (query, optionnel, défaut : auto) : facturx_en16931_base pour EN16931 uniquement, fr_ctc pour France CTC explicite
• jurisdiction (query, optionnel) : FR avec validation_profile=auto cible France 2026 quand le runtime est disponible

Les contrôles France CTC utilisent les artefacts FNFE-MPE v1.3.1 uniquement quand ils sont exécutés et listés dans appliedValidationProfiles / validationScopeLabel. Si la cible explicite n’est pas exécutable, l’API retourne 422 validation_profile_unavailable. Dans tous les cas, /validate ne soumet pas le document à une Plateforme Agréée et ne vaut pas conformité fiscale finale.

Décompte

1 facture traitée par requête. Si une cible explicite n'est pas exécutable et retourne 422 validation_profile_unavailable, l'échec runtime déterministe n'est pas conservé comme consommation utile.

Exemple curl

curl -X POST https://api.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": "invoice.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,
      "error_count": 0,
      "warning_count": 0,
      "info_count": 0,
      "issues": []
    },
    "schematron": {
      "passed": true,
      "skipped": false,
      "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)
• 422 : Cible de validation demandée mais non exécutable

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.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 en document Factur-X PDF/A-3 avec XML CII embarqué. Le contrat public accepte l'extraction depuis un PDF, un invoice_data complet, ou des compléments inline stateless quand conversionInputRecipe les expose comme supportés.

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 complètes de la facture au format JSON. Quand fourni, l'extraction texte du PDF est ignorée.
• invoice_patch (form field, optionnel) : Complément facture partiel. Support actuel : preceding_invoice.issue_date pour BT-26, avec référence d'origine effective déjà détectée ou fournie de façon cohérente.
• seller_context ou seller_profile_inline (form field, optionnel) : Contexte vendeur inline non persistant pour BT-34 et les mentions BT-22 PMT/PMD/AAB.
• buyer_context ou buyer_profile_inline (form field, optionnel) : Contexte acheteur inline non persistant pour BT-49.
• lang (query, optionnel) : Langue de la réponse (en / fr)
• Idempotency-Key (header, optionnel) : Clé d'idempotence pour les retries. Le hash inclut invoice_patch, seller_context et buyer_context.

invoice_patch et les contextes inline ne doivent pas écraser silencieusement une valeur visible dans le PDF/XML. En cas de désaccord document/contexte, l'API retourne 409 inline_context_conflict. invoice_patch ne se combine pas avec invoice_data complet.

Décompte

1 facture traitée par requête. Le mode dry_run=true sert au diagnostic de préparation et ne produit pas le PDF final ; il accepte aussi les uploads XML pour diagnostic, sans packaging Factur-X.

Exemple curl (mode ERP — recommandé)

curl -X POST https://api.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.facturxapi.com/api/v1/convert \
  -H "Authorization: Bearer votre-cle-api" \
  -F "file=@./facture.pdf"

Exemple curl (avoir DI 0414 avec compléments France 2026)

curl -X POST https://api.facturxapi.com/api/v1/convert \
  -H "Authorization: Bearer votre-cle-api" \
  -H "Idempotency-Key: di-0414-2026-05-05-001" \
  -F "file=@./avoir-nicolas.pdf" \
  -F 'invoice_patch={"preceding_invoice":{"issue_date":"2025-08-31"}}' \
  -F 'seller_context={"electronic_address":{"value":"12345678900015","scheme_id":"0002"},"document_notes":[{"subject_code":"PMT","content":"Paiement par virement a reception de facture"},{"subject_code":"PMD","content":"Aucun escompte pour paiement anticipe"},{"subject_code":"AAB","content":"Indemnite forfaitaire de recouvrement applicable"}]}' \
  -F 'buyer_context={"electronic_address":{"value":"98765432100011","scheme_id":"0002"}}'

Payload inline envoyé

{
  "invoice_patch": {
    "preceding_invoice": {
      "issue_date": "2025-08-31"
    }
  },
  "seller_context": {
    "electronic_address": {
      "value": "12345678900015",
      "scheme_id": "0002"
    },
    "document_notes": [
      {
        "subject_code": "PMT",
        "content": "Paiement par virement a reception de facture"
      },
      {
        "subject_code": "PMD",
        "content": "Aucun escompte pour paiement anticipe"
      },
      {
        "subject_code": "AAB",
        "content": "Indemnite forfaitaire de recouvrement applicable"
      }
    ]
  },
  "buyer_context": {
    "electronic_address": {
      "value": "98765432100011",
      "scheme_id": "0002"
    }
  }
}

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

• 400 invalid_invoice_patch : invoice_patch combiné avec invoice_data complet, ou JSON non objet
• 409 inline_context_conflict : Complément inline en conflit avec une valeur visible dans le document
• 415 : Le fichier n'est pas un PDF
• 422 invalid_invoice_patch : Date impossible ou champ inline invalide
• 422 insufficient_data : BT-26 fourni sans référence de facture d'origine effective, données insuffisantes, 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.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é, les étapes PDF/A-3, Factur-X PDF, XSD et Schematron, ainsi que le périmètre exécuté. Le champ message n'existe que dans le mode legacy.

{
  "valid": true,
  "validatedAt": "2026-04-28T10:00:00.000Z",
  "filename": "invoice.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,
      "error_count": 0,
      "warning_count": 0,
      "info_count": 0,
      "issues": []
    },
    "schematron": {
      "passed": true,
      "skipped": false,
      "error_count": 0,
      "warning_count": 0,
      "info_count": 0,
      "issues": []
    }
  },
  "errors": [],
  "warnings": []
}

Champs

• valid (boolean) : true si aucune erreur n’est détectée dans le périmètre exécuté, 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
• validationScopeLabel / appliedValidationProfiles : périmètre réellement exécuté (EN16931 seul ou France CTC si demandé et disponible)
• skippedValidationProfiles / unsupportedValidationProfiles : cible demandée mais non exécutée ou non supportée
• legalDisclaimer : mention à afficher aux utilisateurs; le diagnostic ne vaut pas acceptation PA
• 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.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.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

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