Skip to Content
Takumi

Attachments

Embed files such as invoice XML in a PDF, and set the fields PDF/A-3 requires on each attachment.

Pass files through attachments to embed source data, supporting documents, or invoice XML. Viewers with an attachment panel list them there. This example embeds the line items as CSV:

Attachments
import {  } from "takumi-pdf";

const  = await (, {
  : [
    {
      : "line-items.csv",
      : ,
      : "text/csv",
      : "Invoice line items",
      : "source",
    },
  ],
});
FieldValue
nameFile name in the PDF 1
dataA Uint8Array, or a string written as UTF-8
mimeTypeIANA media type, such as "application/xml"
descriptionHuman-readable description
relationshipThe file's role, written as AFRelationship 2
modificationDateUTC YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS 3

1 Two attachments cannot share a name.

2 The next table lists the relationship values.

3 When unset, it falls back to metadata.creationDate.

relationship takes one of these values.

ValueMeaning
"source"The document was created from this file.
"alternative"An alternative representation of the document.
"data"The PDF presents the file's data, as an invoice presents its XML.
"supplement"Additional resources for the document.
"unspecified"No clear relationship. 1

1 "unspecified" is the default.

Electronic invoices

For a Factur-X or ZUGFeRD document, use PDF/A-3 and attach the invoice XML. Invoices shows a complete Factur-X MINIMUM example with its XMP metadata.

The PDF/A-3 levels require three fields on each attachment:

  • mimeType
  • description
  • a modification date from modificationDate, or the metadata.creationDate fallback

TypeScript enforces mimeType and description under these levels. A missing date fails the render.

Levels that allow attachments

pdfaAttachments
unsetAllowed
"3b", "3u", "3a"Allowed, with the three fields above
"4f"Allowed, with mimeType and description 1
"2b", "2u", "2a", "4"Not allowed, and a TypeScript type error

1 "4f" is the PDF 2.0 option.

Attaching the XML does not validate it or its profile. Add the profile's XMP metadata and validate the result as described in Invoices. See also PDF/A and PDF/UA for the levels.

Last updated on