GOBL.CII

GOBL conversion into Cross Industry Invoice (CII) XML format and vice versa.

Copyright Invopop Ltd. 2025. Released publicly under the Apache License Version 2.0. For commercial licenses, please contact the dev team at invopop. To accept contributions to this library, we require transferring copyrights to Invopop Ltd.

Usage

Go Package

Usage of the GOBL to CII conversion library is straightforward and supports two key actions

1. Conversion of GOBL to CII XML: You must first have a GOBL Envelope, including an invoice, ready to convert. There are some samples in the test/data directory.

2. Parsing of CII XML to GOBL: You need to have a valid CII XML document that you want to convert to GOBL format.

Both conversion directions are supported, allowing you to seamlessly transform between GOBL and CII XML formats as needed.

Converting GOBL to CII Invoice

package main

import (
    "os"

    "github.com/invopop/gobl"
    cii "github.com/invopop/gobl.cii"
)

func main() {
    data, _ := os.ReadFile("./test/data/invoice-sample.json")

    env := new(gobl.Envelope)
    if err := json.Unmarshal(data, env); err != nil {
        panic(err)
    }

    // Prepare the CII document
    doc, err := cii.ConvertInvoice(env)
    if err != nil {
        panic(err)
    }

    // Create the XML output
    out, err := doc.Bytes()
    if err != nil {
        panic(err)
    }

}

Contexts are supported to include specific Guideline and Business rules. Available contexts include:

• ContextEN16931V2017 (default)
• ContextPeppolV3
• ContextXRechnungV3
• ContextChorusProV1
• ContextPeppolFranceFacturXV1
• ContextPeppolFranceCIUSV1
• ContextCDARFlow6, ContextCDARFlow6PPF

Factur-X and ZUGFeRD have one context per profile, since BT-24 is checked against a closed codelist per profile:

Profile	Factur-X	ZUGFeRD
BASIC	ContextFacturXBasicV1	ContextZUGFeRDBasicV2
EN 16931	ContextFacturXV1	ContextZUGFeRDV2
EXTENDED	ContextFacturXExtendedV1	ContextZUGFeRDExtendedV2

MINIMUM and BASIC WL are not covered: they are not EN 16931 conformant.

Example:

doc, err := cii.ConvertInvoice(env, cii.WithContext(cii.ContextXRechnungV3))

Parsing CII Invoice into GOBL

package main

import (
    "io"

    cii "github.com/invopop/gobl.cii"
    )

func main() {
    // Read the CII XML file
	data, err := io.ReadAll("path/to/cii_invoice.xml")
	if err != nil {
		panic(err)
	}

    env, err := cii.Parse(data)
    if err != nil {
        panic(err)
    }

    out, err = json.MarshalIndent(env, "", "  ")
    if err != nil {
        panic(err)
    }
}

Command Line

The GOBL to CII tool includes a command-line helper. You can install it manually in your Go environment with:

go install ./cmd/gobl.cii

Usage:

gobl.cii convert <input> <output> [--context <format>]

The tool automatically detects the input file type (JSON/XML) and performs the appropriate conversion. Optionally specify a context format:

gobl.cii convert invoice.json invoice.xml --context xrechnung

Testing

Run tests with:

go test ./...

To update test fixtures:

go test ./... -update

To validate XML output using Phive:

go test ./... -validate

Validation requires a running Phive service on 127.0.0.1:9091

Considerations

There are certain assumptions and lost information in the conversion from CII to GOBL that should be considered:

1. GOBL does not currently support additional embedded documents, so the AdditionalReferencedDocument field (BG-24 in EN 16931) is not supported and lost in the conversion.
2. Payment advances do not include their own tax rate, they use the global tax rate of the invoice.
3. The fields ReceivableSpecifiedTradeAccountingAccount (BT-133) and DesignatedProductClassification (BT-158) are added as a note to the line, with the type code as the key.

Development

The main source of information for this project comes from the EN 16931 standard, developed by the EU for electronic invoicing. Part 1 of the standard defines the semantic data model that forms an invoice, but does not provide a concrete implementation. Part 3.3 defines the mappings from the semantic data model to the CII XML format covered in this repository.

Useful links:

• UN/CEFACT CII
• CII Schemas