This page provides complete, working examples for the most common gobl.cii conversion workflows. Each example includes input data references, conversion code, and expected output structure. These examples are designed to get you started quickly with typical use cases.
For detailed CLI documentation, see 2.2. For comprehensive Go API reference, see 2.3. For context configuration details, see 3.3.
The gobl.cii library supports two primary conversion directions, each with multiple context options. The following diagram shows the complete workflow with actual function names and test data locations:
Sources: cii.go1-240 examples_test.go40-122 README.md10-105
This example demonstrates the simplest conversion case: transforming a GOBL invoice into EN16931-compliant CII XML using the default context.
The GOBL invoice must include the eu-en16931-v2017 addon for EN16931 conversion:
| GOBL Field | Required | Description |
|---|---|---|
$addons | Yes | Must include "eu-en16931-v2017" |
type | Yes | Invoice type: "standard", "credit-note", "corrective" |
supplier | Yes | Supplier party details |
customer | Yes | Customer party details |
lines | Yes | Invoice line items |
tax.prices_include | No | If present, will be removed automatically |
The generated CII XML follows the EN16931 profile structure:
Sources: cii.go180-206 README.md24-57 cmd/gobl.cii/convert.go34-115 test/data/convert/en16931/out/invoice-de-de.xml1-140
This example shows the reverse operation: parsing a CII XML document into a GOBL envelope.
The CLI automatically detects whether the input is JSON or XML by testing JSON validity on line cmd/gobl.cii/convert.go76
The parser recognizes the following CII TypeCode values and maps them to GOBL invoice types:
| CII TypeCode | GOBL Type | Description |
|---|---|---|
| 380 | standard | Commercial invoice |
| 381 | credit-note | Credit note |
| 384 | corrective | Corrected invoice |
| 389 | standard (tagged) | Self-billed invoice |
Sources: cii.go135-155 cii.go223-239 cmd/gobl.cii/convert.go97-108 examples_test.go124-210
Different contexts generate CII XML with specific metadata and validation rules. This example shows how to use various contexts.
CLI Equivalent:
CLI Equivalent:
| Context | Required Addon | BusinessID | VESID |
|---|---|---|---|
| EN16931 | eu-en16931-v2017 | - | eu.cen.en16931:cii:1.3.13 |
| Peppol | eu-en16931-v2017 | urn:fdc:peppol.eu:2017:poacc:billing:01:1.0 | eu.cen.en16931:cii:1.3.13 |
| XRechnung | de-xrechnung-v3 | urn:fdc:peppol.eu:2017:poacc:billing:01:1.0 | de.xrechnung:cii:3.0.2 |
| Factur-X | fr-facturx-v1 | - | fr.factur-x:extended:1.0.7-2 |
| ZUGFeRD | de-zugferd-v2 | - | de.zugferd:extended:2.3.2 |
| Chorus Pro | fr-choruspro-v1 | - | - |
The conversion function validates that the required addon is present on lines cii.go190-194
Sources: cii.go39-129 cii.go180-206 cmd/gobl.cii/convert.go39-56 examples_test.go54-68
This example demonstrates a complete workflow using the CLI tool, including both conversion directions.
Sources: cmd/gobl.cii/convert.go1-116 README.md107-126
GOBL invoices with tax.prices_include set will have included taxes automatically removed during conversion, as CII does not support included taxes.
The automatic removal happens at cii.go197-199 The test data at test/data/convert/en16931/invoice-prices-include.json demonstrates this transformation:
Input (GOBL):
25.00 (tax included)19.0%tax.prices_include: "VAT"Output (CII):
21.0084 (tax excluded)The repository includes comprehensive test data organized by context and conversion direction:
Test examples can be found in:
test/data/convert/{context}/ for GOBL JSON inputstest/data/parse/{context}/ for CII XML inputsout/ subdirectoriesSources: cii.go197-199 examples_test.go54-122 examples_test.go269-314 README.md149-155
This example shows how to programmatically choose contexts based on business requirements.
| Requirement | Recommended Context | Reason |
|---|---|---|
| German public sector (B2G) | ContextXRechnungV3 | Leitweg-ID routing required |
| French public sector | ContextChorusProV1 | Chorus Pro platform compliance |
| Pan-European network | ContextPeppolV3 | Peppol Access Point routing |
| French B2B/B2C | ContextFacturXV1 | Factur-X legal requirement |
| German B2B | ContextZUGFeRDV2 | ZUGFeRD standard |
| Generic EU | ContextEN16931V2017 | Base standard |
Sources: cii.go39-129 cii.go208-214 examples_test.go54-68
The repository includes test fixtures demonstrating each example. To run tests with fixture updates:
The test infrastructure is implemented in examples_test.go24-314 with the following key components:
| Test Function | Purpose | Lines |
|---|---|---|
TestConvertToInvoice | Tests GOBL-to-CII conversion | 40-122 |
TestParseInvoice | Tests CII-to-GOBL parsing | 124-210 |
loadEnvelope | Helper to load GOBL test data | 231-254 |
parseInvoiceFrom | Helper to parse CII test data | 220-228 |
Sources: examples_test.go1-314 README.md128-148
Refresh this wiki