Core Conversion API

Relevant source files

• cii.go
• cii_test.go
• invoice.go
• invoice_parse.go
• party_parse.go
• settlement.go

This document provides a comprehensive reference for the primary conversion functions in the gobl.cii package. It covers the main entry points for bidirectional conversion between GOBL and CII formats, the context system that governs output profiles, and the options pattern for configuration.

For detailed information about specific conversion directions, see Convert Function (GOBL to CII) and Parse Function (CII to GOBL). For context selection and standard-specific behavior, see Context System. For CDAR acknowledgement documents, see CDAR Acknowledgement Documents.

Overview of API Design

The core API exposes three primary function families:

Function Family	Direction	Purpose	Returns
Convert() / ConvertInvoice()	GOBL → CII	Converts GOBL invoices to CII XML structures	*Invoice (Go struct)
Parse()	CII → GOBL	Parses CII XML into GOBL envelopes	*gobl.Envelope
Unmarshal() / UnmarshalInvoice() / UnmarshalCDAR()	CII → Go	Unmarshals CII XML into Go structs without GOBL conversion	*Invoice or *CDAR

The API follows a "smart defaults with explicit overrides" pattern. GOBL-to-CII conversion defaults to the EN16931 context but can be customized via functional options. CII-to-GOBL parsing automatically detects the source context from the document itself.

Sources: cii.go154-262

Main API Entry Points

Function: Convert()

func Convert(env *gobl.Envelope, opts ...Option) (any, error)

The Convert() function is the primary entry point for converting GOBL documents to CII format. It accepts a GOBL envelope and returns a type-appropriate Go structure (typically *Invoice).

Key behaviors:

1. Context selection: Defaults to ContextEN16931V2017, overridden via WithContext() option
2. Addon validation: Verifies the GOBL invoice contains all required addons for the selected context
3. Tax normalization: Automatically removes included taxes (not supported in CII)
4. Type dispatch: Routes to appropriate generator based on envelope content type

Sources: cii.go201-229

---

Function: ConvertInvoice()

func ConvertInvoice(env *gobl.Envelope, opts ...Option) (*Invoice, error)

A convenience wrapper around Convert() that provides strong typing for invoice conversion. It asserts the result is an *Invoice and returns an error if the envelope contains a different document type.

Sources: invoice.go58-70

---

Function: Parse()

func Parse(data []byte) (*gobl.Envelope, error)

The Parse() function is the primary entry point for converting CII XML to GOBL format. It automatically detects the document type and performs the appropriate conversion.

Key behaviors:

1. Namespace detection: Extracts the root XML namespace to identify document type
2. Type routing: Only supports NamespaceRSM (standard CII invoices)
3. Context inference: Automatically detects the source context from guideline/business IDs
4. Envelope wrapping: Returns a complete GOBL envelope with the converted invoice

Sources: cii.go154-178

---

Function: Unmarshal()

func Unmarshal(data []byte) (any, error)

A lower-level function that unmarshals CII XML into Go structures without performing GOBL conversion. Returns either *Invoice or *CDAR depending on the detected document type.

Use cases:

• Inspecting CII documents without full conversion
• Processing CDAR acknowledgement documents
• Custom conversion workflows

Sources: cii.go180-199

API Entry Points Diagram

Sources: cii.go154-262 invoice.go58-87

Document Type Detection

The API uses XML namespace detection to distinguish between different CII document types before processing. This mechanism is implemented in extractRootNamespace().

Supported Namespaces

Namespace	Document Type	Routing
urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100	Standard CII Invoice	parseInvoice() / UnmarshalInvoice()
urn:un:unece:uncefact:data:standard:CrossDomainAcknowledgement:100	CDAR Acknowledgement	UnmarshalCDAR()
Other	Unknown	Returns ErrUnknownDocumentType

Namespace Detection Flow

Sources: cii.go246-262 cii.go154-178 cii.go183-199

Implementation Details

