Getting Started

Relevant source files

• README.md
• cmd/gobl.cii/convert.go
• examples_test.go
• go.mod
• go.sum
• utils.go

This page provides a practical guide to using gobl.cii for converting between GOBL and CII XML formats. It covers installation, basic usage patterns, and configuration through context selection.

For architectural concepts, see Overview. For detailed API documentation, see Core Conversion API. For standard-specific requirements, see E-Invoicing Standards.

---

What gobl.cii Does

The gobl.cii package provides bidirectional conversion between GOBL's internal invoice format and the UN/CEFACT Cross Industry Invoice (CII) XML standard.

Conversion Capabilities

Direction	Input	Output	Primary Function
GOBL → CII	gobl.Envelope (JSON)	CII XML (CrossIndustryInvoice)	cii.ConvertInvoice
CII → GOBL	CII XML (CrossIndustryInvoice)	gobl.Envelope (JSON)	cii.Parse

Additional functions:

• cii.Convert - Generic conversion dispatcher that handles multiple document types
• cii.Unmarshal - Low-level XML unmarshaling for both invoices and CDAR documents
• cii.UnmarshalInvoice - Unmarshal CII XML to Invoice struct without GOBL conversion
• cii.UnmarshalCDAR - Unmarshal CDAR acknowledgement documents

Diagram: Core Conversion Functions

Sources: cii.go131-206 README.md14-22

---

Prerequisites

For CLI Usage:

• The gobl.cii binary installed (see Installation)
• Input files: GOBL JSON for conversion to CII, or CII XML for conversion to GOBL

For Go Library Usage:

• Go 1.24.4 or later (as specified in go.mod3)
• Module dependency: github.com/invopop/gobl.cii

For GOBL → CII Conversion:

• Valid gobl.Envelope containing a bill.Invoice
• Invoice must have required addons for the target context (validated automatically)
• No included taxes (CII does not support prices_include tax mode)

For CII → GOBL Conversion:

• Valid CII XML document
• Root namespace must be urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100 (NamespaceRSM)
• For CDAR documents, namespace must be urn:un:unece:uncefact:data:standard:CrossIndustryAcknowledgementResponse:100 (NamespaceCDARRSM)

Sources: cii.go157-169 README.md149-156 go.mod3

---

Quick Installation

Install CLI via Go:

Add library to Go project:

The package requires Go 1.24.4+ and depends on:

• github.com/invopop/gobl v0.308.0
• github.com/invopop/xmlctx v0.13.0
• github.com/invopop/validation v0.8.0
• github.com/invopop/phive v0.6.0 (optional, for validation)

For complete installation instructions including pre-built binaries, see Installation.

Sources: README.md108-113 go.mod5-15

---

First Conversion: GOBL to CII

Step 1: Prepare GOBL Input

Start with a valid GOBL envelope containing an invoice. Sample files are available in test/data/convert/

Step 2: Convert to CII

Call cii.ConvertInvoice with optional context selection:

Step 3: Serialize to XML

Call Bytes() to get XML output:

The conversion validates that:

1. Required addons for the context are present
2. No included taxes exist (see README.md149-156)
3. The document structure is valid

Sources: README.md24-57 cii.go131-145 utils.go16-22

---

First Conversion: CII to GOBL

Step 1: Read CII XML

Step 2: Parse to GOBL

Call cii.Parse to convert XML to a GOBL envelope:

The parser automatically:

1. Detects document type via root namespace
2. Extracts all invoice data into GOBL structures
3. Builds tax category mappings
4. Preserves exemption codes

Step 3: Export as JSON

Sources: README.md77-104 cii.go157-206

---

Choosing a Context

A Context defines which e-invoicing standard profile the output CII XML should conform to. The default is ContextEN16931V2017. Override this using the cii.WithContext option.

Available Contexts

