This section describes how a CII CrossIndustryInvoice XML document is composed in the cii package. It covers the Go struct hierarchy that models the document, the builder functions that populate each section during GOBL→CII conversion, and the parser functions that reconstruct GOBL data from each section during CII→GOBL conversion.
For the public API functions that initiate conversion (Convert, Parse, Unmarshal), see the Core Conversion API. For how specific e-invoicing profiles customise what is generated in each component, see E-Invoicing Standards.
A CII invoice is represented in Go by the Invoice struct (invoice.go15-24). It maps directly to the rsm:CrossIndustryInvoice XML element and contains three meaningful child sections, assembled inside a Transaction (invoice.go27-32).
CII Invoice Go Struct Hierarchy
Sources: invoice.go15-32
The table below maps each CII document section to its Go struct, the XML element it serialises to, and the sub-page that documents it in detail.
| CII Section | Go Struct | XML Element | Detail Page |
|---|---|---|---|
| Guideline context | ExchangedContext / ExchangedContextParameter | rsm:ExchangedDocumentContext | Invoice Structure |
| Document header | Header | rsm:ExchangedDocument | Invoice Structure |
| Trade parties | Party, PostalTradeAddress, LegalOrganization | ram:SellerTradeParty, ram:BuyerTradeParty | Party Processing |
| Header agreement | Agreement | ram:ApplicableHeaderTradeAgreement | Agreement Processing |
| Payment & totals | Settlement, PaymentMeans, Terms, Summation | ram:ApplicableHeaderTradeSettlement | Settlement Processing |
| Invoice lines | Line, Product, LineAgreement, TradeSettlement | ram:IncludedSupplyChainTradeLineItem | Line Items Processing |
| Tax breakdown | Tax | ram:ApplicableTradeTax | Tax Processing and Mapping |
| Allowances/charges | AllowanceCharge | ram:SpecifiedTradeAllowanceCharge | Allowances and Charges |
Sources: invoice.go15-54
The newInvoice function (invoice.go87-110) is the root builder. It constructs the Invoice struct and delegates each section to a dedicated builder. The addTransaction method (invoice.go113-128) coordinates the four sections that sit under rsm:SupplyChainTradeTransaction.
GOBL → CII Build Pipeline
Sources: invoice.go87-128
CII → GOBL Parse Pipeline
Sources: Diagram 2 (System Architecture)
Several small structs are used across multiple components.
| Struct | XML Mapping | Used In |
|---|---|---|
Tax | ram:ApplicableTradeTax | Settlement, TradeSettlement |
Date | udt:DateTimeString | Header, DeliveryEvent, Terms |
Note | ram:IncludedNote | Header |
The Tax struct (invoice.go35-42) carries the calculated amount, basis amount, category code, optional exemption reason code, and rate percentage. Date (invoice.go45-48) wraps a string value with a format attribute (typically 102 for YYYYMMDD). Note (invoice.go51-54) carries free-text content and an optional subject code.
Sources: invoice.go35-54
Two public functions allow external callers to work with the Invoice struct directly without going through the full GOBL pipeline:
ConvertInvoice(env, opts...) (invoice.go58-68) — calls Convert and type-asserts the result to *Invoice. Useful when the caller needs access to the raw Go struct rather than serialised XML bytes.UnmarshalInvoice(data []byte) (invoice.go72-85) — deserialises raw CII XML into an *Invoice struct using xmlctx.Unmarshal, without any GOBL conversion. Useful for inspection and debugging.For full conversion workflows, use cii.Convert (GOBL→CII) or cii.Parse (CII→GOBL) as described in Core Conversion API.
Sources: invoice.go58-85
Refresh this wiki