GOBL ➡️ Brazil NFS-e

July 2, 2026 · View on GitHub

Brazil NFS-e (service invoice) addon for GOBL.

Released under the Apache 2.0 LICENSE, Copyright 2026 Invopop S.L..

Lint Test Go Go Report Card codecov GoDoc Latest Tag Ask DeepWiki

This module implements Brazil's NFS-e service invoicing documents as a GOBL tax addon:

  • NFS-e (br-nfse-v1) — Brazil's NFS-e 1.X service invoices.

Brazil's goods/consumer invoices (NF-e / NFC-e) live in a separate module, gobl.br.nfe.

Unlike the format converters in the GOBL ecosystem, this is a true addon: it registers extensions, normalizers, and validation rules into GOBL's global registry. It lives in its own module so that only projects handling Brazil NFS-e documents take on its weight.

Layout

  • addon/ — the GOBL addon: extensions, normalizers, and validation rules that register into GOBL on import. This package is kept dependency-light so importing it never pulls in conversion tooling.
  • the module root (and future subpackages) is reserved for converters and other Brazil NFS-e tooling that build on the addon.

Usage

Add a blank import of the addon so it registers itself, then use GOBL as normal:

import (
	"github.com/invopop/gobl"
	_ "github.com/invopop/gobl.br.nfse/addon"
)

Declare the addon on a document (or let the regime/scenario add it) and Calculate + Validate will run the full Brazil NFS-e normalization and rules.

Note: the br-nfse-v1 key is listed in GOBL core's approved external-addon registry, so it is recognised as a valid $addons value in the JSON Schema. The runtime check stays strict, however: a document declaring this addon will fail validation with add-on must be registered unless this module is imported. Any service that processes Brazil NFS-e documents must import it.

Development

The addon builds on core GOBL features (the regimes/br regime and the approved external-addon registry) that are not yet in a tagged release. The go.mod therefore pins github.com/invopop/gobl to a commit on the core extract-br-addons branch (a pseudo-version); bump it to the release tag once core is published.

go test ./...

Examples

examples/ holds sample documents with their expected JSON envelopes under examples/out/. They are verified via GOBL's shared pkg/examples helpers. Regenerate the golden output after intentional changes with:

go test . -run TestExamples -update

License

Apache 2.0 — see LICENSE.