Retour au blog
Développeurs 8 min de lecture

Générer des Factur-X conformes via l'API

Factur-X n'est pas un simple PDF. C'est un conteneur PDF/A-3b qui embarque un fichier XML structuré (factur-x.xml) au format CII (Cross-Industry Invoice). Ce format hybride est au coeur de la réforme française : lisible par l'humain (PDF) et traitable par les machines (XML). Avec l'API Facturino, vous envoyez un JSON et vous récupérez un Factur-X conforme.

Anatomie d'un fichier Factur-X

Un Factur-X conforme se compose de plusieurs couches techniques :

  • PDF/A-3b : le conteneur, une version archivable et pérenne du PDF (norme ISO 19005-3)
  • factur-x.xml : le fichier XML CII embarqué en pièce jointe, contenant toutes les données structurées de la facture
  • AFRelationship : la relation entre le PDF et le XML, définie comme Alternative (le XML est une représentation alternative du même document)
  • XMP metadata : les métadonnées intégrées au PDF, incluant le niveau de conformance (B) et le nom du fichier XML (factur-x.xml)

Tout cela est généré automatiquement par Facturino. Vous n'avez pas à vous soucier des spécifications PDF/A, des métadonnées XMP ou du namespace CII.

Le profil EN16931

Factur-X définit plusieurs profils de complexité croissante : Minimum, Basic WL, Basic, EN16931 et Extended. Facturino utilise le profil EN16931, qui est le profil de référence pour la réforme française.

Ce profil contient environ 120 champs et couvre l'intégralité des exigences de la norme européenne EN16931 complétée par les extensions françaises CIUS-FR (Core Invoice Usage Specification - France).

Exigences CIUS-FR

Les règles CIUS-FR ajoutent des contraintes spécifiquement françaises au profil EN16931 :

  • BT-46 : le SIRET de l'acheteur est obligatoire (14 chiffres, validé via algorithme de Luhn)
  • BT-3 : le code de type de facture (InvoiceTypeCode) doit être l'un des codes autorisés : 380 (facture), 381 (avoir), 384 (facture corrective), 386 (acompte) ou 389 (auto-facture)
  • BG-7 : l'adresse de livraison est systématiquement requise (même si identique à l'adresse de l'acheteur)
  • BT-20 : la mention de TVA sur les débits doit être présente lorsque applicable

Workflow API : du JSON au Factur-X

1. Créer la facture (brouillon)

Envoyez un JSON avec les lignes de facturation, le client et les dates. Les montants sont en centimes d'euro et les taux de TVA en centièmes de pourcent. 

const invoice = await fetch('https://facturino.com/api/v1/invoices', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fac_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customerId: 'cus_a1b2c3d4e5f6',
    buyer: {
      companyName: 'Acme SAS',
      siret: '73282932000074',
      address: {
        line1: '15 rue de la Paix',
        city: 'Paris',
        postalCode: '75002',
        country: 'FR'
      }
    },
    dates: { issued: '2026-04-28', due: '2026-05-28' },
    payment: {
      terms: 'Paiement à 30 jours',
      termsDays: 30,
      method: 'transfer',
      latePaymentRate: '10.00',
      collectionFee: '40.00'
    },
    lines: [
      {
        description: 'Licence logicielle annuelle',
        quantity: '1',
        unit: 'unit',
        unitPrice: 120000,      // 1 200,00 EUR
        vatRate: 2000,          // 20,00 %
        vatCode: 'S'
      },
      {
        description: 'Support technique premium',
        quantity: '12',
        unit: 'month',
        unitPrice: 8500,        // 85,00 EUR/mois
        vatRate: 2000,
        vatCode: 'S'
      },
      {
        description: 'Formation initiale (2 jours)',
        quantity: '2',
        unit: 'day',
        unitPrice: 95000,       // 950,00 EUR/jour
        vatRate: 2000,
        vatCode: 'S'
      }
    ]
  })
}).then(r => r.json());

// invoice.status → "draft"
// invoice.totals.totalHT → 412000 (4 120,00 EUR)
// invoice.totals.totalVAT → 82400 (824,00 EUR)
// invoice.totals.totalTTC → 494400 (4 944,00 EUR)

2. Finaliser la facture

La finalisation déclenche une chaîne d'opérations atomiques :

  1. Validation complète : tous les champs obligatoires (EN16931 + CIUS-FR) sont vérifiés
  2. Attribution du numéro : numéro séquentiel attribué dans une transaction atomique (pas de trou de numérotation)
  3. Génération du PDF : mise en page professionnelle avec mentions légales automatiques
  4. Génération du XML CII : données structurées conformes au namespace urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100
  5. Assemblage Factur-X : le XML est embarqué dans le PDF/A-3b avec les métadonnées XMP
  6. Validation Schematron : les règles FACTUR-X_EN16931_CIUS-FR v1.0 sont vérifiées automatiquement
  7. Hash d'archivage : SHA-256 du PDF+XML pour la chaîne d'archivage
const finalized = await fetch(
  `https://facturino.com/api/v1/invoices/${invoice.id}/finalize`,
  { method: 'POST', headers }
).then(r => r.json());

// finalized.status → "finalized"
// finalized.number → "FAC-2026-0087"

3. Télécharger le Factur-X

