Overview

Relevant source files

• README.md
• cii.go
• cii_test.go
• cmd/gobl.cii/convert.go
• examples_test.go
• invoice.go
• invoice_parse.go
• party_parse.go
• settlement.go
• utils.go

Purpose and Scope

This document provides an introduction to the gobl.cii repository, a Go library and command-line tool that enables bidirectional conversion between GOBL (JSON format) and CII XML (Cross Industry Invoice) formats. The library supports six major European e-invoicing standards through eight predefined contexts in a unified context system.

For detailed architectural information including the conversion engine and document components, see page 1.1. For installation and usage instructions, see page 2. For information about specific e-invoicing standards, see page 5.

What is GOBL.CII

GOBL.CII is a specialized converter that bridges two invoice data formats:

• GOBL (Go Business Language): A structured JSON format for business documents, developed by Invopop
• CII (Cross Industry Invoice): An XML format standardized by UN/CEFACT, used as the foundation for most European e-invoicing regulations

The library implements the EN 16931 European standard mapping as defined in Part 3.3 of the specification, which provides the semantic model-to-CII transformation rules.

Sources: cii.go1-2 README.md1-4 README.md134-140

Data Formats

GOBL Format

GOBL documents are JSON-based and wrapped in an gobl.Envelope structure. The envelope contains metadata and the actual business document (typically a bill.Invoice). The format is validated against JSON schemas and supports addons for regional compliance requirements.

CII Format

CII (Cross Industry Invoice) is an XML format that uses UN/CEFACT's Core Component Technical Specification (CCTS). The format defines specific XML namespaces and structures:

Namespace Prefix	Namespace URI	Purpose
rsm	urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100	Root document structure
ram	urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100	Business entities (parties, products, etc.)
qdt	urn:un:unece:uncefact:data:standard:QualifiedDataType:100	Qualified data types
udt	urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100	Basic data types

CII supports two versions: D16B (older) and D22B (newer), selected via the Context.Version field.

Sources: cii.go30-48

Supported E-Invoicing Standards

The library supports six e-invoicing standards through a context-based system. Each context is represented by a Context struct containing:

• GuidelineID: URN identifying the semantic specification
• BusinessID: Optional URN for business process profiles
• Version: CII syntax version (D16B or D22B)
• Addons: Required GOBL addon keys for validation

Supported Standards

Eight Predefined Contexts:

Standard	Context Constant	Guideline ID	Version	Line Ref
EN 16931:2017	ContextEN16931V2017	urn:cen.eu:en16931:2017	D16B	cii.go64-69
Peppol BIS 3.0	ContextPeppolV3	urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0	D16B	cii.go72-78
Factur-X v1	ContextFacturXV1	urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:extended	D16B	cii.go81-86
Peppol France Factur-X	ContextPeppolFranceFacturXV1	urn:cen.eu:en16931:2017#conformant#urn:peppol:france:billing:Factur-X:1.0	D16B	cii.go89-95
Peppol France CIUS	ContextPeppolFranceCIUSV1	urn:cen.eu:en16931:2017#compliant#urn:peppol:france:billing:cius:1.0	D22B	cii.go98-104
ZUGFeRD v2	ContextZUGFeRDV2	urn:cen.eu:en16931:2017#conformant#urn:zugferd.de:2p0:extended	D16B	cii.go107-112
XRechnung v3.0	ContextXRechnungV3	urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0	D16B	cii.go115-121
Chorus Pro v1	ContextChorusProV1	A1 (framework-specific)	D16B	cii.go123-129

Each context requires specific GOBL addons (e.g., en16931.V2017, xrechnung.V3) to ensure the source invoice contains the necessary metadata for that standard.

Sources: cii.go50-128 examples_test.go54-68

Core Conversion Capabilities

Bidirectional Conversion Flow

The library provides two primary conversion directions:

GOBL to CII Conversion

Conversion Pipeline:

The ConvertInvoice function transforms a GOBL envelope into a CII Invoice structure:

