THotPDF.AddFacturXAssociatedFile Method
Embeds a Factur-X or ZUGFeRD invoice XML payload in a PDF/A-3 document as an Associated File and adds the matching invoice XMP metadata
Declaration
function AddFacturXAssociatedFile(const XMLBytes: TBytes; const ConformanceLevel: AnsiString; const FileName: AnsiString= 'factur-x.xml'; const Description: AnsiString= 'Factur-X invoice XML'; const Relationship: AnsiString= 'Alternative'; const Version: AnsiString= '1.0'; const CountryCode: AnsiString= ''): THPDFDictionaryObject;Unit
HPDFDoc
Parameters
| Name | Purpose |
|---|---|
XMLBytes | Invoice XML bytes embedded verbatim in the PDF/A-3 EmbeddedFile stream; the XML guideline or profile identifier must match ConformanceLevel |
ConformanceLevel | Allowed invoice profile or conformance level, such as EN 16931, EXTENDED, XRECHNUNG, or COMFORT for ZUGFeRD 1.0 |
FileName | Embedded XML filename written to /F, /UF, the EmbeddedFiles name tree, and the XMP DocumentFileName value |
Description | Optional Filespec /Desc text shown to consuming tools |
Relationship | Associated-file relationship written as /AFRelationship and allowed by the selected invoice profile |
Version | Invoice metadata version, including 1.0, 2p0, or a matching XRECHNUNG version such as 3.0 |
CountryCode | Regional policy code used by profile validation; use an empty value, DE, or FR |
Return value
Returns the indirect Filespec dictionary registered for the primary invoice XML
Usage notes
- Set PDFACompliance to 3A, 3B, or 3U and call BeginDoc before using this method
- The method rejects invalid filename, profile, and metadata-version combinations so xrechnung.xml is only used with XRECHNUNG, ZUGFeRD-invoice.xml is only used with ZUGFeRD 1.0 profiles, zugferd-invoice.xml is only used with Version 2p0, and factur-x.xml is used for current Factur-X profiles
- The method checks the XML guideline or profile identifier against ConformanceLevel, including ZUGFeRD 1.0 profile URNs, current Factur-X profile URNs, French EXTENDED subsets, the EN16931 XMP or profile alias, ZUGFeRD 2.0 profile URNs, and known XRechnung CII or UBL profile URNs with matching metadata versions
- For XRECHNUNG, pass Version as 1.2, 2.0, 2.1, 2.2, 2.3, or 3.0 to preserve that fx:Version; existing calls that leave the default Version value at 1.0 are normalized to 3.0
- For ZUGFeRD 1.0 containers, pass FileName as ZUGFeRD-invoice.xml, Version as 1.0, and ConformanceLevel as BASIC, COMFORT, or EXTENDED
- For ZUGFeRD 2.0 containers, pass FileName as zugferd-invoice.xml and Version as 2p0
- Pass CountryCode as DE when the invoice container must follow German ZUGFeRD relationship rules; MINIMUM and BASIC WL require Data as AFRelationship, while BASIC, EN 16931, EXTENDED, and XRECHNUNG require Alternative
- Pass CountryCode as FR when the invoice must follow French Factur-X rules; XRECHNUNG is rejected and BASIC, EN 16931, EXTENDED, EXTENDED-CTC-FR, and EXTENDED-B2B-FR may use Alternative, Source, or Data
- The method uses MIME type text/xml, writes /Params /Size, /ModDate, and /CheckSum, registers the Filespec in Catalog /AF, and adds a Catalog /Names /EmbeddedFiles entry for XML extraction tools
- After the primary invoice XML is registered, later AddPDFA3AssociatedFile calls can add supporting documents; inspect FacturXWarnings for non-fatal MIME type warnings when those attachments are outside the recommended supporting-document formats
- The generated XMP packet includes the profile-specific PDF/A extension schema plus DocumentType, DocumentFileName, Version, and ConformanceLevel fields under the matching invoice namespace
- Do not set CustomXMP when using this helper, because a caller-supplied XMP packet would replace the generated invoice metadata
- Only one primary invoice XML can be attached through this helper in a document workflow