Documentation API

Introduction

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

La validation inclut :

• XSD : Vérification de la structure XML contre le schéma officiel
• Schematron : Validation des règles métier EN16931 (assertions business)
• Extraction PDF : Extraction automatique du XML embarqué dans les PDF Factur-X

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 2024-2026, 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).

Endpoint de validation

POST /api/v1/validate

Valide un fichier Factur-X (PDF ou XML).

Request

• Method : POST
• Content-Type : multipart/form-data
• Body : Champ file contenant le fichier PDF ou XML
• Max file size : 10 MB (configurable)

Headers

Authorization: Bearer YOUR_API_KEY

Format de réponse

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 "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

Rate Limiting

Les requêtes sont limitées selon votre plan :

• Free : 10 validations / mois
• Pro : 1 000 validations / mois
• Business : 100 000+ validations / mois

Taille fichier

Taille maximale par défaut : 10 MB

Timeout

Timeout de traitement : 30 secondes

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
• GitHub : github.com/facturxapi