1. Validates that the envelope contains a bill.Invoice cii.go188-189
2. Checks that required addons for the selected context are present cii.go191-194
3. Removes included taxes (not supported in CII) cii.go198-200
4. Delegates to newInvoice to construct the CII document structure cii.go202
5. Returns an *Invoice ready for XML serialization invoice.go58-68

Key Functions:

• ConvertInvoice(env *gobl.Envelope, opts ...Option) (*Invoice, error) invoice.go58-68
• Convert(env *gobl.Envelope, opts ...Option) (any, error) cii.go180-206
• WithContext(context Context) Option cii.go217-221
• newInvoice(inv *bill.Invoice, context Context) (*Invoice, error) invoice.go87-110

CII to GOBL Conversion

Parsing Pipeline:

The Parse function transforms CII XML into a GOBL envelope:

1. Extracts the root XML namespace to identify document type cii.go136-138
2. Creates a new GOBL envelope cii.go145
3. Delegates to parseInvoice for CII documents cii.go146-149
4. Wraps the parsed invoice in the envelope cii.go151-153
5. Returns the envelope ready for GOBL processing cii.go154

Key Functions:

• Parse(data []byte) (*gobl.Envelope, error) cii.go135-155
• extractRootNamespace(data []byte) (string, error) cii.go223-239
• Namespace constant: NamespaceRSM cii.go33

Sources: cii.go135-155 cii.go223-239 cmd/gobl.cii/convert.go34-115

Entry Points and Usage Interfaces

Go Package API

The package provides a programmatic API for integration into Go applications:

Public API Structure:

Sources: cii.go133-214 README.md12-105

Command-Line Interface

The CLI tool provides a simple conversion interface with automatic format detection:

CLI Conversion Flow:

The CLI automatically detects whether the input is JSON (GOBL) or XML (CII) and performs the appropriate conversion. The --context flag specifies which e-invoicing standard to target when converting from GOBL to CII.

Supported Context Values:

• en16931 → ContextEN16931V2017 convert.go50-51
• xrechnung → ContextXRechnungV3 convert.go46-47
• facturx → ContextFacturXV1 convert.go42-43
• peppol → ContextPeppolV3 convert.go48-49
• choruspro → ContextChorusProV1 convert.go52-53
• zugferd → ContextZUGFeRDV2 convert.go44-45

Sources: cmd/gobl.cii/convert.go1-116 README.md107-125

Package Structure

The codebase is organized into several key modules:

Module Dependencies and Structure:

The package follows a clear separation between:

• Forward conversion (GOBL → CII): Implemented in builder files like settlement.go, lines.go, party.go, agreement.go
• Reverse conversion (CII → GOBL): Implemented in *_parse.go files
• CLI wrapper: Located in cmd/gobl.cii/ with convert.go as the main command
• Testing: examples_test.go contains integration tests, while *_test.go files provide component-level tests

Sources: go.mod1-42 cii.go1-18 invoice.go1-11 examples_test.go1-40

Key Data Structures

Context Structure

The Context struct controls conversion behavior:

The VESID field is used for validation with the Phive service during testing examples_test.go103-104

Sources: cii.go54-61

Conversion Options

The Option type provides functional configuration:

This pattern allows flexible configuration while maintaining a clean API.

Sources: cii.go208-221

Important Considerations

Data Loss During Conversion

When converting from CII to GOBL, certain information may be lost or transformed:

1. Additional embedded documents (AdditionalReferencedDocument / BG-24) are not supported
2. Payment advances do not preserve their individual tax rates; they inherit the invoice's global tax rate
3. Accounting account references (ReceivableSpecifiedTradeAccountingAccount / BT-133) are converted to notes
4. Product classifications (DesignatedProductClassification / BT-158) are converted to notes

Tax Handling

The conversion process removes included taxes from GOBL invoices before converting to CII, as CII only supports exclusive tax amounts. This is performed automatically by doc.RemoveIncludedTaxes().

Sources: cii.go198-200 README.md150-156

Version Information

The library depends on:

• GOBL: v0.303.0
• Go: 1.24.4+
• CII Syntax: D16B (primary), D22B (select contexts)

Sources: go.mod1-14 go.sum25-26