// Télécharger le PDF/A-3b (contient le XML embarqué)
const pdfResponse = await fetch(
  `https://facturino.com/api/v1/invoices/${invoice.id}/pdf`,
  { headers }
);
const pdfBuffer = await pdfResponse.arrayBuffer();
// → PDF/A-3b avec factur-x.xml intégré

// Ou récupérer le XML seul (format CII)
const xmlResponse = await fetch(
  `https://facturino.com/api/v1/invoices/${invoice.id}/xml?format=cii`,
  { headers }
);
const xml = await xmlResponse.text();

// Ou en UBL 2.1
const ublResponse = await fetch(
  `https://facturino.com/api/v1/invoices/${invoice.id}/xml?format=ubl`,
  { headers }
);
const ubl = await ublResponse.text();

Validation automatique

Facturino valide chaque facture contre les règles Schematron avant la génération. Si une règle est enfreinte, l'API retourne une erreur détaillée avec le code BT/BG correspondant : 

// Exemple : SIRET acheteur manquant (BT-46)
{
  "error": {
    "type": "validation_error",
    "code": "cius_fr_violation",
    "message": "BT-46 : le SIRET de l'acheteur est requis (14 chiffres).",
    "param": "buyer.siret",
    "doc_url": "https://facturino.com/docs/api#cius-fr"
  }
}

Les validations couvrent notamment :

  • Présence et format du SIRET (14 chiffres, Luhn valide)
  • Cohérence des montants (HT + TVA = TTC, par ligne et au total)
  • Codes TVA et mentions d'exonération (VATEX-EU-AE, VATEX-FR-FRANCHISE, etc.)
  • Type de document valide (InvoiceTypeCode 380, 381, 384, 386 ou 389)
  • Présence de l'adresse de livraison (BG-7)

Formats disponibles

Trois formats sont proposés, sélectionnables par facture ou globalement dans vos paramètres :

Format Norme Type Usage principal
Factur-X EN16931 (CII D22B) PDF/A-3b + XML Format par défaut, lisible + structuré
CII UN/CEFACT D22B XML pur Interopérabilité machine-to-machine
UBL OASIS UBL 2.1 XML pur Réseau Peppol, échanges européens

Types de documents

L'API gère tous les types de documents fiscaux définis par la norme :

  • 380 — Facture standard : le cas le plus courant
  • 381 — Avoir (credit note) : pour annuler ou corriger une facture
  • 384 — Facture corrective : pour modifier une facture existante
  • 386 — Acompte : facture de dépôt ou prépaiement
  • 389 — Auto-facture : le client émet la facture au nom du fournisseur

Avoirs (credit notes)

Les avoirs suivent le même workflow que les factures, avec leur propre endpoint et des règles spécifiques : 

const creditNote = await fetch('https://facturino.com/api/v1/credit-notes', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    customerId: 'cus_a1b2c3d4e5f6',
    relatedInvoiceId: 'inv_x9y8z7w6v5u4',
    creditNoteType: 'partial',
    reasonCode: 'defective_goods',  // defective_goods | duplicate | quality | other
    dates: { issued: '2026-04-28' },
    items: [
      {
        description: 'Remboursement licence (défaut constaté)',
        quantity: '1',
        unit: 'unit',
        unitPrice: 120000,
        vatRate: 2000,
        vatCode: 'S'
      }
    ]
  })
}).then(r => r.json());

// Le Factur-X généré aura documentType="CREDITNOTE"
// et InvoiceTypeCode=381

Mentions légales automatiques

Facturino génère automatiquement les mentions légales en fonction du régime TVA de votre entreprise :

  • Franchise en base (CGI art. 293 B) : "TVA non applicable, article 293 B du CGI"
  • Autoliquidation (VATEX-EU-AE) : "Autoliquidation de la TVA — article 283-2 du CGI"
  • Export (VATEX-EU-G) : "Exonération de TVA — exportation hors UE"
  • Intracommunautaire (VATEX-EU-IC) : "Exonération de TVA — livraison intracommunautaire"
  • TVA sur les débits (BT-20) : "TVA acquittée sur les débits"

Les pénalités de retard, l'indemnité forfaitaire de recouvrement (40 EUR pour les factures B2B), les conditions de paiement et les coordonnées bancaires sont également insérées automatiquement selon votre configuration.

Archivage et intégrité

À chaque finalisation, Facturino calcule un hash SHA-256 du PDF et du XML. Ces hashs sont chaînés pour constituer une chaîne d'archivage inviolable. Vous pouvez vérifier l'intégrité d'une facture à tout moment : 

// Vérifier l'intégrité d'une facture
const verification = await fetch(
  `https://facturino.com/api/v1/invoices/${invoice.id}/verify`,
  { headers }
).then(r => r.json());

// verification.valid → true
// verification.hash → "a1b2c3d4..."
// verification.chain_valid → true

Envoyez un JSON, récupérez un Factur-X conforme. Facturino gère la complexité technique — vous gardez le contrôle métier.

Prêt à passer à la facturation électronique ?

Créez votre compte Facturino gratuitement et commencez à émettre des factures conformes en quelques minutes.

Essai gratuit Voir la documentation

Articles connexes

Qu'est-ce que la facturation électronique obligatoire ? 8 min de lecture Calendrier 2026-2027 : les dates clés 6 min de lecture Les 30 mentions obligatoires d'une facture 10 min de lecture
Tous les articles