Context Constant	Standard	GuidelineID	CII Version
ContextEN16931V2017	European EN 16931 base	urn:cen.eu:en16931:2017	D16B
ContextXRechnungV3	German XRechnung 3.0	urn:cen.eu:en16931:2017#compliant#urn:xrechnung.de:xrechnung_3.0	D16B
ContextPeppolV3	Peppol BIS Billing 3.0	urn:cen.eu:en16931:2017#conformant#urn:fdc:peppol.eu:2017:poacc:billing:international:aunz:3.0	D16B
ContextFacturXV1	French/German Factur-X	urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:extended	D22B
ContextZUGFeRDV2	German ZUGFeRD 2.0	urn:fdc:nen.nl:nlcius:v1.0	D16B
ContextChorusProV1	French Chorus Pro	A1	D16B
ContextPeppolFranceFacturXV1	Peppol France + Factur-X	urn:cen.eu:en16931:2017#conformant#urn:fdc:peppol:france:Factur-X:1.0	D22B
ContextPeppolFranceCIUSV1	Peppol France CIUS	urn:cen.eu:en16931:2017#conformant#urn:fdc:peppol:france:cius:1.0	D22B

Diagram: Context Selection Flow

Context Structure

Each Context contains:

Field	Type	Purpose
GuidelineID	string	Sets ExchangedDocumentContext.GuidelineSpecifiedDocumentContextParameter.ID
BusinessID	string	Sets ExchangedDocumentContext.BusinessProcessSpecifiedDocumentContextParameter.ID (optional)
Version	string	CII schema version: D16B (most standards) or D22B (Factur-X, newer Peppol France)
Addons	[]cbc.Key	Required GOBL addons that must be present in the invoice
VESID	string	Phive validation identifier (used by test suite with -validate flag)

Usage Example

For detailed requirements of each standard, see E-Invoicing Standards.

Sources: cii.go51-129 README.md59-75

---

CLI Usage Summary

The gobl.cii command-line tool provides a single convert command that automatically detects conversion direction.

Command Syntax

Direction Detection

The tool determines conversion direction automatically:

• If input is valid JSON → GOBL to CII conversion
• If input is XML → CII to GOBL conversion

Detection logic is in cmd/gobl.cii/convert.go76 using json.Valid(inData).

Context Flag Values

Flag Value	Context Constant	Standard
en16931	ContextEN16931V2017	European EN 16931 (default)
xrechnung	ContextXRechnungV3	German XRechnung 3.0
peppol	ContextPeppolV3	Peppol BIS Billing 3.0
facturx	ContextFacturXV1	French/German Factur-X
zugferd	ContextZUGFeRDV2	German ZUGFeRD 2.0
choruspro	ContextChorusProV1	French Chorus Pro

Examples

Convert GOBL to XRechnung XML:

Convert CII XML to GOBL (context flag ignored for this direction):

Use stdin/stdout:

For complete CLI documentation including all flags and examples, see CLI Usage.

Sources: cmd/gobl.cii/convert.go22-115 README.md107-125

---

API Usage Patterns

Diagram: API Function Call Flow

Key Function Signatures

Error Handling

Common errors returned by the API:

Error	Condition	Source
ErrUnknownDocumentType	XML namespace not recognized	cii.go197
validation.Errors	Missing required addons for context	cii.go138-140
validation.Errors	Invoice has included taxes	cii.go141-143

For detailed API documentation, see Go API Usage. For end-to-end examples, see Quick Start Examples.

Sources: cii.go131-206 utils.go16-22

---

What Comes Next

Topic	Page
Installing binaries and adding the Go module	Installation
Full CLI reference with all flags and examples	CLI Usage
Complete Go API with options and error handling	Go API Usage
Runnable end-to-end examples from the test suite	Quick Start Examples
Convert, Parse, Unmarshal API deep-dive	Core Conversion API
EN16931, XRechnung, Factur-X, Peppol, ZUGFeRD, Chorus Pro details	E-Invoicing Standards