Documentation
¶
Overview ¶
Package zerechnung reads, validates and creates Factur-X, ZUGFeRD and XRechnung hybrid invoices: a PDF that carries the invoice as CII XML.
The package does not draw invoices. It takes a PDF produced by your own rendering engine and adds what the standard requires (the XML attachment, its file specification, the XMP metadata), with an incremental update that leaves the original bytes untouched. It reads and checks any hybrid invoice, whatever its profile.
The main entry points are:
- Extract and Read get the XML, or the parsed invoice, out of a PDF, ZUGFeRD 1.0 PDFs included.
- Embed adds an XML invoice to a PDF; Create does the same from an invoice.Invoice.
- Check validates a hybrid PDF: container, XML schema, EN 16931 rules, profile rules and, on request, French and German rules.
Sub-packages give direct access to each layer: invoice (the EN 16931 model), cii (CII XML), validate (validation of XML invoices).
Example ¶
Example creates a Factur-X invoice from a PDF produced elsewhere, then reads it back and checks it with the French rules.
package main
import (
"fmt"
"log"
"os"
"time"
"github.com/ritoon/zerechnung"
"github.com/ritoon/zerechnung/invoice"
"github.com/ritoon/zerechnung/validate"
)
// newInvoice builds a French B2B invoice for services at the EN 16931
// profile, with the mentions required by the 2026 reform.
func newInvoice() *invoice.Invoice {
d := invoice.MustDecimal
seller := invoice.Party{
Name: "Exemple Informatique SAS",
IDs: []invoice.Identifier{{ID: "12345678900017", Scheme: invoice.SchemeSIRET}},
LegalRegistration: invoice.Identifier{ID: "123456789", Scheme: invoice.SchemeSIREN},
VATID: "FR32123456789",
Address: invoice.Address{Line1: "1 rue de l'Exemple", PostCode: "75001", City: "Paris", CountryCode: "FR"},
ElectronicAddress: invoice.Identifier{ID: "123456789_FACTURES", Scheme: invoice.SchemeFRDirectory},
}
buyer := invoice.Party{
Name: "Client Exemple SARL",
IDs: []invoice.Identifier{{ID: "98765432100015", Scheme: invoice.SchemeSIRET}},
LegalRegistration: invoice.Identifier{ID: "987654321", Scheme: invoice.SchemeSIREN},
VATID: "FR58987654321",
Address: invoice.Address{Line1: "2 place de l'Exemple", PostCode: "69002", City: "Lyon", CountryCode: "FR"},
ElectronicAddress: invoice.Identifier{ID: "987654321_ACHATS", Scheme: invoice.SchemeFRDirectory},
}
return &invoice.Invoice{
Profile: invoice.ProfileEN16931,
BusinessProcess: "S1",
Number: "FA-2026-00042",
TypeCode: invoice.TypeCommercialInvoice,
IssueDate: invoice.NewDate(2026, time.October, 15),
Currency: "EUR",
Notes: []invoice.Note{
{SubjectCode: "BAR", Content: "B2B"},
{SubjectCode: "PMT", Content: "Indemnité forfaitaire pour frais de recouvrement : 40 euros."},
{SubjectCode: "PMD", Content: "Pénalités de retard : trois fois le taux d'intérêt légal."},
{SubjectCode: "AAB", Content: "Pas d'escompte pour paiement anticipé."},
},
BuyerReference: "SERVICE-ACHATS",
Seller: seller,
Buyer: buyer,
DeliveryDate: invoice.NewDate(2026, time.October, 12),
PaymentMeans: []invoice.PaymentMeans{{TypeCode: invoice.PaymentSEPACreditTransfer, PayeeIBAN: "FR7630006000011234567890189"}},
PaymentTerms: []invoice.PaymentTerms{{Description: "Paiement à 30 jours par virement.", DueDate: invoice.NewDate(2026, time.November, 14)}},
Lines: []invoice.Line{{
ID: "1",
Item: invoice.Item{Name: "Maintenance applicative, octobre 2026"},
Quantity: d("2"),
UnitCode: "DAY",
NetPrice: d("450.00"),
VATCategoryCode: invoice.VATStandard,
VATRate: d("20.00"),
}},
}
}
func main() {
host, err := os.ReadFile("testdata/host.pdf") // any PDF, ideally PDF/A-3
if err != nil {
log.Fatal(err)
}
inv := newInvoice()
pdf, err := zerechnung.Create(host, inv, &zerechnung.CreateOptions{
Calculate: true, // line amounts, totals and VAT breakdown
Validate: &validate.Options{Rules: validate.Default | validate.France},
})
if err != nil {
log.Fatal(err)
}
back, att, err := zerechnung.Read(pdf)
if err != nil {
log.Fatal(err)
}
fmt.Println(att.Filename, att.Relationship, att.Metadata.ConformanceLevel)
fmt.Println(back.Number, back.Totals.TaxBasisTotal, back.Totals.TaxTotal, back.Totals.DuePayable, back.Currency)
report, _, err := zerechnung.Check(pdf, &validate.Options{Rules: validate.Default | validate.France})
if err != nil {
log.Fatal(err)
}
fmt.Println("errors:", len(report.Errors()))
}
Output: factur-x.xml Alternative EN 16931 FA-2026-00042 900.00 180.00 1080.00 EUR errors: 0
Example (VatOnDebits) ¶
Example_vatOnDebits declares the option for paying the VAT on debits ("option pour le paiement de la taxe d'après les débits"), a mandatory mention in France for a supplier of services who has opted for it. The DGFiP carries it in BT-8 with the code of the invoice date (rule G1.43 of its external specifications v3.2): 5 in CII, written in every VAT breakdown. BT-8 excludes the VAT point date BT-7 (BR-CO-03). Without the option, leave BT-8 empty: the VAT on services is then due on payment.
package main
import (
"bytes"
"fmt"
"log"
"time"
"github.com/ritoon/zerechnung/cii"
"github.com/ritoon/zerechnung/invoice"
"github.com/ritoon/zerechnung/validate"
)
// newInvoice builds a French B2B invoice for services at the EN 16931
// profile, with the mentions required by the 2026 reform.
func newInvoice() *invoice.Invoice {
d := invoice.MustDecimal
seller := invoice.Party{
Name: "Exemple Informatique SAS",
IDs: []invoice.Identifier{{ID: "12345678900017", Scheme: invoice.SchemeSIRET}},
LegalRegistration: invoice.Identifier{ID: "123456789", Scheme: invoice.SchemeSIREN},
VATID: "FR32123456789",
Address: invoice.Address{Line1: "1 rue de l'Exemple", PostCode: "75001", City: "Paris", CountryCode: "FR"},
ElectronicAddress: invoice.Identifier{ID: "123456789_FACTURES", Scheme: invoice.SchemeFRDirectory},
}
buyer := invoice.Party{
Name: "Client Exemple SARL",
IDs: []invoice.Identifier{{ID: "98765432100015", Scheme: invoice.SchemeSIRET}},
LegalRegistration: invoice.Identifier{ID: "987654321", Scheme: invoice.SchemeSIREN},
VATID: "FR58987654321",
Address: invoice.Address{Line1: "2 place de l'Exemple", PostCode: "69002", City: "Lyon", CountryCode: "FR"},
ElectronicAddress: invoice.Identifier{ID: "987654321_ACHATS", Scheme: invoice.SchemeFRDirectory},
}
return &invoice.Invoice{
Profile: invoice.ProfileEN16931,
BusinessProcess: "S1",
Number: "FA-2026-00042",
TypeCode: invoice.TypeCommercialInvoice,
IssueDate: invoice.NewDate(2026, time.October, 15),
Currency: "EUR",
Notes: []invoice.Note{
{SubjectCode: "BAR", Content: "B2B"},
{SubjectCode: "PMT", Content: "Indemnité forfaitaire pour frais de recouvrement : 40 euros."},
{SubjectCode: "PMD", Content: "Pénalités de retard : trois fois le taux d'intérêt légal."},
{SubjectCode: "AAB", Content: "Pas d'escompte pour paiement anticipé."},
},
BuyerReference: "SERVICE-ACHATS",
Seller: seller,
Buyer: buyer,
DeliveryDate: invoice.NewDate(2026, time.October, 12),
PaymentMeans: []invoice.PaymentMeans{{TypeCode: invoice.PaymentSEPACreditTransfer, PayeeIBAN: "FR7630006000011234567890189"}},
PaymentTerms: []invoice.PaymentTerms{{Description: "Paiement à 30 jours par virement.", DueDate: invoice.NewDate(2026, time.November, 14)}},
Lines: []invoice.Line{{
ID: "1",
Item: invoice.Item{Name: "Maintenance applicative, octobre 2026"},
Quantity: d("2"),
UnitCode: "DAY",
NetPrice: d("450.00"),
VATCategoryCode: invoice.VATStandard,
VATRate: d("20.00"),
}},
}
}
func main() {
inv := newInvoice() // services, billing frame S1
inv.TaxPointDateCode = invoice.TaxPointDebits
inv.Calculate()
xml, err := cii.Marshal(inv, nil)
if err != nil {
log.Fatal(err)
}
const elem = "<ram:DueDateTypeCode>5</ram:DueDateTypeCode>"
fmt.Println(elem, bytes.Count(xml, []byte(elem)) == 1)
report := validate.XML(xml, &validate.Options{Rules: validate.Default | validate.France})
fmt.Println("errors:", len(report.Errors()))
}
Output: <ram:DueDateTypeCode>5</ram:DueDateTypeCode> true errors: 0
Index ¶
- Constants
- Variables
- func Create(pdf []byte, inv *invoice.Invoice, opts *CreateOptions) ([]byte, error)
- func DetectProfile(xml []byte) (invoice.Profile, error)
- func Embed(pdfData, xml []byte, opts *EmbedOptions) ([]byte, error)
- type Attachment
- func Check(pdf []byte, opts *validate.Options) (*validate.Report, *Attachment, error)
- func CheckContainer(pdfData []byte) (*Attachment, []rules.Finding, error)
- func Extract(pdfData []byte) (*Attachment, error)
- func ExtractAll(pdfData []byte) ([]*Attachment, error)
- func Read(pdf []byte) (*invoice.Invoice, *Attachment, error)
- type CreateOptions
- type EmbedOptions
- type File
- type Metadata
- type ValidationError
Examples ¶
Constants ¶
const ( // NamespaceFacturX is used by Factur-X, ZUGFeRD 2.1 and later, and // XRechnung hybrids. NamespaceFacturX = xmp.NSFacturX // NamespaceZUGFeRD2 is used by ZUGFeRD 2.0. NamespaceZUGFeRD2 = xmp.NSZUGFeRD2 // NamespaceZUGFeRD1 is used by ZUGFeRD 1.0. NamespaceZUGFeRD1 = xmp.NSZUGFeRD1 // NamespaceZUGFeRD1RC is used by files made with the ZUGFeRD 1.0 // release candidate (2014). NamespaceZUGFeRD1RC = xmp.NSZUGFeRD1RC )
XMP namespaces of the hybrid-invoice schema.
Variables ¶
var ( // ErrNoInvoice is returned by Extract when the PDF has no invoice XML // attachment. ErrNoInvoice = errors.New("zerechnung: no invoice XML attachment in the PDF") // ErrEncrypted is returned for encrypted PDFs, which PDF/A forbids. ErrEncrypted = pdf.ErrEncrypted )
Errors of the PDF container layer.
var ContainerCatalog = []rules.RuleInfo{ {ID: "PDF-01", Severity: rules.Error, Description: "The PDF is not encrypted (PDF/A forbids encryption; the attachment cannot be read)."}, {ID: "PDF-02", Severity: rules.Error, Description: "The document catalog has an XMP metadata stream (/Metadata)."}, {ID: "PDF-03", Severity: rules.Error, Description: "The XMP metadata is a readable RDF/XML packet."}, {ID: "PDF-04", Severity: rules.Error, Description: "The XMP metadata declares PDF/A-3 or PDF/A-4 (pdfaid:part is 3 or 4), the parts that allow embedded XML files."}, {ID: "PDF-05", Severity: rules.Error, Description: "The XMP metadata declares a PDF/A conformance level that allows embedded XML files (pdfaid:conformance is A, B or U for PDF/A-3, F or E for PDF/A-4)."}, {ID: "PDF-06", Severity: rules.Warning, Description: "The catalog has a PDF/A output intent (/OutputIntents with /S /GTS_PDFA1). PDF/A requires it as soon as a device-dependent colour space is used, which is not analysed here."}, {ID: "PDF-07", Severity: rules.Error, Description: "The PDF/A output intent has an ICC profile (/DestOutputProfile stream)."}, {ID: "PDF-08", Severity: rules.Error, Description: "The trailer has a file identifier (/ID), as PDF/A requires."}, {ID: "PDF-09", Severity: rules.Error, Description: "The PDF has an invoice XML attachment that can be decoded."}, {ID: "PDF-10", Severity: rules.Error, Description: "The invoice attachment has an invoice file name: factur-x.xml, xrechnung.xml, or the legacy ZUGFeRD names zugferd-invoice.xml and ZUGFeRD-invoice.xml."}, {ID: "PDF-11", Severity: rules.Warning, Description: "The invoice attachment has the name of its profile in current specifications: factur-x.xml, or xrechnung.xml for XRECHNUNG. Legacy ZUGFeRD names are reported here."}, {ID: "PDF-12", Severity: rules.Error, Description: "The file specification of the invoice has an /AFRelationship entry (PDF/A-3 associated file)."}, {ID: "PDF-13", Severity: rules.Error, Description: "The /AFRelationship of the invoice is Data, Alternative or Source."}, {ID: "PDF-14", Severity: rules.Warning, Description: "The /AFRelationship matches the profile: Data for MINIMUM and BASIC WL, Alternative or Source for BASIC and above. Data is not reported for BASIC and above when the French rules apply: France admits it (Factur-X 1.09, 6.2.2)."}, {ID: "PDF-15", Severity: rules.Error, Description: "The file specification of the invoice is listed in the /AF array of the document catalog."}, {ID: "PDF-16", Severity: rules.Error, Description: "The embedded file stream has an XML MIME type (/Subtype /text#2Fxml)."}, {ID: "PDF-17", Severity: rules.Warning, Description: "The MIME type of the embedded file is text/xml rather than application/xml."}, {ID: "PDF-18", Severity: rules.Error, Description: "The embedded file stream has a modification date (/Params /ModDate), as PDF/A-3 requires."}, {ID: "PDF-19", Severity: rules.Warning, Description: "The modification date of the embedded file is a valid PDF date (D:YYYYMMDDHHmmSSOHH'mm')."}, {ID: "PDF-20", Severity: rules.Error, Description: "The file specification of the invoice has both a /F and a /UF file name, as PDF/A-3 requires."}, {ID: "PDF-21", Severity: rules.Error, Description: "The XMP metadata has the hybrid-invoice schema (Factur-X, ZUGFeRD 2.0 or ZUGFeRD 1.0 namespace)."}, {ID: "PDF-22", Severity: rules.Error, Description: "The XMP DocumentType is INVOICE."}, {ID: "PDF-23", Severity: rules.Error, Description: "The XMP DocumentFileName is the name of the invoice attachment."}, {ID: "PDF-24", Severity: rules.Error, Description: "The XMP ConformanceLevel is a known level and matches the profile of the XML (BT-24). EN 16931 is accepted for an XRECHNUNG invoice, EXTENDED for EXTENDED-CTC-FR."}, {ID: "PDF-25", Severity: rules.Error, Description: "The XMP metadata describes the hybrid-invoice schema and its properties in a PDF/A extension schema (pdfaExtension:schemas)."}, {ID: "PDF-26", Severity: rules.Warning, Description: "The XMP Version of the hybrid-invoice schema is set (\"1.0\" for Factur-X)."}, {ID: "PDF-27", Severity: rules.Warning, Description: "The XMP namespace matches the XML syntax: Factur-X or ZUGFeRD 2.0 for CrossIndustryInvoice, ZUGFeRD 1.0 for CrossIndustryDocument."}, {ID: "PDF-28", Severity: rules.Error, Description: "The PDF has a single invoice attachment: no other embedded file is named factur-x.xml, xrechnung.xml or zugferd-invoice.xml."}, {ID: "PDF-29", Severity: rules.Warning, Description: "A PDF/A-4 declaration gives the edition of ISO 19005-4 it follows (pdfaid:rev, a four-digit year: 2020)."}, {ID: "PDF-30", Severity: rules.Warning, Description: "The PDF version matches the declared PDF/A part: PDF 1.7 or earlier for PDF/A-3, PDF 2.0 for PDF/A-4."}, {ID: "PDF-31", Severity: rules.Warning, Description: "The fonts of the pages (in the resources of the pages, form XObjects, patterns, Type 3 fonts and annotation appearances) embed their font program (/FontFile, /FontFile2 or /FontFile3 in the font descriptor). PDF/A requires it for the fonts used for rendering; whether the content draws visible text with them is not analysed."}, {ID: "PDF-32", Severity: rules.Error, Description: "The document has no document-level JavaScript (/JavaScript in the catalog /Names), which PDF/A forbids."}, {ID: "PDF-33", Severity: rules.Error, Description: "No action forbidden by PDF/A (Launch, Sound, Movie, ResetForm, ImportData, Hide, SetOCGState, Rendition, Trans, GoTo3DView, JavaScript, SetState, NOP, or a named action other than NextPage, PrevPage, FirstPage and LastPage) in the /OpenAction, the outlines, the annotations or a chain of /Next actions."}, {ID: "PDF-34", Severity: rules.Error, Description: "No additional-actions dictionary (/AA) in the document catalog, the pages, the annotations or the form fields, as PDF/A requires."}, {ID: "PDF-35", Severity: rules.Error, Description: "The entries of the document information dictionary (/Info) that have an XMP equivalent (Title, Author, Subject, Keywords, Creator, Producer, CreationDate, ModDate) have the same value in the XMP metadata, as ISO 19005-3 requires. Not checked for PDF/A-4."}, {ID: "PDF-36", Severity: rules.Error, Description: "Every embedded file besides the invoice has an /AFRelationship entry (PDF/A-3 associated file)."}, {ID: "PDF-37", Severity: rules.Error, Description: "Every embedded file besides the invoice has a MIME type (/Subtype of the embedded file stream), as PDF/A-3 requires."}, {ID: "PDF-38", Severity: rules.Error, Description: "No stream of the pages, their resources, the annotation appearances, the font programs, the embedded files or the metadata uses the LZWDecode filter, which PDF/A forbids. Inline images of the page content are not checked."}, {ID: "PDF-39", Severity: rules.Error, Description: "Every embedded file besides the invoice is an associated file, listed in an /AF array (of the document catalog, a page, an annotation, a form or image XObject, a marked-content property list of the resources or a structure element), as PDF/A-3 requires. Files associated otherwise (property lists inside the page content, document parts) are not found."}, {ID: "PDF-40", Severity: rules.Error, Description: "Where the German rules apply, the /AFRelationship of a BASIC, EN 16931, EXTENDED or XRECHNUNG invoice is Alternative: Germany admits no other value (Factur-X 1.09, 5.3 and 6.2.2). They apply to XRECHNUNG invoices; Check also applies them when validate.Options selects the German rule sets (Germany, GermanyProfile, or Auto for a seller in Germany)."}, }
ContainerCatalog lists the checks of CheckContainer. They cover what the Factur-X specification (and ZUGFeRD, XRechnung hybrids) requires from the PDF container — the invoice attachment, its file specification and the XMP metadata — and the PDF/A-3 requirements a reader can verify without parsing the page content: encryption, output intent, file identifier, embedded fonts, JavaScript and actions, /Info and XMP consistency, other embedded files and forbidden filters. They do not replace a PDF/A validator: colour spaces, transparency, the font programs themselves and the page content are not checked.
Functions ¶
func DetectProfile ¶
DetectProfile returns the profile declared by the BT-24 of a CII invoice, or for a ZUGFeRD 1.0 invoice, the profile matched to its specification identifier (see invoice.ProfileFromZUGFeRD1URN).
func Embed ¶
func Embed(pdfData, xml []byte, opts *EmbedOptions) ([]byte, error)
Embed attaches an invoice XML to a PDF as Factur-X requires and returns the new PDF. The input is not modified.
The result is an incremental update: the original bytes are kept as they are (existing signatures stay valid) and followed by the embedded file, its file specification (listed in the catalog /AF array and in the EmbeddedFiles name tree), a new version of the catalog and an XMP metadata stream merged from the existing one: the PDF/A identification, the hybrid-invoice (fx) properties and their PDF/A extension schema. The document is declared PDF/A-4f when it is a PDF 2.0 file or already declares PDF/A-4 (level E is kept), and PDF/A-3 otherwise, keeping the existing conformance level when it is A, B or U (B by default). An attachment of the same name and any other invoice attachment (factur-x.xml, xrechnung.xml, zugferd-invoice.xml) are replaced: the result carries a single invoice. Other attachments are kept.
The supplementary files of EmbedOptions.Attachments are written like the invoice: embedded file stream with its MIME type and /Params /ModDate, file specification with /F, /UF and /AFRelationship (Supplement by default), listed in the EmbeddedFiles name tree and after the invoice in the catalog /AF array. An attachment of the host with the same name is replaced. Embed fails when a supplementary file has no name, an invoice name, the name of another one, an AFRelationship PDF/A-3 does not define or a malformed MIME type.
Embed fails when EmbedOptions.Relationship does not fit the profile or, for Data and Source, the seller's country (see EmbedOptions).
Embed does not convert the PDF to PDF/A: fonts, colour spaces and output intents are left as they are. CheckContainer reports what is missing. Nor does it validate the XML: only BT-24 is read, when Profile is unset, and the seller's country (BT-40), when Relationship is Data or Source for BASIC and above.
Types ¶
type Attachment ¶
type Attachment struct {
Filename string // /UF (or /F) of the file specification
XML []byte // decoded content of the embedded file
Relationship string // /AFRelationship ("Alternative", "Data", "Source"...), "" when absent
MimeType string // /Subtype of the embedded file, decoded ("text/xml")
Description string // /Desc of the file specification
ModDate time.Time // /Params /ModDate; zero when absent or unreadable
InAF bool // listed in the /AF array of the document catalog
Metadata *Metadata // XMP metadata of the document; nil when absent or unreadable
PDFVersion string // PDF version: the header's, or the catalog's /Version when later
}
Attachment is a file embedded in a PDF, normally the invoice XML.
func Check ¶
Check validates a hybrid PDF: the PDF container (PDF/A-3, attachment, XMP) and the embedded XML. The returned attachment is nil when no invoice was found. The error is reserved for PDFs that cannot be read at all.
The national rule sets that apply to the XML (France, Germany, GermanyProfile, selected explicitly or through Auto, and Germany for an XRECHNUNG invoice, see validate.RulesFor) also select the national usage of the container: with the German rules, the /AFRelationship of a BASIC invoice or above must be Alternative (PDF-40); with the French rules, Data is admitted besides Alternative and Source (no PDF-14).
The XML is validated with opts.Hybrid set: an EN 16931 invoice in a Factur-X PDF is checked against the Factur-X schematron of the EN 16931 profile, like BASIC and EXTENDED invoices (see validate.Options.Hybrid).
func CheckContainer ¶
func CheckContainer(pdfData []byte) (*Attachment, []rules.Finding, error)
CheckContainer checks the PDF container of a hybrid invoice: the PDF/A-3 or PDF/A-4 identification and XMP metadata, the invoice attachment and its file specification, the consistency of the XMP hybrid-invoice schema with the attachment and its profile (BT-24), and the PDF/A requirements that do not depend on rendering the pages (fonts, actions, document information, other attachments, filters). The rules are listed in ContainerCatalog; every finding has Source rules.SourcePDF.
The national usage of the /AFRelationship depends on the seller's country, which the container does not tell: CheckContainer applies the German one (PDF-40) to XRECHNUNG invoices only. Check applies the French and German usages whenever validate.Options selects their rule sets.
The returned attachment is the one Extract returns, or nil when the PDF is encrypted (finding PDF-01) or has no readable invoice attachment (finding PDF-09). The error is reserved for files that cannot be read as a PDF.
func Extract ¶
func Extract(pdfData []byte) (*Attachment, error)
Extract returns the invoice XML attachment of a Factur-X, ZUGFeRD or XRechnung hybrid PDF, with its file specification details and the XMP metadata of the document.
The attachment is looked up in the EmbeddedFiles name tree and the /AF array of the catalog (then of the pages), by name — factur-x.xml, xrechnung.xml, zugferd-invoice.xml or ZUGFeRD-invoice.xml, order-x.xml being ignored — and failing that as the first attachment whose XML root is a CrossIndustryInvoice or CrossIndustryDocument. The returned XML is the decoded embedded file, byte for byte.
Extract returns ErrNoInvoice when there is no such attachment and ErrEncrypted for encrypted PDFs.
func ExtractAll ¶
func ExtractAll(pdfData []byte) ([]*Attachment, error)
ExtractAll returns every embedded file of the PDF referenced by the EmbeddedFiles name tree or an /AF array, invoice or not, in document order. The XML field of each attachment holds its decoded content.
type CreateOptions ¶
type CreateOptions struct {
// Profile is the profile to write; zero means inv.Profile, or EN 16931
// when inv.Profile is not set.
Profile invoice.Profile
// Calculate runs inv.Calculate before writing the XML.
Calculate bool
// Validate, when not nil, validates the XML before embedding it and makes
// Create fail with a *ValidationError when the report has errors.
Validate *validate.Options
// Embed tunes the PDF part. Its Profile field is ignored.
Embed EmbedOptions
}
CreateOptions tune Create.
type EmbedOptions ¶
type EmbedOptions struct {
// Profile of the invoice. When unset, it is read from BT-24 of the XML;
// Embed fails when the identifier is unknown.
Profile invoice.Profile
// Filename of the attachment; Profile.Filename() when empty
// ("factur-x.xml", or "xrechnung.xml" for XRECHNUNG).
Filename string
// Relationship is the /AFRelationship: "Data", "Alternative" or
// "Source"; Profile.AFRelationship() when empty, which suits both France
// and Germany. Embed refuses a value that does not fit the profile or
// the seller's country (BT-40), as Factur-X 1.09 (6.2.2) tabulates them:
// MINIMUM and BASIC WL take Data; XRECHNUNG, and BASIC and above for a
// seller in Germany, take Alternative; BASIC and above take Alternative,
// Source or Data otherwise (France admits all three).
Relationship string
// Description of the attachment (/Desc).
Description string
// ModDate is the modification date of the attachment and of the
// document; time.Now() when zero. Set it for deterministic output.
ModDate time.Time
// Version is fx:Version; "1.0" when empty.
Version string
// DocumentType is fx:DocumentType; "INVOICE" when empty.
DocumentType string
// Attachments are supplementary files embedded besides the invoice: a
// purchase order, a timesheet, a delivery note...
Attachments []File
}
EmbedOptions tune Embed. The zero value (or nil) is ready to use.
type File ¶
type File struct {
// Name of the file (/F and /UF of the file specification); required.
// The invoice names (factur-x.xml, xrechnung.xml, zugferd-invoice.xml)
// and EmbedOptions.Filename are refused, whatever the case.
Name string
// MimeType is the MIME type of the file (/Subtype of the embedded file
// stream), such as "application/pdf". When empty, it is guessed from the
// extension of Name (pdf, xml, csv, txt, json, png, jpg, gif, tif, svg,
// zip, odt, ods, docx, xlsx, doc, xls), "application/octet-stream"
// otherwise.
MimeType string
// Description of the file (/Desc); none when empty.
Description string
// Data is the content of the file.
Data []byte
// Relationship is the /AFRelationship of the file: "Supplement" when
// empty, or "Data", "Source", "Alternative", "Unspecified".
Relationship string
// ModDate is the modification date of the file (/Params /ModDate);
// EmbedOptions.ModDate when zero.
ModDate time.Time
}
File is a supplementary file that Embed attaches to the PDF besides the invoice.
type Metadata ¶
type Metadata struct {
// NamespaceURI is the hybrid-invoice namespace found: NamespaceFacturX,
// NamespaceZUGFeRD2, NamespaceZUGFeRD1 (or NamespaceZUGFeRD1RC); "" when
// the XMP has no hybrid-invoice property.
NamespaceURI string
DocumentType string // "INVOICE"
DocumentFileName string // "factur-x.xml"
Version string // "1.0"
ConformanceLevel string // "EN 16931"
PDFAPart int // pdfaid:part; 0 when absent or not a number
PDFAConformance string // pdfaid:conformance ("B"; "F" or "E" for PDF/A-4)
PDFARev string // pdfaid:rev, the year of the PDF/A-4 edition ("2020"); "" when absent
}
Metadata is what the XMP metadata of the document says about the hybrid invoice.
type ValidationError ¶
ValidationError is returned by Create when the invoice is not valid.
func (*ValidationError) Error ¶
func (e *ValidationError) Error() string
Error gives the number of errors of the report and the first one.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cii reads and writes invoices in the UN/CEFACT Cross Industry Invoice (CII D16B) syntax used by Factur-X, ZUGFeRD 2.x and XRechnung.
|
Package cii reads and writes invoices in the UN/CEFACT Cross Industry Invoice (CII D16B) syntax used by Factur-X, ZUGFeRD 2.x and XRechnung. |
|
cmd
|
|
|
zerechnung
command
Command zerechnung reads, validates and creates Factur-X / ZUGFeRD / XRechnung invoices.
|
Command zerechnung reads, validates and creates Factur-X / ZUGFeRD / XRechnung invoices. |
|
internal
|
|
|
codes
Package codes holds the code lists of EN 16931 and lookup functions for them.
|
Package codes holds the code lists of EN 16931 and lookup functions for them. |
|
codes/gen
command
Command gen generates the code lists of package codes from the CII validation artefacts of CEN TC 434 (EN 16931).
|
Command gen generates the code lists of package codes from the CII validation artefacts of CEN TC 434 (EN 16931). |
|
pdf
Package pdf is a small, lazy PDF reader and an incremental-update writer, sized for what Factur-X needs: reaching the catalog, the embedded files, the XMP metadata and the output intents of a PDF, and appending new objects without touching the original bytes.
|
Package pdf is a small, lazy PDF reader and an incremental-update writer, sized for what Factur-X needs: reaching the catalog, the embedded files, the XMP metadata and the output intents of a PDF, and appending new objects without touching the original bytes. |
|
pdf/gen
command
Command gen writes ints_gen.go: the boxed values of the integers 0 to smallIntLimit-1, so that package pdf reads them without allocating.
|
Command gen writes ints_gen.go: the boxed values of the integers 0 to smallIntLimit-1, so that package pdf reads them without allocating. |
|
pdf/pdftest
Package pdftest builds small PDF files for tests: classic cross-reference tables, compressed cross-reference streams with object streams, hybrid files and damaged files.
|
Package pdftest builds small PDF files for tests: classic cross-reference tables, compressed cross-reference streams with object streams, hybrid files and damaged files. |
|
rules
Package rules holds the types shared by the validation rule sets: findings, reports, and the parsed CII document the rules run on (for a UBL invoice, a CII view of it, see NewUBLDoc).
|
Package rules holds the types shared by the validation rule sets: findings, reports, and the parsed CII document the rules run on (for a UBL invoice, a CII view of it, see NewUBLDoc). |
|
rules/choruspro
Package choruspro checks French B2G invoices, addressed to a public buyer through Chorus Pro, for the data Chorus Pro needs to accept and route them.
|
Package choruspro checks French B2G invoices, addressed to a public buyer through Chorus Pro, for the data Chorus Pro needs to accept and route them. |
|
rules/de
Package de implements the German rules of XRechnung 3.0, as published by KoSIT in the XRechnung schematrons: for the CII syntax, the patterns cii-pattern, cii-extension-pattern and cii-cvd-pattern of XRechnung-CII-validation.sch; for the UBL syntax, the patterns ubl-pattern, ubl-extension-pattern and ubl-cvd-pattern of XRechnung-UBL-validation.sch; both with the variables of common.sch.
|
Package de implements the German rules of XRechnung 3.0, as published by KoSIT in the XRechnung schematrons: for the CII syntax, the patterns cii-pattern, cii-extension-pattern and cii-cvd-pattern of XRechnung-CII-validation.sch; for the UBL syntax, the patterns ubl-pattern, ubl-extension-pattern and ubl-cvd-pattern of XRechnung-UBL-validation.sch; both with the variables of common.sch. |
|
rules/en16931
Package en16931 implements the validation rules of EN 16931-1 for the CII syntax, as published by CEN TC 434 in its validation artefacts (release Release): the business rules BR-* and BR-CO-*, the decimal rules BR-DEC-*, the VAT category rules (BR-S, BR-Z, BR-E, BR-AE, BR-IC, BR-G, BR-O, BR-IP for IGIC, BR-IG for IPSI, BR-B), the code list rules BR-CL-* and the CII syntax rules CII-SR-* and CII-DT-*.
|
Package en16931 implements the validation rules of EN 16931-1 for the CII syntax, as published by CEN TC 434 in its validation artefacts (release Release): the business rules BR-* and BR-CO-*, the decimal rules BR-DEC-*, the VAT category rules (BR-S, BR-Z, BR-E, BR-AE, BR-IC, BR-G, BR-O, BR-IP for IGIC, BR-IG for IPSI, BR-B), the code list rules BR-CL-* and the CII syntax rules CII-SR-* and CII-DT-*. |
|
rules/en16931/gen
command
Command gen generates the rule catalogs of package en16931:
|
Command gen generates the rule catalogs of package en16931: |
|
rules/facturx
Package facturx implements the Factur-X / ZUGFeRD profile rules: what each profile requires and allows beyond EN 16931.
|
Package facturx implements the Factur-X / ZUGFeRD profile rules: what each profile requires and allows beyond EN 16931. |
|
rules/facturx/gen
command
Command gen generates the code list assertions of package facturx from the Factur-X 1.09.2 schematrons of the BASIC, EN 16931 and EXTENDED profiles (FNFE-MPE / FeRD, ZUGFeRD 2.5.2): FACTUR-X_<profile>.sch and the code lists it reads, FACTUR-X_<profile>_codedb.xml.
|
Command gen generates the code list assertions of package facturx from the Factur-X 1.09.2 schematrons of the BASIC, EN 16931 and EXTENDED profiles (FNFE-MPE / FeRD, ZUGFeRD 2.5.2): FACTUR-X_<profile>.sch and the code lists it reads, FACTUR-X_<profile>_codedb.xml. |
|
rules/fr
Package fr implements the French rules BR-FR of the 2026 e-invoicing reform for the CII syntax, as published by the FNFE-MPE in the schematron "BR-FR-Flux2-Schematron-CII" version 1.4.0.04 (fatal on reception by 1 October 2026 at the latest, and on emission from that date).
|
Package fr implements the French rules BR-FR of the 2026 e-invoicing reform for the CII syntax, as published by the FNFE-MPE in the schematron "BR-FR-Flux2-Schematron-CII" version 1.4.0.04 (fatal on reception by 1 October 2026 at the latest, and on emission from that date). |
|
rules/peppol
Package peppol implements the rules of Peppol BIS Billing 3.0, as published by OpenPEPPOL in release 3.0.21 (unchanged in the hotfix 3.0.22): the 90 assertions of PEPPOL-EN16931-CII.sch for a CII invoice (Catalog), the 165 assertions of PEPPOL-EN16931-UBL.sch for a UBL invoice (UBLCatalog), in Go, with their exact identifiers, flags and messages.
|
Package peppol implements the rules of Peppol BIS Billing 3.0, as published by OpenPEPPOL in release 3.0.21 (unchanged in the hotfix 3.0.22): the 90 assertions of PEPPOL-EN16931-CII.sch for a CII invoice (Catalog), the 165 assertions of PEPPOL-EN16931-UBL.sch for a UBL invoice (UBLCatalog), in Go, with their exact identifiers, flags and messages. |
|
rules/ubl
Package ubl implements the validation of UBL 2.1 invoices and credit notes against the EN 16931 validation artefacts of CEN TC 434 for UBL (release Release).
|
Package ubl implements the validation of UBL 2.1 invoices and credit notes against the EN 16931 validation artefacts of CEN TC 434 for UBL (release Release). |
|
rules/ubl/gen
command
Command gen generates the rule catalog and the tables of package ubl from the UBL validation artefacts of CEN TC 434 (EN 16931).
|
Command gen generates the rule catalog and the tables of package ubl from the UBL validation artefacts of CEN TC 434 (EN 16931). |
|
schema
Package schema checks the structure of an invoice against its XML schema: a CII invoice against the schema of its profile, a UBL invoice against the OASIS UBL 2.1 schema of its document (Invoice or CreditNote).
|
Package schema checks the structure of an invoice against its XML schema: a CII invoice against the schema of its profile, a UBL invoice against the OASIS UBL 2.1 schema of its document (Invoice or CreditNote). |
|
schema/gen
command
Command gen compiles XML schemas into the compact Go tables used by package schema: the schemas of the Factur-X profiles (CII), the complete UN/CEFACT CII schemas used by the reference validators of XRechnung (D16B) and of the French EXTENDED-CTC-FR profile (D22B), and the OASIS UBL 2.1 schemas of the Invoice and CreditNote documents.
|
Command gen compiles XML schemas into the compact Go tables used by package schema: the schemas of the Factur-X profiles (CII), the complete UN/CEFACT CII schemas used by the reference validators of XRechnung (D16B) and of the French EXTENDED-CTC-FR profile (D22B), and the OASIS UBL 2.1 schemas of the Invoice and CreditNote documents. |
|
xmlenc
Package xmlenc holds the XML escaping shared by the CII and UBL writers.
|
Package xmlenc holds the XML escaping shared by the CII and UBL writers. |
|
xmltree
Package xmltree is a small read-only XML tree used to parse and validate CII invoices.
|
Package xmltree is a small read-only XML tree used to parse and validate CII invoices. |
|
xmltree/gen
command
Command gen writes names_gen.go: the characters above U+007F allowed in XML names by package xmltree.
|
Command gen writes names_gen.go: the characters above U+007F allowed in XML names by package xmltree. |
|
xmp
Package xmp reads and writes the XMP metadata of Factur-X / ZUGFeRD PDFs: the PDF/A identification (pdfaid), the hybrid-invoice schema (fx) and the PDF/A extension schema that describes it.
|
Package xmp reads and writes the XMP metadata of Factur-X / ZUGFeRD PDFs: the PDF/A identification (pdfaid), the hybrid-invoice schema (fx) and the PDF/A extension schema that describes it. |
|
Package invoice is a Go model of an electronic invoice following the semantic data model of EN 16931-1, with the extensions used by the Factur-X / ZUGFeRD EXTENDED and EXTENDED-CTC-FR profiles.
|
Package invoice is a Go model of an electronic invoice following the semantic data model of EN 16931-1, with the extensions used by the Factur-X / ZUGFeRD EXTENDED and EXTENDED-CTC-FR profiles. |
|
Package ubl reads and writes invoices and credit notes in the OASIS UBL 2.1 syntax, following the EN 16931 syntax binding of CEN/TS 16931-3-2.
|
Package ubl reads and writes invoices and credit notes in the OASIS UBL 2.1 syntax, following the EN 16931 syntax binding of CEN/TS 16931-3-2. |
|
Package validate checks CII and UBL invoices: CII invoices against the XML schema of their Factur-X profile, the EN 16931 business rules, the Factur-X profile rules, and optionally the French (BR-FR) and German (BR-DE) rules, the profiles that France and Germany admit, the checks of Chorus Pro for French B2G invoices, and the Peppol BIS Billing 3.0 rules.
|
Package validate checks CII and UBL invoices: CII invoices against the XML schema of their Factur-X profile, the EN 16931 business rules, the Factur-X profile rules, and optionally the French (BR-FR) and German (BR-DE) rules, the profiles that France and Germany admit, the checks of Chorus Pro for French B2G invoices, and the Peppol BIS Billing 3.0 rules. |