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 : Génération d'un Factur-X PDF/A-3 avec contrôles de sortie
• 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 champs guidés supportés.
• Un point nécessitant une vérification manuelle doit être traité séparément ; ce n’est 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_target (query, recommandé) : en16931 pour le socle Factur-X / EN16931, france_2026 pour EN16931 + exigences France 2026 / FNFE-MPE disponibles
• validation_profile, jurisdiction, require_profile (query, legacy) : contrôles historiques encore acceptés pour les intégrations existantes

La réponse inclut toujours target.requested, target.executed, target.status, target.missing_inputs et target.not_run_reason. 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?validation_target=en16931 \
  -H "Authorization: Bearer votre-cle-api" \
  -F "file=@./facture.pdf"

Réponse par défaut (200)

{
  "valid": true,
  "target": {
    "requested": "en16931",
    "executed": "en16931",
    "status": "verified",
    "missing_inputs": [],
    "not_run_reason": null
  },
  "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",
  "target": {
    "requested": "en16931",
    "executed": "en16931",
    "status": "verified",
    "missing_inputs": [],
    "not_run_reason": null
  }
}

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.

Choisissez toujours la cible avec validation_target. en16931 vérifie le socle Factur-X / EN16931. france_2026 inclut EN16931 plus les exigences françaises FNFE-MPE disponibles dans le runtime. L'API ne soumet pas la facture à une Plateforme Agréée et ne retourne jamais une acceptation PA.

En dry_run=true, la réponse France 2026 inclut targetPreflight. Si targetPreflight.exhaustive vaut false, utilisez targetPreflight.status, targetPreflight.exhaustive et les blockers structurés pour afficher une copie produit validée, sans présenter la checklist comme complète. Les champs de targetPreflight.requiredInputs doivent être envoyés via les racines partielles déclarées par la recette : invoice_patch, seller_context et buyer_context, jamais comme un invoice_data partiel.

Le replay final France 2026 doit reprendre la structure de conversionInputRecipe.examplePayload retournée par votre dry-run, puis remplacer toute valeur modèle par des valeurs réelles confirmées. Ne lancez ce replay que si targetPreflight.exhaustive=true et si targetPreflight.unsupportedBlockers est vide ; sinon gardez le résultat comme diagnostic et exposez les blockers restants.

Si une recette ou un préflight expose un blocker technique comme api_gap, ne proposez pas de replay final : le champ doit d'abord être couvert par conversionInputRecipe.requiredInputs, une correction automatique documentée, ou une décision produit explicite côté API.

Paramètres

• file (multipart, requis) : Fichier PDF de la facture
• validation_target (form field, recommandé) : en16931 pour un Factur-X EN16931, france_2026 pour EN16931 + contrôles France 2026 / FNFE-MPE disponibles.
• 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
  • validation_target peut aussi être envoyé dans options si votre client préfère garder tous les réglages en JSON.
• 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, et payment.iban pour BT-84 quand le compte vendeur manque au document.
• 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 "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": "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 "validation_target=en16931" \
  -F "file=@./facture.pdf"

Exemple curl (dry-run France 2026 avec targetPreflight)

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

Replay final France 2026 après dry-run exhaustif

Utilisez les racines et chemins indiqués par le conversionInputRecipe.examplePayload de votre dry-run, puis remplacez les exemples par des valeurs réelles confirmées. Les valeurs modèles inchangées sont refusées par l'API ; cet exemple prouve le chemin dry_run → recette exploitable → /convert final, pas qu’un IBAN seul suffit pour France 2026.

curl -X POST https://api.facturxapi.com/api/v1/convert \
  -H "Authorization: Bearer votre-cle-api" \
  -H "Idempotency-Key: facture-france-2026-001" \
  -F "validation_target=france_2026" \
  -F "file=@./facture.pdf" \
  -F 'invoice_patch={"payment":{"iban":"FR7630006000011234567890189"}}' \
  -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"}}'

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 "validation_target=france_2026" \
  -F 'invoice_patch={"preceding_invoice":{"issue_date":"2025-08-31"},"payment":{"iban":"FR7630006000011234567890189"}}' \
  -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"
    },
    "payment": {
      "iban": "FR7630006000011234567890189"
    }
  },
  "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,
  "target": {
    "requested": "en16931",
    "executed": "en16931",
    "status": "verified",
    "missing_inputs": [],
    "not_run_reason": null
  },
  "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"
    }
  }
}

Réponse avec compléments manquants

{
  "success": false,
  "dry_run": true,
  "target": {
    "requested": "france_2026",
    "executed": null,
    "status": "blocked",
    "missing_inputs": [
      "seller_context.electronic_address.value",
      "buyer_context.electronic_address.value"
    ],
    "not_run_reason": "missing_inputs"
  },
  "verdict": "convert_with_inputs",
  "missing_fields": [
    "seller_context.electronic_address.value",
    "buyer_context.electronic_address.value"
  ],
  "targetPreflight": {
    "requested": "france_2026",
    "status": "incomplete",
    "exhaustive": false,
    "remainingAfterInputsPolicy": "unknown",
    "requiredInputs": [
      {
        "btCode": "BT-84",
        "ruleRef": "FX-SCH-A-000132",
        "requestContextPath": "invoice_patch.payment.iban"
      },
      {
        "btCode": "BT-34",
        "ruleRef": "BR-FR-13_BT-34",
        "requestContextPath": "seller_context.electronic_address.value"
      },
      {
        "btCode": "BT-49",
        "ruleRef": "BR-FR-12_BT-49",
        "requestContextPath": "buyer_context.electronic_address.value"
      }
    ],
    "automaticFixes": [],
    "unsupportedBlockers": []
  }
}

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...",
  "target": {
    "requested": "en16931",
    "executed": "en16931",
    "status": "verified",
    "missing_inputs": [],
    "not_run_reason": null
  },
  "repairSuccessful": true,
  "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,
    "target": {
      "requested": "en16931",
      "executed": "en16931",
      "status": "failed",
      "missing_inputs": [],
      "not_run_reason": null
    },
    "summary": {
      "errorCount": 2,
      "warningCount": 0
    }
  },
  "validation_after": {
    "valid": true,
    "target": {
      "requested": "en16931",
      "executed": "en16931",
      "status": "verified",
      "missing_inputs": [],
      "not_run_reason": null
    },
    "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,
  "target": {
    "requested": "en16931",
    "executed": "en16931",
    "status": "verified",
    "missing_inputs": [],
    "not_run_reason": null
  },
  "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",
  "target": {
    "requested": "en16931",
    "executed": "en16931",
    "status": "verified",
    "missing_inputs": [],
    "not_run_reason": null
  }
}

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 : contact@facturxapi.com