Skip to content
Lamina PDF

A PDF/A-3 invoice with XML

You’ll write a one-page invoice as PDF/A-3b, with the same invoice attached as XML. You need this for e-invoices such as Factur-X and ZUGFeRD, where a person reads the PDF and the buyer’s software reads the XML.

The function draws the invoice, writes the same items as XML and attaches that file before it finishes. In TypeScript it needs the text module, init({ text: true }). Both languages write the same bytes:

packages/sdk/examples/pdf-a3-invoice-with-xml.ts
// A PDF/A-3b invoice that carries the same invoice as XML, attached for software to read.
import { Builder, Font, PAGE_SIZES, type Surface } from "@laminapdf/sdk";


const MARGIN = 56;
/** The page's right edge, less the margin: where the rule under the items ends. */
const RIGHT = PAGE_SIZES.A4[0] - MARGIN;
const AMOUNTS = 460;
const ROW = 22;
const TITLE_BASELINE = 80;
const FIRST_ROW = 130;
/**
 * How far above the next row's baseline the rule sits, and how far below it the total and
 * the note are.
 */
const RULE_RISE = 7;
const TOTAL_DROP = 18;
const NOTE_DROP = 68;
/** How far left of the amounts column the total starts, to fit its "Total" label. */
const TOTAL_INDENT = 40;
const TITLE = 24;
const TOTAL = 14;
const BODY = 11;
const ITEMS = [
  ["Sprockets", 12, 1.25],
  ["Gadget", 1, 79.9],
  ["Delivery", 1, 4.5],
] as const;


/** The invoice's total. */
function total(): number {
  return ITEMS.reduce((sum, [, qty, price]) => sum + qty * price, 0);
}


/** The invoice as XML, in a made-up schema (a real e-invoice follows EN 16931, as Factur-X does). */
function invoiceXml(): string {
  const lines = ITEMS.map(
    ([item, qty, price]) => `  <line item="${item}" quantity="${qty}" price="${price.toFixed(2)}"/>\n`,
  );
  return `<?xml version="1.0" encoding="UTF-8"?>\n<invoice number="42" currency="EUR">\n${lines.join("")}  <total>${total().toFixed(2)}</total>\n</invoice>\n`;
}


/**
 * The invoice's bytes. Needs `init({ text: true })`.
 *
 * @param notoSans - the bytes of the Noto Sans font file.
 */
export function pdfA3InvoiceWithXml(notoSans: Uint8Array): Uint8Array<ArrayBuffer> {
  using b = new Builder({ profiles: ["PDF/A-3b"] });
  b.metadata({ title: "Invoice 42", author: "Acme Widgets Ltd" });
  const font = Font.fromBytes(notoSans);
  b.font(font);
  const page = b.page("A4");
  draw(page.surface(), font);
  page.finish();
  b.attach("invoice-42.xml", new TextEncoder().encode(invoiceXml()), "text/xml", {
    relationship: "alternative",
    description: "Invoice 42 as XML",
  });
  using doc = b.finish();
  return doc.save();
}


function draw(s: Surface, font: Font): void {
  s.text("Invoice 42", { font, size: TITLE, at: [MARGIN, TITLE_BASELINE] });
  let y = FIRST_ROW;
  for (const [item, qty, price] of ITEMS) {
    s.text(`${qty} × ${item}`, { font, size: BODY, at: [MARGIN, y] });
    s.text(`€ ${(qty * price).toFixed(2)}`, { font, size: BODY, at: [AMOUNTS, y] });
    y += ROW;
  }
  const rule = y - RULE_RISE;
  s.strokeColor([0.5])
    .path((p) => p.moveTo(MARGIN, rule).lineTo(RIGHT, rule))
    .stroke();
  s.text(`Total € ${total().toFixed(2)}`, { font, size: TOTAL, at: [AMOUNTS - TOTAL_INDENT, y + TOTAL_DROP] });
  s.text("The invoice is attached as invoice-42.xml.", {
    font,
    size: BODY,
    at: [MARGIN, y + NOTE_DROP],
    link: { target: { type: "uri", uri: "https://example.com/invoices/42" }, contents: "Invoice 42 online" },
  });
}

The result is one A4 page with three line items and a total of € 99.40, carrying invoice-42.xml: open the reference PDF. Viewers that show attachments list it there.

How it works

Section titled “How it works”
  • profiles: ["PDF/A-3b"] (Profile::PdfA3b in Rust) asks for PDF/A-2b’s rules and allows attached files of any kind. finish() fails with a coded error for the first rule the invoice breaks; see Archival PDFs.
  • PDF/A needs every font embedded, so the invoice uses Noto Sans rather than one of the standard 14 fonts.
  • invoiceXml writes the line items and the total from the same ITEMS the page draws, so the PDF and the XML always agree. Its schema is made up for the recipe.
  • attach adds the file with its name, its bytes and its MIME type, text/xml. PDF/A needs a MIME type on every attachment, or finish() fails with embedded-file-without-mime-type.
  • relationship: "alternative" (AfRelationship::Alternative) says the XML is another form of the same content, and the builder associates it with the document. description is the text a viewer shows beside the file.

What to change

Section titled “What to change”
  • The items: change ITEMS. The page, the total and the XML all follow.
  • A real e-invoice: replace invoiceXml with XML that follows EN 16931, the European e-invoicing standard, as Factur-X and ZUGFeRD do. Those formats also need XMP entries of their own, which the builder can’t add yet.
  • Other attachments: attach the file the invoice was made from with relationship: "source", or the data behind it with "data" (AfRelationship::Source, AfRelationship::Data). Each needs its own name and MIME type.
  • Accessible too: add "PDF/UA-1" to profiles, set lang and tag the content, as the PDF/UA report does.

Next: a 100-page report, the case Lamina PDF times in every runtime.