Aller au contenu

Démarrage rapide

Accès mis à jour

Essayez les exemples fixes sans clé. Vos documents nécessitent une clé. Les nouvelles clés gratuites et d’essai sont fermées ; les clés existantes conservent leur quota.

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

1. Obtenir une clé API

Essayez les exemples fixes sans clé. Pour générer, incorporer, valider ou extraire vos documents, choisissez un forfait payant, copiez la clé après paiement et envoyez Authorization: Bearer <clé>.

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

Définissez FACTURX_API_KEY dans votre environnement. L'exemple curl utilise Bash ; Python nécessite httpx (python -m pip install httpx) ; Node nécessite Node.js 22+ et un fichier .mjs. Chaque génération réussie consomme votre quota.

curl --fail --silent --show-error --max-time 60 -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 json
import os
from pathlib import Path

import httpx

API_KEY = os.environ["FACTURX_API_KEY"]
facture = json.loads(Path("facture.json").read_text(encoding="utf-8"))
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()
if r.headers.get("content-type", "").split(";")[0] != "application/pdf" or not r.content.startswith(b"%PDF-"):
    raise RuntimeError("Expected a PDF response")
with open("facture-facturx.pdf", "xb") as output:
    output.write(r.content)
print(r.headers["X-Facturx-Amount-Due"])  # "3216.00"

import fs from "node:fs";

const apiKey = process.env.FACTURX_API_KEY;
if (!apiKey) throw new Error("Set FACTURX_API_KEY");
const invoice = JSON.parse(fs.readFileSync("facture.json", "utf8"));
const res = await fetch("https://facturx.orvel.dev/v1/invoices/generate", {
  method: "POST",
  redirect: "error",
  signal: AbortSignal.timeout(60_000),
  headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
  body: JSON.stringify({ invoice, options: { profile: "en16931" } }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}; check invoice fields, key and quota`);
const pdf = Buffer.from(await res.arrayBuffer());
if (res.headers.get("content-type")?.split(";")[0] !== "application/pdf" || pdf.subarray(0, 5).toString() !== "%PDF-") {
  throw new Error("Expected a PDF response");
}
fs.writeFileSync("facture-facturx.pdf", pdf, { flag: "wx" });

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.

Exemple exécutable : PDF et rapport en un appel

Téléchargez generate.mjs et invoice.json dans le même dossier. Le JSON est une fixture de démonstration, pas une facture à envoyer ni une preuve d'identité des entreprises. Avec Node.js 22+ et FACTURX_API_KEY défini, exécutez :

node generate.mjs invoice.json

Le script effectue un seul appel avec Accept: application/json. Il exige le succès des contrôles XSD, EN 16931 et fr-ctc, sans contrôle ignoré, puis écrit invoice.pdf et validation.json dans un nouveau sous-dossier de facturx-output. Les deux fichiers contiennent les données de facture : gardez-les privés. Le montant attendu pour cet exemple est 3 216,00 EUR (2 680,00 EUR HT et 536,00 EUR de TVA).

Le rapport décrit les contrôles effectués par le service sur le XML généré ; il ne constitue pas une vérification PDF/A indépendante ni une preuve de réception par une PA. Le script ne réessaie pas automatiquement : après une interruption réseau, vérifiez le quota avant de relancer. Aucune deuxième requête de validation n'est nécessaire pour obtenir ce rapport.

4. Valider n'importe quel fichier

curl --fail --silent --show-error --max-time 60 -X POST "https://facturx.orvel.dev/v1/invoices/validate?check=fr-ctc" \
  -H "Authorization: Bearer $FACTURX_API_KEY" \
  -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": "fatal", "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 --fail --silent --show-error --max-time 60 -X POST "https://facturx.orvel.dev/v1/invoices/extract?include_xml=false" \
  -H "Authorization: Bearer $FACTURX_API_KEY" \
  -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