happypdf / embedFacturX

Function: embedFacturX()

function embedFacturX(
   pdfDoc, 
   invoiceXml, 
options?): Promise<void>;

Defined in: src/api/pdfa/facturx.ts:174

Embed a Factur-X / ZUGFeRD invoice XML into a PDF as a PDF/A-3 attachment with the required XMP metadata.

This helper:

1. Ensures PDF/A-3 (converts to 3B if needed; keeps an existing 3U/3B level).
2. Adds the Factur-X fx: properties and PDF/A extension schema to XMP.
3. Attaches the invoice XML with an associated-file relationship.

It does not generate or validate the Cross Industry Invoice XML — pass a complete factur-x.xml (or equivalent) produced by your invoicing stack. Drawn text must still use an embedded font for PDF/A compliance.

For example:

import { PDFDocument, embedFacturX } from '@cantoo/pdf-lib'

const pdfDoc = await PDFDocument.create()
const font = await pdfDoc.embedFont(fontBytes)
// ... draw the human-readable invoice with `font` ...

await embedFacturX(pdfDoc, invoiceXmlBytes, {
  conformanceLevel: 'EN 16931',
})

const pdfBytes = await pdfDoc.save()

Parameters

Parameter	Type	Description
pdfDoc	PDFDocument	The document that will carry the hybrid invoice.
invoiceXml	BinaryData	The Factur-X / ZUGFeRD XML bytes to embed.
options	EmbedFacturXOptions	Embedding and XMP options.

Returns

Promise<void>