API de conversion Factur-X : guide d'intégration pour développeurs

L'interface web Facturio est idéale pour des conversions ponctuelles. Mais si vous traitez des dizaines ou centaines de factures par mois, l'API REST permet d'automatiser entièrement le flux.

Cas d'usage typiques : • Intégration dans un ERP : vos factures fournisseurs arrivent par email, un script les envoie à l'API et récupère le Factur-X. • Plateforme Agréée : vous développez une PA et souhaitez ajouter la conversion de factures étrangères. • Éditeur comptable : vous intégrez la conversion comme fonctionnalité de votre logiciel. • Workflow automatisé : Zapier, Make, n8n — l'API s'intègre dans n'importe quel outil d'automatisation.

L'API est disponible à partir du plan Business (€149 HT/mois, 500 conversions incluses).

L'API utilise des clés API pour l'authentification. Chaque clé est préfixée fio_live_ et transmise dans le header HTTP.

Créer une clé API : Depuis votre tableau de bord → Clés API → Créer une clé. La clé complète n'est affichée qu'une seule fois. Stockez-la en lieu sûr (variable d'environnement, secret manager).

Header d'authentification : X-API-Key: fio_live_a3b2c4d5e6f7...

Sécurité : • Ne commitez jamais vos clés dans un dépôt Git • Utilisez des variables d'environnement • Chaque clé peut être révoquée individuellement • Le plan Business permet 5 clés, le plan Enterprise jusqu'à 20

L'endpoint de conversion accepte un fichier PDF et retourne un identifiant de conversion.

Requête : POST https://api.getfacturio.com/v1/convert Content-Type: multipart/form-data X-API-Key: fio_live_xxx

Champs du formulaire : • file (obligatoire) : le fichier PDF à convertir • format (optionnel) : facturx_en16931 (défaut), facturx_minimum, facturx_basic, facturx_extended, ubl

Réponse (202 Accepted) : {"success": true, "data": {"id": "conv-xxx", "status": "pending", "estimated_time_ms": 60000}}

La conversion est asynchrone. L'API retourne immédiatement l'identifiant, et vous pollez le statut ou configurez un webhook pour être notifié.

Méthode 1 : Polling Appelez GET /v1/status/{id} toutes les 2 secondes. Quand le statut passe à completed, la réponse inclut l'URL de téléchargement.

GET /v1/status/conv-xxx

Réponse (completed) : {"data": {"id": "conv-xxx", "status": "completed", "result": {"confidence": 0.95, "download_url": "/v1/convert/conv-xxx/download", "xsd_valid": true}}}

Méthode 2 : Webhooks (Enterprise) Configurez un endpoint de callback. Facturio envoie un POST avec le payload signé (HMAC-SHA256) quand la conversion est terminée.

Événements disponibles : • conversion.completed — conversion réussie • conversion.failed — échec de la conversion • conversion.started — conversion démarrée

Chaque payload inclut un header X-Facturio-Signature que vous devez vérifier côté serveur.

Une fois la conversion terminée, téléchargez le résultat :

GET /v1/convert/{id}/download X-API-Key: fio_live_xxx

La réponse est le fichier binaire : • Factur-X : Content-Type: application/pdf (PDF/A-3 avec XML embarqué) • UBL : Content-Type: application/xml

Le header Content-Disposition contient le nom de fichier suggéré : facture_facturx.pdf ou facture_ubl.xml.

Le lien est valide 24 heures. Au-delà, relancez la conversion.

Le plan Business et supérieur permet le batch upload : envoyez jusqu'à 50 fichiers PDF en une seule requête.

POST /v1/batch Content-Type: multipart/form-data

Attachez les fichiers avec le champ files (ou plusieurs champs file). L'API retourne un batch_id et la liste des conversion_ids.

Réponse : {"data": {"batch_id": "batch-xxx", "conversion_ids": ["conv-001", "conv-002", ...], "total": 10}}

Suivez l'avancement avec GET /v1/batch/{batch_id}. Le statut agrégé peut être : processing, completed, partial (certains réussis, d'autres échoués), ou failed.

L'API utilise le format RFC 7807 (Problem Details) pour les erreurs.

Exemple : {"type": "https://api.getfacturio.com/errors/quota-exceeded", "title": "Quota de conversions dépassé", "status": 429, "detail": "Limite de 500 conversions/mois atteinte."}

Codes d'erreur fréquents : • 401 : clé API invalide ou absente • 413 : fichier trop volumineux • 415 : fichier non PDF • 422 : extraction ou conversion échouée • 429 : quota dépassé ou trop de requêtes

Rate limiting : • Business : 60 requêtes/minute • Enterprise : 120 requêtes/minute

Les headers de réponse incluent X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset.