invopop/gobl

Go Business Language

GOBL

Go Business Language. Core library and Schemas.

Released under the Apache 2.0 LICENSE, Copyright 2021-2024 Invopop S.L..

Official GOBL documentation site.

Introduction

GOBL, the Go Business Language library and tools, aim to:

• Help developers build electronic business documents, especially invoices, anywhere in the world.
• Define a set of open JSON Schema.
• Build a global database of local tax categories and, whenever practical to do so, provide current and historical tax rates in code.
• Validate business documents according to local requirements, including tax ID validation.
• Define the algorithms used to make tax calculations while avoiding rounding errors.
• Provide built-in support for signing documents using JSON Web Signatures.
• Output simple and easy-to-read JSON documents that emphasize the use of keys instead of abstract codes, like credit-transfer instead of 30 (UNTDID4461 code for sender-initiated bank or wire transfer).
• Be flexible enough to support extreme local complexity but produce output that is easily legible in other countries.
• Build a global community of contributors tired of the complexity of current standards based on XML or EDI.

Community

The complexity around invoicing, particularly electronic invoicing, can quickly become overwhelming. Check out the following resources and get in touch:

• Documentation contains details on how to use GOBL, and the schema.
• Builder helps try out GOBL and quickly figure out what is possible, all from your browser.
• Issues if you have a specific problem with GOBL related to code or usage.
• Discussions for open discussions about the future of GOBL, complications with a specific country, or any open-ended issues.
• Pull Requests are very welcome, especially if you'd like to see a new local country or features.
• Slack for real-time chat about something specific or urgent. We always encourage you to use one of the other options, which are indexed and searchable, but if you'd like to bring something to attention quickly, this is a great resource.

Companion Projects

GOBL makes it easy to create business documents, like invoices, but check out some of the companion projects that help create, use, and convert into other formats:

• Builder - Available to try at build.gobl.org, this tool makes it easy to build, test, and discover the features of GOBL using the wasm binary in the browser.
• Generator - Ruby project to convert GOBL JSON Schema into libraries for other languages or documentation.
• Docs - Content of the official GOBL Documentation Site docs.gobl.org.
• GOBL for Ruby - Easily build or read GOBL documents in Ruby.

Conversion to local formats

• GOBL to FacturaE (Spain) - convert into the Spanish FacturaE format.
• GOBL to CFDI (Mexico) - convert into the Mexican CFDI format.
• GOBL to FatturaPA (Italy) - convert into the Italian FatturaPA format.
• GOBL to FA_VAT / KSeF (Poland) - convert to the Polish FA_VAT format and send to KSeF
• GOBL to TicketBAI (Spain/Euskadi) - convert into TicketBAI documents, required in the Euskadi (northern region of Spain)
• GOBL to Factur-X (France) and XRechnung/ZUGFeRD (Germany) - convert into Factur-X (FR) and XRechnung/ZUGFeRD (DE) formats.

Usage

GOBL is primarily a Go library, so the following instructions assume you'd like to build documents from your own Go applications. See some of the links above if you'd like to develop in another language or use a CLI.

Installation

Run the following command to install the package:

go get github.com/invopop/gobl

Building an Invoice

There are many different ways to get data into GOBL, but for the following example, we're going to try to build an invoice in several steps.

First define a minimal or "partial" GOBL Invoice Document:

inv := &bill.Invoice{
	Series:    "F23",
	Code:      "00010",
	IssueDate: cal.MakeDate(2023, time.May, 11),
	Supplier: &org.Party{
		TaxID: &tax.Identity{
			Country: l10n.US,
		},
		Name:  "Provider One Inc.",
		Alias: "Provider One",
		Emails: []*org.Email{
			{
				Address: "[email protected]",
			},
		},
		Addresses: []*org.Address{
			{
				Number:   "16",
				Street:   "Jessie Street",
				Locality: "San Francisco",
				Region:   "CA",
				Code:     "94105",
				Country:  l10n.US,
			},
		},
	},
	Customer: &org.Party{
		Name: "Sample Customer",
		Emails: []*org.Email{
			{
				Address: "[email protected]",
			},
		},
	},
	Lines: []*bill.Line{
		{
			Quantity: num.MakeAmount(20, 0),
			Item: &org.Item{
				Name:  "A stylish mug",
				Price: num.MakeAmount(2000, 2),
				Unit:  org.UnitHour,
			},
			Taxes: []*tax.Combo{
				{
					Category: common.TaxCategoryST,
					Percent:  num.NewPercentage(85, 3),
				},
			},
		},
	},
}

Notice that the are no sums or calculations yet. The next step involves "inserting" the invoice document into an "envelope". In GOBL, we use the concept of an envelope to hold data and provide functionality to guarantee that no modifications have been made to the payload.

Insert our previous Invoice into an envelope as follows:

// Prepare an "Envelope"
env := gobl.NewEnvelope()
if err := env.Insert(inv); err != nil {
	panic(err)
}

CLI

This repo contains a gobl CLI tool which can be used to manipulate GOBL documents from the command line or shell scripts.

Build with:

mage -v build

Install with:

mage -v install

Build

Build expects a partial GOBL Envelope or Document, in either YAML or JSON as input. It'll automatically run the Calculate and Validate methods and output JSON data as either an envelope or document, according to the input source.

Example uses:

# Calculate and validate a YAML invoice
gobl build ./samples/invoice-es.yaml

# Output using indented formatting
gobl build -i ./samples/customer.yaml

# Set the supplier from an external file
gobl build -i ./samples/invoice-es.yaml \
    --set-file customer=./samples/customer.yaml

# Set arbitrary values from the command line. Inputs are parsed as YAML.
gobl build -i ./samples/invoice-es.yaml \
    --set meta.bar="a long string" \
    --set series="TESTING"

# Set the top-level object:
gobl build -i ./samples/invoice-es.yaml \
    --set-file .=./samples/envelope-invoice-es.yaml

# Insert a document into an envelope
gobl build -i --envelop ./samples/invoice-es.yaml

Correct

The GOBL CLI makes it easy to use the library and tax regime specific functionality that create a corrective document that reverts or amends a previous document. This is most useful for invoices and issuing refunds for example.

# Correct an invoice with a credit note (this will error for ES invoice!)
gobl correct -i ./samples/invoice-es.yaml --credit

# Specify tax regime specific details
gobl correct -i -d '{"credit":true,"changes":["line"],"method":"complete"}' \
    ./samples/invoice-es.yaml

Sign

GOBL encourages users to sign data embedded into envelopes using digital signatures. To get started, you'll need to have a JSON Web Key. Use the following commands to generate one:

# Generate a JSON Web Key and store in ~/.gobl/id_es256.jwk
gobl keygen

# Generate and output a JWK into a new file
gobl keygen ./samples/key.jwk

Use the key to sign documents:

# Add a signature to the envelope using our personal key
gobl sign -i ./samples/envelope-invoice-es.yaml

# Add a signature using a specific key
gobl sign -i --key ./samples/key.jwk ./samples/envelope-invoice-es.yaml

It is only possible to sign non-draft envelopes, so the CLI will automatically remove this flag during the signing process. This implies that the document must be completely valid before signing.

Development

GOBL uses the go generate command to automatically generate JSON schemas, definitions, and some Go code output. After any changes, be sure to run:

go generate .

gobl's Issues

MX: do not validate presence of extensions for foreign customers

• I'd like to be able to define a customer as a foreign entity and not have GOBL raise an error due to missing Mexican fields.
• The options here will need to be validated with the gobl.cfdi package.
• Mexico differentiates between local and foreign B2C customers (XAXX010101000 vs XEXX010101000), so it should still be possible to add a client with just the tax_id country.

Reverse charge scenario for IT

Add the reverse-charge scenario to Italy

Japan too ?

https://www.nta.go.jp/english/taxes/consumption_tax/pdf/2021/simplified_15.pdf

The docs are decent . Almost as good as the EU ones in English

cmd: build crash

• Running the gobl build command with no further parameters causes the process to crash and refuses to respond to CTRL-C. Only a kill -9 <pid> will get rid of the process.
• I'd have expected a help screen to show me what options to add.

Validation error type

Validation errors performed on the Envelope should be wrapped inside an ErrValidation response instead of just the raw message. See here: https://github.com/invopop/gobl/blob/main/envelope.go#L60-L71

Feature: support command line `--include` flag

• In build, provide a base file as a template for the GOBL document to be incorporated, as opposed to a "snippet".

The suggestion is to add a --include= flag that will parse the provided file (YAML / JSON) and use it as a base to add the provided document. Functionally, this is already supported using --set-file .=source.json, but this isn't as obvious.

cmd: missing whitespace around version

Running the gobl version command should probably have a \n at the end:

sam@dev-1 ~/workspace/invopop/gobl (main)$ ./gobl version
GOBL version gobl.org/v0.16.0sam@dev-1 ~/workspace/invopop/gobl (main)$

Multiple currencies in multiple items

At the moment, GOBL allows to specify the currency at item level, if the currency is different than the invoice's one. However, at the time of calculating totals, different lines with different currencies are summed together as if they had the same currency.

We need to review this behaviour as probably the exchange rates information (if present) should be used to calculate totals in the invoice's currency properly (or a validation error be returned if the exchange rates required to calculate the totals are missing)

Bug in exempt tax rate totals calculation

Given the following document:

$schema: "https://gobl.org/draft-0/bill/invoice"
uuid: "328f20c8-a0ac-11ee-bb1d-e6a7901137ed"
currency: "EUR"
issue_date: "2023-12-18"
series: "EXPORT-X"
code: "0002"

supplier:
  tax_id:
    country: "ES"
    code: "B98602642" # random
  name: "Provide One S.L."
  emails:
    - addr: "[email protected]"
  addresses:
    - num: "42"
      street: "San Frantzisko"
      locality: "Bilbo"
      region: "Bizkaia"
      code: "48003"
      country: "ES"

customer:
  tax_id:
    country: "NL"
  name: "Sample End-Consumer"
  identities:
    - key: "es-passport"
      code: "123456789"

lines:
  - quantity: 20
    item:
      name: "Development services"
      price: "90.00"
      unit: "h"
    discounts:
      - percent: "10%"
        reason: "Special discount"
    taxes:
      - cat: VAT
        ext:
          es-tbai-product: "services"
          es-tbai-exemption: "RL"

notes:
  - key: "general"
    text: "Some random description"

Unless rate: exempt is included in the line's taxes, the totals will not be calculated.

CLI build: support `-t` or `--type` parameter

To save user's from having to know the exact schema of a document to be inserted inside a GOBL envelope, a simple -t or --type parameter can be used to try and map the name to the GOBL type.

A simple implementation of this would expect the type provided to look like bill.Invoice (matching the Go name), convert it to snake-case with dashes and / instead of ., and try to lookup an existing schema.