Aller au contenu
Facturation Express

Référence — SDK e-facturation

@facturation/core

validate(invoice)

Valide une facture contre les règles EN 16931 et les règles françaises BR-FR-*.

function validate(invoice: unknown): ValidationResult


type ValidationResult = {
  valid: boolean;
  errors: ValidationError[];   // bloquants — lèvent une erreur en génération
  warnings: ValidationError[]; // non-bloquants — loggés uniquement
}


type ValidationError = {
  rule: string;       // ex: 'BR-FR-01'
  message: string;
  path?: string;      // chemin JSON vers le champ fautif
}

generateXml(invoice)

Génère le XML CII (Cross Industry Invoice) EN 16931 à partir d’une facture validée.

function generateXml(invoice: Invoice): string

Retourne une chaîne XML UTF-8 conforme au profil urn:cen.eu:en16931:2017#compliant#urn:factur-x.eu:1p0:en16931.

buildPdf(invoice, xml)

Embarque le XML dans un PDF/A-3 avec relation Alternative.

function buildPdf(invoice: Invoice, xml: string): Promise<Buffer>

Retourne un Buffer contenant le Factur-X PDF/A-3 prêt à l’envoi.

parseUbl(xmlString)

Parse un XML UBL 2.1 et retourne un objet Invoice compatible.

function parseUbl(xmlString: string): Invoice

@facturation/sdk

SandboxPaClient

Client pour la Plateforme Agréée en mode sandbox.

class SandboxPaClient {
  async deposit(invoice: Invoice, xml: string): Promise<DepositResponse>
  async getStatus(depositId: string): Promise<StatusResponse>
}


type DepositResponse = {
  depositId: string;
  paReference: string;
  status: InvoiceStatus;
}

IopolePaClient

Client pour la Plateforme Agréée Iopole en mode production.

class IopolePaClient {
  constructor(options: { apiKey: string; sandbox: boolean })
  async deposit(invoice: Invoice, xml: string): Promise<DepositResponse>
  async getStatus(paReference: string): Promise<StatusResponse>
}

transition(invoiceId, from, to)

Vérifie et enregistre une transition d’état dans la machine à états.

function transition(
  invoiceId: string,
  from: InvoiceStatus,
  to: InvoiceStatus
): TransitionResult


type TransitionResult =
  | { success: true; event: TransitionEvent }
  | { success: false; error: string }


type InvoiceStatus =
  | 'DRAFT' | 'SUBMITTED' | 'RECEIVED'
  | 'REJECTED' | 'REFUSED' | 'ACCEPTED'
  | 'PAID' | 'CANCELLED'

verifyWebhook(rawBody, signature, secret)

Vérifie la signature HMAC-SHA256 d’un webhook entrant de la PA.

function verifyWebhook(
  rawBody: string | Buffer,
  signature: string,  // header X-Webhook-Signature
  secret: string
): WebhookVerification


type WebhookVerification =
  | { valid: true; payload: WebhookPayload }
  | { valid: false; payload: null }

La comparaison utilise timingSafeEqual (temps constant) pour prévenir les attaques par timing.

EReportingClient (scaffold)

Client e-reporting — interface préparée pour la connexion DGFiP (obligation à partir de 2026).

class EReportingClient {
  buildBatch(invoices: Invoice[]): EReportingBatch
  validateBatch(batch: EReportingBatch): ValidationResult
  // submit() : non encore implémenté — en attente de la doctrine DGFiP
}

Types communs

Invoice

type Invoice = {
  number: string;
  typeCode: '380' | '381' | '386';  // 380=facture, 381=avoir, 386=devis
  issueDate: string;  // ISO 8601 YYYY-MM-DD
  currency: 'EUR';
  seller: Party;
  buyer: Party;
  lines: InvoiceLine[];
  paymentTerms?: string;
  note?: string;
}


type Party = {
  name: string;
  siret?: string;
  vatNumber?: string;
  address: Address;
}


type InvoiceLine = {
  id: string;
  description: string;
  quantity: number;
  unitCode: string;   // UN/ECE rec 20 (ex: 'HUR', 'C62', 'KGM')
  netPrice: number;
  lineNetAmount: number;
  vatCategoryCode: 'S' | 'Z' | 'E' | 'AE' | 'K' | 'G' | 'O';
  vatRate: number;
}