Guide d'intégration — SDK e-facturation

Pour qui ?

Les éditeurs de logiciels qui doivent raccorder leur produit à la facturation électronique française :

Réception obligatoire au 1/9/2026
Émission obligatoire au 1/9/2027

Démarrage rapide (lib open source)

npm install @facturation/core

import { generateXml, buildPdf, validate } from '@facturation/core';

const invoice = {
  number: 'FACT-2026-0001',
  typeCode: '380',
  issueDate: '2026-06-23',
  currency: 'EUR',
  seller: {
    name: 'ACME SAS',
    siret: '12345678900012',
    vatNumber: 'FR12345678901',
    address: { line1: '1 rue de la Paix', city: 'Paris', postalCode: '75001', countryCode: 'FR' },
  },
  buyer: {
    name: 'CLIENT SAS',
    siret: '98765432100018',
    address: { line1: '5 avenue Victor Hugo', city: 'Lyon', postalCode: '69001', countryCode: 'FR' },
  },
  lines: [
    {
      id: '1',
      description: 'Prestation de conseil',
      quantity: 10,
      unitCode: 'HUR',
      netPrice: 100,
      lineNetAmount: 1000,
      vatCategoryCode: 'S',
      vatRate: 20,
    },
  ],
};

// Validation EN 16931
const { valid, errors } = validate(invoice);
if (!valid) throw new Error(errors.map(e => e.message).join(', '));

// Génération
const xml = generateXml(invoice);
const pdfBuffer = await buildPdf(invoice, xml);
// pdfBuffer : Buffer contenant le Factur-X PDF/A-3 complet

SDK complet (payant)

Le SDK complet ajoute :

Machine à états : cycle de vie complet (DRAFT → SUBMITTED → RECEIVED → ACCEPTED → PAID)
Client PA sandbox/prod : dépôt Iopole, suivi des statuts
Webhooks signés : vérification HMAC-SHA256 des notifications PA
Bascule sandbox/prod explicite : log + avertissement contractuel

Accès sandbox 30 jours gratuits : créer un compte.

import { SandboxPaClient, transition, verifyWebhook } from '@facturation/sdk';

// Dépôt en sandbox
const pa = new SandboxPaClient();
const { depositId, status, paReference } = await pa.deposit(invoice, xml);
// status === 'SUBMITTED'

// Vérifier une transition d'état
const result = transition(invoiceId, 'SUBMITTED', 'RECEIVED');
if (result.success) {
  // result.event : { from, to, at, source }
}

// Vérifier un webhook entrant de la PA
const { valid, payload } = verifyWebhook(rawBody, signature, process.env.WEBHOOK_SECRET!);
if (valid) {
  // payload.event : 'INVOICE_STATUS_CHANGED'
  // payload.paReference, payload.newStatus
}

Règles de validation EN 16931

Le validateur implémente toutes les règles BR-* applicables en France :

Règle	Description
BR-CO-15	Somme des lignes cohérente avec le total HT (±0.02 €)
BR-CO-16	Total TTC cohérent avec HT + TVA (±0.05 €)
BR-CO-17	Montant dû cohérent avec le total TTC (±0.05 €)
BR-FR-01	Bloquant — franchise TVA 293 B : taux TVA doit être 0
BR-AE-02	Autoliquidation : taux 0 + raison requise

Machine à états des factures

DRAFT → SUBMITTED → RECEIVED → ACCEPTED → PAID
                 → REJECTED  → SUBMITTED (nouvelle tentative)
                 → REFUSED   (terminal)
       → CANCELLED (terminal)

Toutes les transitions invalides lèvent une InvalidTransitionError.

Passage en production

import { IopolePaClient } from '@facturation/sdk';

// UNIQUEMENT avec une clé production valide
const pa = new IopolePaClient({
  apiKey: process.env.PA_API_KEY!, // clé live
  sandbox: false,
});
// Un console.warn est émis si la clé n'est pas au format live

Tarifs

Plan	Volume	Prix
Starter	≤ 1 000 factures/mois	290 €/mois
Growth	≤ 10 000/mois	590 €/mois
Scale	Illimité + support prioritaire	990 €/mois
Intégration forfaitaire	One-shot	Sur devis