The extractRootNamespace() function uses a streaming XML decoder to extract the namespace from the root element without parsing the entire document:

This approach is efficient because it avoids unmarshaling the full document when only type detection is needed.

Sources: cii.go246-262

Context System Overview

The Context struct defines the profile for CII document generation. Each context specifies:

Field	Purpose	Example
GuidelineID	Primary standard identifier	"urn:cen.eu:en16931:2017"
BusinessID	Business process context (optional)	"urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
Version	CII schema version	"D16B" or "D22B"
Addons	Required GOBL addons	[]cbc.Key{en16931.V2017}
VESID	Validation Exchange Specification ID	"eu.cen.en16931:cii:1.3.13"

Predefined Contexts

The package provides 8 predefined contexts:

Sources: cii.go51-137

Context Lookup During Parsing

The FindContext() function performs reverse lookup during CII-to-GOBL parsing:

func FindContext(guidelineID string, businessID string) *Context

Matching logic:

1. Iterate through predefined contexts
2. Match on GuidelineID
3. If context has a BusinessID, verify it matches (if provided)
4. Return first matching context or nil

This enables automatic context detection when parsing CII documents, allowing the parser to infer which addons to apply to the resulting GOBL invoice.

Sources: cii.go139-152 invoice_parse.go33-66

Functional Options Pattern

The conversion API uses the functional options pattern for configuration. This provides a clean, extensible way to customize conversion behavior.

Options Structure

Sources: cii.go231-244

Available Options

WithContext(context Context)

Overrides the default EN16931 context with a specific e-invoicing standard context.

Implementation:

type Option func(*options)

func WithContext(context Context) Option {
    return func(o *options) {
        o.context = context
    }
}

Sources: cii.go231-244 cii_test.go12-57

Error Handling

The API defines two sentinel errors for common failure modes:

Error Types

Error	Trigger Condition	Typical Cause
ErrUnknownDocumentType	Root namespace not recognized	Malformed XML, unsupported CII variant, non-CII document
ErrUnsupportedDocumentType	Document type cannot be converted	Passing non-invoice document to Convert()

Error Flow

Sources: cii.go21-29 cii.go154-178 cii.go201-229

Additional Validation Errors

During conversion, additional validation errors may be returned:

Addon validation error:

Included taxes error:

Payment means validation:

// From settlement.go:367-378
if instr.Ext[untdid.ExtKeyPaymentMeans].String() == "" {
    return "", validation.Errors{...}
}

Sources: cii.go213-223 settlement.go367-378

Conversion Pipeline Architecture

GOBL to CII Pipeline

Sources: cii.go201-229 invoice.go89-133

CII to GOBL Pipeline

Sources: cii.go154-178 invoice_parse.go17-154

Code Entity Mapping

This section maps natural language concepts to specific code entities:

Concept	Primary Code Entity	Location
Convert GOBL to CII	Convert() function	cii.go201-229
Convert with type safety	ConvertInvoice() function	invoice.go58-70
Parse CII to GOBL	Parse() function	cii.go154-178
Unmarshal without conversion	Unmarshal() function	cii.go180-199
Context configuration	Context struct	cii.go51-61
Default context	ContextEN16931V2017 variable	cii.go63-69
Context selection	WithContext() option	cii.go239-244
Document type detection	extractRootNamespace() function	cii.go246-262
Context lookup	FindContext() function	cii.go139-152
Invoice generation	newInvoice() function	invoice.go89-112
Invoice parsing	parseInvoice() function	invoice_parse.go17-31
GOBL conversion	goblInvoice() function	invoice_parse.go33-154
Tax category mapping	buildTaxCategoryMap() function	invoice_parse.go163-177
Unknown document error	ErrUnknownDocumentType variable	cii.go21-24
Unsupported document error	ErrUnsupportedDocumentType variable	cii.go26-29

Sources: cii.go1-262 invoice.go1-146 invoice_parse.go1-203