Go API Usage

Relevant source files

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

This page demonstrates how to use gobl.cii as a Go library for bidirectional conversion between GOBL JSON invoices and CII XML documents. For command-line usage, see CLI Usage. For complete working examples, see Quick Start Examples. For detailed API documentation, see Core Conversion API.

Module Import

To use gobl.cii as a library, add it to your Go project:

Import the package in your code:

The library requires Go 1.24.4 or later as specified in go.mod3

Sources: go.mod1-3

Public API Overview

The library provides three primary entry points for conversion operations:

Diagram: Public API Surface

Function	Purpose	Input	Output
Parse	CII XML → GOBL	Raw XML bytes	GOBL Envelope
Convert	GOBL → CII	GOBL Envelope	CII document (any type)
ConvertInvoice	GOBL → CII Invoice	GOBL Envelope	CII Invoice struct
WithContext	Set target standard	Context	Option function

Sources: cii.go130-199

Converting GOBL to CII

Basic Conversion

The most common use case is converting a GOBL invoice to CII XML using ConvertInvoice:

Diagram: GOBL to CII Conversion Flow

The conversion process follows these steps:

1. Unmarshal GOBL JSON into a gobl.Envelope
2. Call ConvertInvoice with optional context
3. Addon Validation: Checks that required addons are present cii.go170-174
4. Tax Processing: Removes included taxes (not supported in CII) cii.go177-179
5. Document Building: Constructs the CII structure cii.go181
6. Serialization: Generates XML bytes

Sources: cii.go157-199 README.md24-57

Example Code Pattern

Sources: README.md26-56 examples_test.go84-90

Parsing CII to GOBL

Basic Parsing

The Parse function converts CII XML to GOBL format:

Diagram: CII to GOBL Parsing Flow

The parsing process:

1. Namespace Detection: Identifies the document type by root namespace cii.go134-136
2. Type Routing: Currently supports NamespaceRSM (CII invoices) cii.go141-148
3. Invoice Parsing: Extracts data into GOBL structures (implementation in parsing modules)
4. Envelope Creation: Wraps the result in a GOBL envelope cii.go139-152

Sources: cii.go130-155 README.md77-105

Example Code Pattern

Sources: README.md79-105 examples_test.go156-161

Using Contexts

Contexts control which e-invoicing standard the output conforms to. The library provides eight predefined contexts:

Diagram: Context Selection Pattern

Context Properties

Each context specifies:

Field	Purpose	Example
GuidelineID	Standard identifier in XML	"urn:cen.eu:en16931:2017"
BusinessID	Peppol business process ID	"urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
Version	CII version (D16B/D22B)	"D16B"
Addons	Required GOBL addons	[]cbc.Key{en16931.V2017}
VESID	Validation Exchange Specification ID	"eu.cen.en16931:cii:1.3.13"

Sources: cii.go50-60 cii.go63-128

Using a Specific Context

The WithContext function implements the functional options pattern cii.go209-214 storing the context in an internal options struct cii.go201-203

Sources: cii.go209-214 README.md59-75 examples_test.go85-87

Error Handling

The library defines two primary error types:

Diagram: Error Handling Flow

Error Types

Error	When Raised	Code Location
ErrUnknownDocumentType	XML namespace not recognized during parsing	cii.go23
ErrUnsupportedDocumentType	Document type not supported for conversion	cii.go27
Missing addon error	Required addon not present in GOBL document	cii.go172
Included taxes error	Document has included taxes (not CII compatible)	cii.go178

Error Handling Example

Sources: cii.go20-28 cii.go167-184

Working with Invoice Output

The Invoice struct represents the complete CII document structure:

Diagram: Invoice Structure and Serialization

Invoice Struct Overview

The Invoice struct contains:

• XML Namespaces: Four CII namespaces (RSM, RAM, QDT, UDT) invoice.go13-17
• ExchangedContext: Context parameters (GuidelineID, BusinessID) invoice.go18
• ExchangedDocument: Document header (type, number, dates, notes) invoice.go19
• Transaction: Main business data container invoice.go20
  • Lines: Line items array invoice.go25
  • Agreement: Parties and agreements invoice.go26
  • Delivery: Delivery information invoice.go27
  • Settlement: Payment terms, taxes, totals invoice.go28

Sources: invoice.go12-29

Serialization Methods

The Invoice type provides XML serialization through standard Go encoding:

The XML output includes:

• XML declaration: <?xml version="1.0" encoding="UTF-8"?>
• Root element: <rsm:CrossIndustryInvoice> invoice.go13
• Namespace declarations for RSM, RAM, QDT, UDT invoice.go14-17

Sources: invoice.go12-21 examples_test.go89-90

Complete Usage Examples

GOBL to CII with Context

CII to GOBL with Validation

Sources: README.md26-105 examples_test.go79-119 examples_test.go154-179