confactura — client JS / Node

Client officiel de l'API Confactura : générer et valider des factures Factur-X (PDF/A-3 + XML CII, profil EN 16931) en un appel HTTP, conformes à la réforme française de la facturation électronique 2026-2027.

Le service recalcule les totaux côté serveur et refuse de livrer une facture qui ne passe pas la validation XSD et Schematron (règles CTC FR incluses) : un 200 est une garantie de conformité, pas une supposition.

npm install confactura

Zéro dépendance : fetch / FormData / Blob natifs (Node ≥ 18, ou navigateur). ESM.

Clé API

curl -X POST https://confactura.fr/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

La clé n'est renvoyée qu'une seule fois (dans la réponse et par email). Le plan gratuit couvre 20 factures/mois ; la validation est illimitée et sans clé.

Usage

import { ConfacturaClient, ConfacturaValidationError } from "confactura";
import { readFileSync, writeFileSync } from "node:fs";

const df = new ConfacturaClient({ apiKey: "df_live_…" });

// Générer un Factur-X
try {
  const pdf = await df.generateFacturx({
    number: "2026-0042",
    issue_date: "2026-09-01",
    due_date: "2026-09-30",
    seller: { name: "Ma Société", address_line: "1 rue X", postcode: "75001", city: "Paris", siren: "123456789", vat_id: "FR32123456789", electronic_address: "[email protected]" },
    buyer:  { name: "Client SARL", address_line: "2 av. Y", postcode: "69001", city: "Lyon", electronic_address: "[email protected]" },
    lines:  [{ description: "Presta dev", quantity: 5, unit_price: "450.00" }],
  });
  writeFileSync("facture-2026-0042.pdf", pdf);
} catch (e) {
  if (e instanceof ConfacturaValidationError) console.error("Non conforme :", e.errors);
}

// Valider un Factur-X — anonyme, aucune clé requise, aucun quota consommé
const report = await df.validate(readFileSync("facture.pdf"));
console.log(report.valid, report.errors);

// Consommation du mois
console.log(await df.usage()); // { plan: "free", used: 3, quota: 20 }

validate fonctionne sans clé : new ConfacturaClient().validate(bytes). Autre environnement : new ConfacturaClient({ baseUrl: "http://localhost:8000" }).

Champs requis côté CTC FR

Sans eux la facture part en 422 avec le rapport détaillé — jamais en 500 :

• electronic_address sur le vendeur et l'acheteur (BR-FR-12 / BR-FR-13) ;
• vat_id côté vendeur dès qu'une ligne est en TVA standard (BR-S-02) ;
• un siren vendeur valide.

Les autres mentions de la réforme 2026 (frais de recouvrement, pénalités de retard, escompte, catégorie d'opération) sont ajoutées automatiquement côté serveur.

API

| Méthode | Endpoint | Retour | |---|---|---| | generateFacturx(invoice) | POST /v1/invoices/facturx | Uint8Array — PDF/A-3 | | generateXml(invoice) | POST /v1/invoices/xml | Uint8Array — XML CII EN 16931 | | validate(pdf) | POST /v1/validate | { valid, profile, flavor, errors } | | usage() | GET /v1/usage | { plan, used, quota } |

Un 422 en génération lève ConfacturaValidationError (.errors, .report) ; tout autre statut ≥ 400 lève ConfacturaError (.status, .detail).

Liens

• Guide pas à pas : https://confactura.fr/factur-x-node
• Validateur Factur-X en ligne, gratuit : https://confactura.fr/validateur
• Erreurs Schematron expliquées : https://confactura.fr/erreurs-schematron
• Référence OpenAPI : https://confactura.fr/docs

Tests

npm test   # node --test, serveur http local jetable, zéro réseau externe

MIT.