Documentation API

Deux endpoints : POST /api/generate génère une facture XML conforme EN 16931 (profil Factur-X, syntaxe CII) à partir de JSON ; POST /api/validate valide une facture existante. Les montants sont calculés côté serveur et chaque XML généré est auto-validé (XSD + Schematron EN 16931) avant d'être renvoyé.

Authentification

Toutes les requêtes API exigent l'en-tête X-API-Key. Obtenez votre clé gratuitement sur la page Tarifs.

X-API-Key: facturx_...

Sans clé ou avec une clé invalide : 401 {"error": "Invalid or missing API key"}.

POST /api/generate

Génère une facture EN 16931 (XML CII, téléchargeable directement). Quota : 5 factures/mois en gratuit, 500/mois en Pro (fenêtre = mois calendaire UTC, remise à zéro le 1er du mois).

Exemple de requête

curl -X POST https://factur-x-api.com/api/generate \
  -H "X-API-Key: facturx_..." \
  -H "Content-Type: application/json" \
  -o facture.xml \
  -d '{
    "invoiceNumber": "F-2026-001",
    "issueDate": "2026-10-09",
    "currency": "EUR",
    "seller": {
      "name": "Ma Société SARL",
      "countryCode": "FR",
      "vatId": "FR12345678901"
    },
    "buyer": {
      "name": "Client SAS",
      "countryCode": "FR"
    },
    "lines": [
      {
        "description": "Prestation de conseil",
        "quantity": 2,
        "unitPrice": 500.00,
        "vatRate": 20
      }
    ],
    "payment": {
      "iban": "FR7630006000011234567890189",
      "dueDate": "2026-11-08"
    }
  }'

Champs

Champ	Requis	Description
invoiceNumber	oui	Numéro de facture (BT-1)
issueDate	oui	Date d'émission, ISO `AAAA-MM-JJ` (BT-2)
currency	oui	Code devise ISO 4217, ex. `EUR` (BT-5)
typeCode	non	Type de document, défaut `380` (facture) (BT-3)
seller / buyer	oui	Voir tableau ci-dessous
lines[]	oui	Au moins une ligne (voir ci-dessous)
payment	non	`iban` (BT-91), `paymentReference` (BT-83), `dueDate` (BT-9)
note	non	Note libre (BT-22)

seller / buyer

Champ	Requis	Description
name	oui	Raison sociale (BT-27 / BT-44)
countryCode	oui	Code pays ISO 3166-1 alpha-2 (BT-40 / BT-55)
vatId	vendeur*	N° TVA intracommunautaire (BT-31 / BT-48)
legalOrgId	vendeur*	SIREN / identifiant légal (BT-30)
postcode, lineOne, city	non	Adresse (BT-35/37/38 / BT-50/52/53)

* Le vendeur doit fournir vatId ou legalOrgId (au moins l'un des deux, règle BR-CO-26).

lines[]

Champ	Requis	Description
description	oui	Libellé de la ligne (BT-153)
quantity	oui	Quantité > 0 (BT-129)
unitPrice	oui	Prix unitaire HT (hors TVA) (BT-146)
vatRate	oui	Taux de TVA en %, ex. `20` (BT-152)
unitCode	non	Unité UN/ECE, défaut `C62` (pièce) (BT-130)
vatCategoryCode	non	Catégorie TVA, défaut `S`. Taux 0 % → `Z` (exonéré) (BT-151)

Les montants totaux (HT, TVA, TTC) sont calculés côté serveur : il n'y a rien à fournir, et aucune incohérence n'est possible. ⚠️ Une ligne vatRate: 0 avec la catégorie par défaut S viole la règle BR-S-05 : utilisez vatCategoryCode: "Z".

Réponse

Succès : 200, corps = le XML (Content-Type: application/xml, pièce jointe invoice-F-2026-001.xml), auto-validé EN 16931 avant envoi.

Code	Signification
400	Corps JSON invalide ou champ requis manquant
401	Clé API absente ou invalide
402	Quota mensuel épuisé. En-têtes `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` ; corps contient `upgrade_url`
422	Données métier invalides (ex. vendeur sans vatId ni legalOrgId)

Les réponses réussies incluent X-RateLimit-Limit et X-RateLimit-Remaining pour suivre votre quota. Les requêtes rejetées avant traitement (400/401) ne consomment pas de quota.

POST /api/validate

Valide une facture Factur-X / ZUGFeRD (PDF avec XML embarqué, ou XML CII brut) contre les XSD D16B et les règles Schematron EN 16931. Gratuit et illimité pour tous les plans.

Exemple de requête

curl -X POST https://factur-x-api.com/api/validate \
  -H "X-API-Key: facturx_..." \
  -F "file=@facture.pdf"

Réponse

{
  "valid": false,
  "errors": [
    {
      "rule": "BR-07",
      "message": "Le nom de l'acheteur doit être renseigné.",
      "location": "..."
    }
  ],
  "warnings": []
}

Code	Signification
200	Validation effectuée (`valid: true/false`)
400	Fichier vide ou format non pris en charge (PDF ou XML attendu, 10 Mo max)
401	Clé API absente ou invalide
422	PDF sans XML embarqué (ce n'est pas une facture Factur-X)

Quotas

Endpoint	Gratuit	Pro (9 $/mois)
/api/generate	5 / mois	500 / mois
/api/validate	illimité	illimité

Comptage par mois calendaire UTC, remise à zéro automatique le 1er de chaque mois. Passage en Pro sur la page Tarifs.