Reference — e-invoicing SDK

@facturation/core

validate(invoice)

Validates an invoice against EN 16931 rules and French BR-FR-* rules.

function validate(invoice: unknown): ValidationResult

type ValidationResult = {
  valid: boolean;
  errors: ValidationError[];    // blocking — prevent generation
  warnings: ValidationError[];  // non-blocking — logged only
}

generateXml(invoice)

Generates CII (Cross Industry Invoice) XML conforming to EN 16931.

function generateXml(invoice: Invoice): string

Returns a UTF-8 XML string conforming to profile urn:cen.eu:en16931:2017#compliant#urn:factur-x.eu:1p0:en16931.

buildPdf(invoice, xml)

Embeds the XML into a PDF/A-3 with Alternative relationship.

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

parseUbl(xmlString)

Parses a UBL 2.1 XML and returns a compatible Invoice object.

function parseUbl(xmlString: string): Invoice

---

@facturation/sdk

SandboxPaClient

Client for the Approved Platform in sandbox mode.

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

IopolePaClient

Client for Iopole Approved Platform in production mode.

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)

Verifies and records a state transition.

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

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

verifyWebhook(rawBody, signature, secret)

Verifies the HMAC-SHA256 signature of an incoming webhook. Uses timingSafeEqual (constant-time comparison) to prevent timing attacks.

function verifyWebhook(
  rawBody: string | Buffer,
  signature: string,
  secret: string
): { valid: true; payload: WebhookPayload } | { valid: false; payload: null }