Aller au contenu

Démarrage rapide

Cinq minutes entre zéro et une facture Factur-X conforme.

1. Obtenir une clé API

  • Valider / extraire : aucune clé nécessaire, jusqu'à 20 requêtes par minute et par IP.
  • Générer / incorporer : prenez une clé sur la page des tarifs (plan Free à 0 €, 50 documents par mois, sans carte). La clé affichée après le paiement est votre clé API ; envoyez-la dans Authorization: Bearer <clé>. La même clé ouvre le serveur MCP.

2. Décrire la facture

Les montants sont des chaînes décimales ("1200.00"), les dates au format ISO 8601. Les totaux et la ventilation de TVA sont calculés côté serveur ; ne les envoyez que pour forcer une valeur.

facture.json
{
  "number": "F-2026-0042",
  "issue_date": "2026-09-01",
  "due_date": "2026-10-01",
  "seller": {
    "name": "Atelier Numérique SAS",
    "siren": "732829320",
    "vat_id": "FR40732829320",
    "legal_info": "SAS au capital de 10 000 € - RCS Paris 732 829 320",
    "address": {"line1": "12 rue de la Paix", "postal_code": "75002", "city": "Paris", "country": "FR"}
  },
  "buyer": {
    "name": "Boulangerie Dupont SARL",
    "siren": "552081317",
    "vat_id": "FR09552081317",
    "address": {"line1": "8 avenue des Champs", "postal_code": "69002", "city": "Lyon", "country": "FR"}
  },
  "payment": {"means_code": "30", "iban": "FR7630006000011234567890189", "terms": "Paiement à 30 jours."},
  "lines": [
    {"item_name": "Développement site web", "quantity": "1", "unit_price": "2500.00", "vat_rate": "20"},
    {"item_name": "Hébergement annuel", "quantity": "12", "unit_code": "MON", "unit_price": "15.00", "vat_rate": "20"}
  ]
}

Vendeurs français

Renseignez siren (l'API déduit le schéma 0002), vat_id et une adresse postale complète. Les trois mentions obligatoires françaises (pénalités de retard, indemnité forfaitaire de 40 €, escompte) sont ajoutées automatiquement en notes ; personnalisez-les avec french_mentions.

3. Générer

curl -X POST https://facturx.orvel.dev/v1/invoices/generate \
  -H "Authorization: Bearer $FACTURX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoice": '"$(cat facture.json)"', "options": {"profile": "en16931", "language": "fr"}}' \
  -o F-2026-0042-facturx.pdf -D -

import httpx, json

facture = json.load(open("facture.json"))
r = httpx.post(
    "https://facturx.orvel.dev/v1/invoices/generate",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"invoice": facture, "options": {"profile": "en16931", "output": "facturx-pdf"}},
    timeout=60,
)
r.raise_for_status()
open("facture-facturx.pdf", "wb").write(r.content)
print(r.headers["X-Facturx-Amount-Due"])  # "3278.98"

const invoice = JSON.parse(fs.readFileSync("facture.json", "utf8"));
const res = await fetch("https://facturx.orvel.dev/v1/invoices/generate", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.FACTURX_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ invoice, options: { profile: "en16931" } }),
});
if (!res.ok) throw new Error(await res.text());
fs.writeFileSync("facture-facturx.pdf", Buffer.from(await res.arrayBuffer()));

La réponse est le fichier PDF/A-3. En-têtes utiles : X-Facturx-Profile, X-Facturx-Amount-Due, X-Facturx-Warnings, X-Usage-Used, X-Usage-Quota.

Vous voulez seulement le XML ? Passez "output": "cii-xml" ou "ubl-xml". Vous voulez une enveloppe JSON avec le fichier en base64, les totaux calculés et le rapport de validation ? Envoyez Accept: application/json.

4. Valider n'importe quel fichier

curl -X POST "https://facturx.orvel.dev/v1/invoices/validate?check=fr-ctc" \
  -F file=@facture-fournisseur.pdf

{
  "valid": false,
  "flavor": "factur-x",
  "profile": "en16931",
  "checks_run": ["pdf", "xsd", "schematron:base", "schematron:fr-ctc"],
  "error_count": 1,
  "findings": [
    {"source": "schematron:fr-ctc", "severity": "error", "rule": "BR-FR-08",
     "message": "[BR-FR-08] Le SIREN du vendeur (BT-30) doit être cohérent avec le SIRET ...",
     "location": "/rsm:CrossIndustryInvoice/..."}
  ],
  "pdf": {"pages": 1, "attachments": ["factur-x.xml"], "pdfa": "3B", "facturx_xmp": "EN 16931"}
}

5. Lire une facture reçue

curl -X POST "https://facturx.orvel.dev/v1/invoices/extract?include_xml=false" \
  -F file=@facture-fournisseur.pdf

Renvoie fields (numéro, dates, vendeur, acheteur, totaux, ventilation de TVA, lignes) et, sauf désactivation, le XML incorporé brut.

Ensuite