Technical Reference

Relevant source files

• go.mod
• go.sum
• invoice.go
• invoice_parse.go
• settlement.go

This section is the entry point for detailed technical reference material for the gobl.cii package. It provides a structural overview, quick-reference tables for key types and functions, and links to sub-pages covering dependencies, data models, code mappings, and compliance information.

Intended for developers who need to:

• Understand implementation details for debugging or extension
• Integrate gobl.cii into other systems or toolchains
• Contribute new conversions or context definitions
• Audit standards compliance or known limitations

For architecture context, see page 1.1. For conversion API usage, see page 3. For e-invoicing standard details, see page 5.

---

Package Structure Overview

The gobl.cii package is organized into distinct layers with clear responsibilities.

Package layer and file map

Sources: cii.go1-230 invoice.go1-141 invoice_parse.go1-50

File Organization

File	Purpose	Key Types / Functions
cii.go	Public API and context definitions	Parse(), Convert(), ConvertInvoice(), Context constants, Option
invoice.go	CII root document structure and assembly	Invoice, Transaction, Tax, Date, Note, newInvoice(), ConvertInvoice(), UnmarshalInvoice()
header.go	Document header section	Header, addHeader()
agreement.go	Agreement section (parties, references)	Agreement, addAgreement()
settlement.go	Settlement section (payment, tax totals)	Settlement, newSettlement()
lines.go	Line item conversion	Line, addLines()
party.go	Party conversion (GOBL → CII)	Party, newParty()
delivery.go	Delivery section	Delivery, newDelivery()
cdar.go	CDAR acknowledgement document	CDAR, CDARAcknowledgement, UnmarshalCDAR()
invoice_parse.go	CII → GOBL invoice parsing	parseInvoice(), goblInvoice(), goblAddLines()
settlement_parse.go	Settlement parsing	goblNewPaymentDetails()
party_parse.go	Party parsing	goblNewParty(), goblNewAddress()

Sources: cii.go1-230 invoice.go1-141 cdar.go1-100

---

Quick Reference

Core Data Types

Primary document structure

Type	Location	Purpose
Invoice	invoice.go15-24	Root rsm:CrossIndustryInvoice struct with namespace attributes
Transaction	invoice.go27-32	Container: lines, agreement, delivery, settlement
Header	header.go	Document metadata: ID, type code, issue date, notes
Party	party.go	Seller/buyer/payee entity
Line	lines.go	Individual ram:IncludedSupplyChainTradeLineItem
Agreement	agreement.go	ram:ApplicableHeaderTradeAgreement (parties, references)
Settlement	settlement.go	ram:ApplicableHeaderTradeSettlement (payment, tax totals)
Delivery	delivery.go	ram:ApplicableHeaderTradeDelivery (location, dates)
CDAR	cdar.go	Cross Domain Acknowledgement and Response document

Supporting types

Type	Location	Purpose
Tax	invoice.go35-42	ram:ApplicableTradeTax (rate, category, calculated amount)
Date	invoice.go45-48	udt date value with format attribute
Note	invoice.go51-54	ram:IncludedNote with optional subject code
Context	cii.go50-58	Target e-invoicing standard configuration

Sources: invoice.go15-54 cii.go50-58

Context Definitions

See page 3.3 for full context field documentation.

Available contexts

Constant	Version	Required GOBL Addon	Use Case
ContextEN16931V2017	D16B	eu-en16931-v2017	Base European standard
ContextPeppolV3	D16B	eu-en16931-v2017	Peppol BIS Billing 3.0
ContextXRechnungV3	D16B	de-xrechnung-v3	Germany public sector
ContextFacturXV1	D16B	fr-facturx-v1	France Factur-X extended
ContextZUGFeRDV2	D16B	de-zugferd-v2	Germany ZUGFeRD 2.x
ContextChorusProV1	D16B	fr-choruspro-v1	France public procurement
ContextPeppolFranceFacturXV1	D22B	fr-facturx-v1	Peppol France Factur-X
ContextPeppolFranceCIUSV1	D22B	fr-en16931-v2017	Peppol France CIUS

Sources: cii.go61-126

Public API Functions

Conversion functions

Function	Signature	Purpose
Parse	func Parse(data []byte) (*gobl.Envelope, error)	CII XML → GOBL envelope
Unmarshal	func Unmarshal(data []byte, env *gobl.Envelope) error	CII XML → GOBL envelope (in-place)
Convert	func Convert(env *gobl.Envelope, opts ...Option) (any, error)	GOBL envelope → CII document
ConvertInvoice	func ConvertInvoice(env *gobl.Envelope, opts ...Option) (*Invoice, error)	Type-safe wrapper around Convert
UnmarshalInvoice	func UnmarshalInvoice(data []byte) (*Invoice, error)	CII XML → Invoice struct (no GOBL conversion)
UnmarshalCDAR	func UnmarshalCDAR(data []byte) (*CDAR, error)	CDAR XML → CDAR struct

Configuration functions

Function	Signature	Purpose
WithContext	func WithContext(context Context) Option	Set target e-invoicing standard for Convert

Sources: cii.go131-212 invoice.go57-85 cdar.go1-50

Constants

XML namespaces

Constant	Value
NamespaceRSM	urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100
NamespaceRAM	urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100
NamespaceQDT	urn:un:unece:uncefact:data:standard:QualifiedDataType:100
NamespaceUDT	urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100

CII versions

Constant	Value	Usage
VersionD16B	"D16B"	UN/CEFACT D.16B — default for all standard contexts
VersionD22B	"D22B"	UN/CEFACT D.22B — Peppol France CIUS and Extended variants

Error sentinels

Constant	When returned
ErrUnknownDocumentType	XML root namespace not recognized during Parse
ErrUnsupportedDocumentType	GOBL document type has no CII conversion in Convert

Sources: cii.go23-48

Key Internal Functions

Document generation (GOBL → CII)

Function	Source	Purpose
newInvoice	invoice.go87-110	Assembles root Invoice with namespace attrs and context
addHeader	header.go	Populates rsm:ExchangedDocument (ID, type code, dates)
addTransaction	invoice.go113-128	Orchestrates lines, agreement, settlement, delivery
addLines	lines.go	Converts bill.Invoice.Lines to ram:IncludedSupplyChainTradeLineItem
addAgreement	agreement.go	Builds ram:ApplicableHeaderTradeAgreement with parties and references
newSettlement	settlement.go	Builds ram:ApplicableHeaderTradeSettlement
newParty	party.go	Converts org.Party → CII Party
newDelivery	delivery.go	Builds ram:ApplicableHeaderTradeDelivery
extractGuidelineID	invoice.go130-140	Resolves guideline ID (with Chorus Pro extension override)

Parsing pipeline (CII → GOBL)

Function	Source	Purpose
parseInvoice	invoice_parse.go	Entry point: XML → *bill.Invoice
goblInvoice	invoice_parse.go	Orchestrates all field extraction
goblNewParty	party_parse.go	Party → org.Party
goblNewAddress	party_parse.go	PostalTradeAddress → org.Address
goblAddLines	invoice_parse.go	Line items extraction
goblNewPaymentDetails	settlement_parse.go	Payment instructions extraction
extractRootNamespace	cii.go	Reads XML root namespace to route to correct parser

Sources: invoice.go87-140 invoice_parse.go1-50 cii.go214-230

---

Conversion Flow Diagrams

Parse: CII XML → GOBL

Sources: cii.go131-153 invoice_parse.go17-154

Convert: GOBL → CII XML

Sources: cii.go157-183 invoice.go89-133 settlement.go115-174

Settlement Processing Detail

The newSettlement function orchestrates the most complex part of invoice conversion.

Sources: settlement.go115-174 settlement.go273-302 settlement.go304-349

---

Context System Details

The Context struct controls which CII profile is generated and what GOBL addons are required. See page 3.3 for full documentation.

Context struct fields → CII XML mapping

Sources: cii.go50-58 invoice.go87-100 cii.go168-171

---

Sub-pages

7.1 Module Dependencies

Direct Dependencies go.mod5-14

Core Runtime Dependencies

Module	Version	Purpose
github.com/invopop/gobl	v0.308.0	GOBL invoice data structures (bill.Invoice, org.Party, tax.Total)
github.com/invopop/xmlctx	v0.13.0	XML marshaling/unmarshaling with namespace support
github.com/invopop/validation	v0.8.0	Validation framework for business rules
github.com/invopop/phive	v0.6.0	gRPC client for external Phive validation service

CLI Dependencies

Module	Version	Purpose
github.com/spf13/cobra	v1.9.1	Command-line interface framework
github.com/joho/godotenv	v1.5.1	Environment variable loading

Testing Dependencies

Module	Version	Purpose
github.com/stretchr/testify	v1.10.0	Test assertions and mocking
gitlab.com/flimzy/testy	v0.14.0	Fixture-based testing utilities

Transport Dependencies

Module	Version	Purpose
google.golang.org/grpc	v1.77.0	gRPC transport for Phive validation
google.golang.org/protobuf	v1.36.10	Protocol buffer serialization

Indirect Dependencies (Selected) go.mod17-42

• github.com/Masterminds/semver/v3 — Semantic version parsing
• github.com/google/uuid — UUID generation for document identifiers
• github.com/invopop/jsonschema — JSON schema generation
• golang.org/x/net, golang.org/x/text — Network and text utilities

Sources: go.mod1-45 go.sum1-117

7.2 Data Models Reference

Settlement Structures

The Settlement struct is the most complex component (importance: 30.45), handling all financial aspects.

Field	XML Tag	Type	Purpose
CreditorRefID	ram:CreditorReferenceID	string	Direct debit creditor reference
PaymentReference	ram:PaymentReference	string	Payment reference code (BT-83)
Currency	ram:InvoiceCurrencyCode	string	Invoice currency (BT-5)
Payee	ram:PayeeTradeParty	*Party	Alternative payee if different from supplier
PaymentMeans	ram:SpecifiedTradeSettlementPaymentMeans	[]*PaymentMeans	Payment instructions (BG-16)
Tax	ram:ApplicableTradeTax	[]*Tax	Tax category summaries (BG-23)
Period	ram:BillingSpecifiedPeriod	*Period	Invoice period (BG-14)
AllowanceCharges	ram:SpecifiedTradeAllowanceCharge	[]*AllowanceCharge	Document-level charges/discounts (BG-20, BG-21)
PaymentTerms	ram:SpecifiedTradePaymentTerms	[]*Terms	Payment terms and due dates (BG-8)
Summary	ram:SpecifiedTradeSettlementHeaderMonetarySummation	*Summary	Monetary totals (BG-22)
ReferencedDocument	ram:InvoiceReferencedDocument	[]*ReferencedDocument	Preceding invoice references (BG-3)
Advance	ram:SpecifiedAdvancePayment	[]*Advance	Advance payments (BG-24)

Summary Structure settlement.go95-106

Field	XML Tag	Type	Purpose
LineTotalAmount	ram:LineTotalAmount	string	Sum of line net amounts (BT-106)
Charges	ram:ChargeTotalAmount	string	Sum of document charges (BT-108)
Discounts	ram:AllowanceTotalAmount	string	Sum of document allowances (BT-107)
TaxBasisTotalAmount	ram:TaxBasisTotalAmount	string	Invoice total without VAT (BT-109)
TaxTotalAmount	ram:TaxTotalAmount	*TaxTotalAmount	Total VAT amount (BT-110)
RoundingAmount	ram:RoundingAmount	string	Rounding adjustment (BT-114)
GrandTotalAmount	ram:GrandTotalAmount	string	Invoice total with VAT (BT-112)
TotalPrepaidAmount	ram:TotalPrepaidAmount	string	Sum of advances (BT-113)
DuePayableAmount	ram:DuePayableAmount	string	Amount due for payment (BT-115)

PaymentMeans Structure settlement.go43-51

Field	XML Tag	Type	Purpose
TypeCode	ram:TypeCode	string	UNTDID 4461 payment means code (BT-81)
Information	ram:Information	string	Additional payment information (BT-82)
Card	ram:ApplicableTradeSettlementFinancialCard	*Card	Card payment details (BG-18)
Debtor	ram:PayerPartyDebtorFinancialAccount	*DebtorAccount	Debtor account for direct debit (BG-19)
Creditor	ram:PayeePartyCreditorFinancialAccount	*Creditor	Creditor account for credit transfer (BG-17)
CreditorInstitution	ram:PayeeSpecifiedCreditorFinancialInstitution	*CreditorInstitution	Bank BIC code

Tax Structure invoice.go35-44

Field	XML Tag	Type	Purpose
CalculatedAmount	ram:CalculatedAmount	string	Tax amount for this category (BT-117)
TypeCode	ram:TypeCode	string	Tax type (typically "VAT") (BT-118)
ExemptionReason	ram:ExemptionReason	string	Human-readable exemption reason (BT-120)
BasisAmount	ram:BasisAmount	string	Tax basis amount (BT-116)
CategoryCode	ram:CategoryCode	string	UNTDID 5305 tax category (BT-118)
ExemptionReasonCode	ram:ExemptionReasonCode	string	CEF VATEX exemption code (BT-121)
TaxPointDate	ram:TaxPointDate	*IssueDate	VAT point date (BT-7)
RateApplicablePercent	ram:RateApplicablePercent	string	Tax rate percentage (BT-119)

Invoice Root Structure invoice.go15-24

Field	XML Tag	Type	Purpose
XMLName	rsm:CrossIndustryInvoice	xml.Name	Root element
RSMNamespace	xmlns:rsm	string	RSM namespace declaration
RAMNamespace	xmlns:ram	string	RAM namespace declaration
QDTNamespace	xmlns:qdt	string	QDT namespace declaration
UDTNamespace	xmlns:udt	string	UDT namespace declaration
ExchangedContext	rsm:ExchangedDocumentContext	*ExchangedContext	Document context (guideline/business IDs)
ExchangedDocument	rsm:ExchangedDocument	*Header	Document header (ID, type, dates)
Transaction	rsm:SupplyChainTradeTransaction	*Transaction	Main transaction container

Sources: settlement.go16-106 invoice.go15-44

7.3 Extension Keys and Code Mappings

Payment Means Code Mapping

The getPaymentMeansCode function settlement.go367-378 requires the UNTDID 4461 payment means code in GOBL extensions:

Common payment means codes:

• 30 — Credit transfer
• 31 — Debit transfer
• 42 — Payment to bank account
• 48 — Card payment
• 49 — Direct debit
• 58 — SEPA credit transfer
• 59 — SEPA direct debit

Tax Category Code Mapping invoice.go318-349

UNTDID 5305 tax category codes used in Tax.CategoryCode:

Code	Meaning	Business Rules
S	Standard rate	Must include RateApplicablePercent
Z	Zero-rated	Must include RateApplicablePercent ("0")
E	Exempt from tax	May include ExemptionReason, ExemptionReasonCode
AE	Reverse charge	May include ExemptionReason, ExemptionReasonCode
K	Intra-community supply	May include ExemptionReason, ExemptionReasonCode
G	Free export	May include ExemptionReason, ExemptionReasonCode
O	Not subject to VAT	No rate allowed (BR-O-05)

Tax Exemption Reason Codes settlement.go336-338

CEF VATEX codes stored in cef.ExtKeyVATEX extension:

• VATEX-EU-79-C — Article 79, point c of Directive 2006/112/EC
• VATEX-EU-132 — Article 132 of Directive 2006/112/EC
• VATEX-EU-143 — Article 143 of Directive 2006/112/EC
• Custom national codes (e.g., VATEX-FR-262)

Document Type Code Mapping

UNTDID 1001 document type codes used in untdid.ExtKeyDocumentType:

Code	Type	Description
380	Commercial invoice	Standard invoice
381	Credit note	Negative invoice
384	Corrected invoice	Correction of previous invoice
389	Self-billed invoice	Invoice issued by buyer

Tax Map During Parsing invoice_parse.go156-202

The buildTaxCategoryMap function creates a lookup map for preserving exemption codes during CII→GOBL conversion:

Key construction logic:

• Standard rate S: "VAT:S:20" (includes rate for multiple S entries)
• Exempt categories: "VAT:E" (no rate component)

Sources: settlement.go336-378 invoice_parse.go156-202 invoice.go318-349

7.4 Standards Compliance and Limitations

Supported Features

Feature	GOBL→CII	CII→GOBL	Notes
Standard invoices	✓	✓	Document type 380
Credit notes	✓	✓	Document type 381
Corrected invoices	✓	✓	Uses preceding document references
Self-billed	✓	✓	Document type 389
Multiple tax rates	✓	✓	Full support
Document-level charges	✓	✓	Via AllowanceCharges
Line-level charges	✓	✓	Via LineAllowanceCharge
Attachments	✓	✓	Base64-encoded binary data
Payment terms	✓	✓	Multiple due dates supported
Delivery details	✓	✓	Address and dates
Tax representative	✓	✓	Via TaxRepresentative party

Critical Limitations

1. Included Tax Not Supported cii.go175-177

CII requires tax-exclusive pricing. GOBL invoices with tax.PricesInclude set to taxes must be convertible to tax-exclusive format or conversion fails.

2. Addon Enforcement cii.go168-171

Each Context requires specific GOBL addons:

Missing required addons cause conversion failure.

3. Single Document Type Support

Only bill.Invoice documents are supported. Other GOBL document types (credit memos, debit notes, etc.) return ErrUnsupportedDocumentType.

Known Data Loss Scenarios

GOBL → CII

GOBL Field	Loss Type	Reason
Custom Meta fields	Complete loss	No CII equivalent
Line-level Notes with complex keys	Partial loss	Merged into single Content field
Multiple Identities per party	Partial loss	Only first suitable ID mapped
Precision > 2 decimals	Rounding	CII typically uses 2 decimal places

CII → GOBL

CII Field	Loss Type	Reason
Terms.Amount	Not imported	Parse-only field settlement.go37-41
Terms.Percent	Not imported	Parse-only field settlement.go37-41
Custom Note.SubjectCode	Partial loss	Stored in extensions but may not round-trip perfectly
Multiple PaymentMeans	Only first used	GOBL pay.Instructions has single-means structure

Version-Specific Constraints

D16B (Default)

D22B (Peppol France Only)

D22B provides additional field support for French Peppol requirements but is not backward-compatible with D16B validators.

Validation Stages

The package performs structural validation during conversion. Standards compliance validation (XSD, Schematron) requires external tools like Phive cii.go37

Sources: cii.go168-177 settlement.go37-41 invoice_parse.go156-202

---

Standards Compliance and Limitations

Supported Conversions

Direction	Supported	Notes
GOBL → CII	✓ Full	All invoice types
CII → GOBL	✓ Full	Namespace detection required
Credit Notes	✓	Handled via invoice type codes
Corrective Invoices	✓	Uses preceding document references

Known Limitations

Tax Handling Constraints

Included Taxes Not Supported:

CII requires tax-exclusive amounts. The converter automatically attempts to remove included taxes, but if this operation fails, conversion is aborted.

Impact: Invoices with prices including tax must be convertible to tax-exclusive format.

Addon Requirements

Each context requires specific GOBL addons:

Validation Location: cii.go168-171

Namespace Support

Currently Supported:

• urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100 (NamespaceRSM)

Not Yet Supported:

• Other UN/CEFACT document types (despatch advice, receipt advice, etc.)
• Custom CII extensions

Document Type Support

Parse Function:

• Only bill.Invoice extraction implemented
• Other document types return ErrUnknownDocumentType

Convert Function:

• Only bill.Invoice conversion implemented
• Other types return ErrUnsupportedDocumentType

Future Extension: The architecture supports adding other document types by adding cases to the switch statements at cii.go139-147 and cii.go165-182

CII Version Differences

Most contexts use VersionD16B for maximum compatibility. Only Peppol France CIUS and Extended variants use VersionD22B for additional field support.

Sources: cii.go45-48 cii.go94 cii.go102

Data Loss Scenarios

GOBL → CII:

• Custom metadata not in CII specification
• GOBL-specific extensions not mapped to CII equivalents
• Precision loss in amounts (CII typically uses 2 decimal places for currency)

CII → GOBL:

• CII-specific codes may be mapped to generic GOBL equivalents
• Some CII optional fields may not have GOBL equivalents
• Document-level notes vs. line-level notes may be consolidated

Validation Boundaries

The package performs structural and addon validation during conversion. Standards compliance validation (XSD, Schematron) is the responsibility of downstream systems or external validation tools.

Sources: cii.go168-177

---

Sources Summary

This technical reference documentation is based on analysis of the following source files:

• Core Implementation: cii.go1-231
• Dependencies: go.mod1-42 go.sum1-102
• Test Examples: cii_test.go1-58

For additional implementation details on specific components, refer to:

• Conversion logic: invoice.go party.go settlement.go lines.go agreement.go
• Parsing logic: invoice_parse.go settlement_parse.go party_parse.go
• Internal utilities: internal/gtoc/ internal/ctog/ document/utils.go