Documentation API · v1
Validez et générez du Factur-X depuis votre code
Deux endpoints REST, authentifiés par clé API. Les fichiers sont traités en mémoire et jamais conservés — vous pouvez y envoyer des factures réelles. 1 000 appels par mois inclus dans le plan API (49 € TTC/mois), puis 0,05 € par appel.
Authentification
Passez votre clé dans l'en-tête Authorization: Bearer fxk_…. Les clés se créent dans votre espace client et sont stockées hachées : conservez-les dans un gestionnaire de secrets.
POST /api/v1/validate
Envoie un fichier .pdf (Factur-X) ou .xml (CII) en multipart, champ file. Renvoie un rapport JSON : verdict, profil détecté, erreurs traduites en français avec piste de correction.
curl -X POST https://facturxapp.com/api/v1/validate \
-H "Authorization: Bearer fxk_votre_cle" \
-F "[email protected]"{
"valid": false,
"profile_label": "EN 16931",
"errors": [
{
"rule_id": "BR-CO-15",
"severity": "fatal",
"message": "Invoice total amount with VAT = ...",
"message_fr": "Le total TTC doit être égal au total HT plus la TVA.",
"hint_fr": "Recalculez GrandTotalAmount = TaxBasisTotalAmount + TaxTotalAmount."
}
],
"pdfa3_checks": [ { "id": "pdfa-xmp", "passed": true } ]
}POST /api/v1/generate
Reçoit un payload JSON décrivant la facture, renvoie le PDF Factur-X (PDF/A-3, profil EN 16931, XML CII embarqué). Ajoutez source_pdf_base64pour embarquer le XML dans votre propre PDF plutôt que dans un visuel généré. Chaque fichier produit est auto-validé avant d'être renvoyé.
curl -X POST https://facturxapp.com/api/v1/generate \
-H "Authorization: Bearer fxk_votre_cle" \
-H "Content-Type: application/json" \
-d '{
"invoice": {
"invoice_number": "FA-2026-042",
"issue_date": "2026-06-15",
"seller": {
"name": "Atelier Numérique SARL",
"siren": "123456789",
"vat_number": "FR32123456789",
"address": { "line1": "12 rue de la République", "postcode": "69001", "city": "Lyon", "country": "FR" }
},
"buyer": {
"name": "Client Conseil SAS",
"address": { "country": "FR" }
},
"lines": [
{ "description": "Développement web", "quantity": "10", "unit_price": "85.00", "vat_rate": "20" }
]
}
}' \
--output facture-facturx.pdfExemples
const form = new FormData();
form.append("file", fs.createReadStream("facture.pdf"));
const res = await fetch("https://facturxapp.com/api/v1/validate", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.FACTURX_API_KEY}` },
body: form,
});
const report = await res.json();
if (!report.valid) {
for (const err of report.errors) {
console.log(`${err.rule_id}: ${err.message_fr}`);
}
}import os
import requests
with open("facture.pdf", "rb") as f:
res = requests.post(
"https://facturxapp.com/api/v1/validate",
headers={"Authorization": f"Bearer {os.environ['FACTURX_API_KEY']}"},
files={"file": f},
)
report = res.json()
if not report["valid"]:
for err in report["errors"]:
print(err["rule_id"], "-", err["message_fr"])Codes d'erreur
| HTTP | Code | Signification |
|---|---|---|
| 400 | missing_file / missing_invoice | Requête incomplète (fichier ou payload manquant). |
| 401 | unauthorized | Clé API absente, invalide ou révoquée. |
| 402 | payment_required | Le plan API n'est pas actif sur ce compte. |
| 413 | file_too_large | Fichier supérieur à 10 Mo. |
| 415 | unsupported_type | Seuls les fichiers PDF et XML sont acceptés. |
| 422 | generation_failed | Payload de facture invalide (détail dans `error.details`). |
| 503 | service_unavailable | Service d'analyse momentanément indisponible. |
Toutes les erreurs suivent le format { "error": { "code", "message" } }. L'en-tête de réponse X-Calls-Used indique votre consommation du mois.
Limites et bonnes pratiques
- Fichiers : 10 Mo maximum, PDF et XML uniquement.
- Aucun fichier n'est conservé : re-soumettez le fichier si vous avez besoin d'une nouvelle analyse.
- Montants : envoyez des chaînes décimales (
"85.00") pour éviter les flottants. - Profil généré : EN 16931 (le plus large accepté en B2B France).