Add initial Brazil NFSe addon

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to GOBL will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/). See also the [GOBL versions](https://docs.gobl.org/overview/versions) documentation site for more details.
 
+## [Unreleased]
+
+### Added
+
+- `br-nfse-v1`: added initial Brazil NFS-e addon
+
 ## [v0.203.0]
 
 ### Added

addons/addons.go

@@ -9,6 +9,7 @@ package addons
 
 import (
 	// Import all the addons to ensure they're ready to use.
+	_ "github.com/invopop/gobl/addons/br/nfse"
 	_ "github.com/invopop/gobl/addons/co/dian"
 	_ "github.com/invopop/gobl/addons/es/facturae"
 	_ "github.com/invopop/gobl/addons/es/tbai"

addons/br/nfse/extensions.go

@@ -0,0 +1,32 @@
+package nfse
+
+import (
+	"github.com/invopop/gobl/cbc"
+	"github.com/invopop/gobl/i18n"
+	"github.com/invopop/gobl/pkg/here"
+)
+
+// Brazilian extension keys required to issue NFS-e documents.
+const (
+	ExtKeyService = "br-nfse-service"
+)
+
+var extensions = []*cbc.KeyDefinition{
+	{
+		Key: ExtKeyService,
+		Name: i18n.String{
+			i18n.EN: "Service Code",
+			i18n.PT: "Código Item Lista Serviço",
+		},
+		Desc: i18n.String{
+			i18n.EN: here.Doc(`
+				The service code as defined by the municipality. Typically, one of the codes listed
+				in the Lei Complementar 116/2003, but municipalities can make their own changes.
+
+				For further details on the list of possible codes, see:
+
+				* https://www.planalto.gov.br/ccivil_03/leis/lcp/lcp116.htm
+			`),
+		},
+	},
+}

addons/br/nfse/invoices.go

@@ -0,0 +1,23 @@
+package nfse
+
+import (
+	"github.com/invopop/gobl/bill"
+	"github.com/invopop/validation"
+)
+
+func validateInvoice(inv *bill.Invoice) error {
+	if inv == nil {
+		return nil
+	}
+
+	return validation.ValidateStruct(inv,
+		validation.Field(&inv.Charges,
+			validation.Empty.Error("not supported by nfse"),
+			validation.Skip,
+		),
+		validation.Field(&inv.Discounts,
+			validation.Empty.Error("not supported by nfse"),
+			validation.Skip,
+		),
+	)
+}

addons/br/nfse/invoices_test.go

@@ -0,0 +1,64 @@
+package nfse_test
+
+import (
+	"testing"
+
+	"github.com/invopop/gobl/addons/br/nfse"
+	"github.com/invopop/gobl/bill"
+	"github.com/invopop/gobl/num"
+	"github.com/invopop/gobl/tax"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestInvoicesValidation(t *testing.T) {
+	tests := []struct {
+		name string
+		inv  *bill.Invoice
+		err  string
+	}{
+		{
+			name: "valid invoice",
+			inv:  &bill.Invoice{},
+		},
+		{
+			name: "nil invoice",
+			inv:  nil,
+		},
+		{
+			name: "charges present",
+			inv: &bill.Invoice{
+				Charges: []*bill.Charge{
+					{
+						Amount: num.MakeAmount(100, 2),
+					},
+				},
+			},
+			err: "charges: not supported by nfse.",
+		},
+		{
+			name: "discounts present",
+			inv: &bill.Invoice{
+				Discounts: []*bill.Discount{
+					{
+						Amount: num.MakeAmount(100, 2),
+					},
+				},
+			},
+			err: "discounts: not supported by nfse.",
+		},
+	}
+
+	addon := tax.AddonForKey(nfse.V1)
+	for _, ts := range tests {
+		t.Run(ts.name, func(t *testing.T) {
+			err := addon.Validator(ts.inv)
+			if ts.err == "" {
+				assert.NoError(t, err)
+			} else {
+				if assert.Error(t, err) {
+					assert.Contains(t, err.Error(), ts.err)
+				}
+			}
+		})
+	}
+}

addons/br/nfse/item.go

@@ -0,0 +1,20 @@
+package nfse
+
+import (
+	"github.com/invopop/gobl/org"
+	"github.com/invopop/gobl/tax"
+	"github.com/invopop/validation"
+)
+
+func validateItem(item *org.Item) error {
+	if item == nil {
+		return nil
+	}
+
+	return validation.ValidateStruct(item,
+		validation.Field(&item.Ext,
+			tax.ExtensionsRequires(ExtKeyService),
+			validation.Skip,
+		),
+	)
+}

addons/br/nfse/item_test.go

@@ -0,0 +1,66 @@
+package nfse_test
+
+import (
+	"testing"
+
+	"github.com/invopop/gobl/addons/br/nfse"
+	"github.com/invopop/gobl/org"
+	"github.com/invopop/gobl/tax"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestItemValidation(t *testing.T) {
+	tests := []struct {
+		name string
+		item *org.Item
+		err  string
+	}{
+		{
+			name: "valid item",
+			item: &org.Item{
+				Ext: tax.Extensions{
+					nfse.ExtKeyService: "12345678",
+				},
+			},
+		},
+		{
+			name: "nil item",
+			item: nil,
+		},
+		{
+			name: "missing extensions",
+			item: &org.Item{},
+			err:  "ext: (br-nfse-service: required.)",
+		},
+		{
+			name: "empty extensions",
+			item: &org.Item{
+				Ext: tax.Extensions{},
+			},
+			err: "ext: (br-nfse-service: required.)",
+		},
+		{
+			name: "missing extension",
+			item: &org.Item{
+				Ext: tax.Extensions{
+					"random": "12345678",
+				},
+			},
+			err: "ext: (br-nfse-service: required.).",
+		},
+	}
+
+	addon := tax.AddonForKey(nfse.V1)
+	for _, ts := range tests {
+		t.Run(ts.name, func(t *testing.T) {
+			err := addon.Validator(ts.item)
+			if ts.err == "" {
+				assert.NoError(t, err)
+			} else {
+				if assert.Error(t, err) {
+					assert.Contains(t, err.Error(), ts.err)
+				}
+			}
+		})
+	}
+}

addons/br/nfse/line.go

@@ -0,0 +1,17 @@
+package nfse
+
+import (
+	"github.com/invopop/gobl/bill"
+	"github.com/invopop/gobl/regimes/br"
+	"github.com/invopop/validation"
+)
+
+func validateLine(line *bill.Line) error {
+	if line == nil {
+		return nil
+	}
+
+	return validation.Validate(line,
+		bill.RequireLineTaxCategory(br.TaxCategoryISS),
+	)
+}

addons/br/nfse/line_test.go

@@ -0,0 +1,71 @@
+package nfse_test
+
+import (
+	"testing"
+
+	"github.com/invopop/gobl/addons/br/nfse"
+	"github.com/invopop/gobl/bill"
+	"github.com/invopop/gobl/regimes/br"
+	"github.com/invopop/gobl/tax"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestLineValidation(t *testing.T) {
+	tests := []struct {
+		name string
+		line *bill.Line
+		err  string
+	}{
+		{
+			name: "valid line",
+			line: &bill.Line{
+				Taxes: tax.Set{
+					{
+						Category: br.TaxCategoryISS,
+					},
+				},
+			},
+		},
+		{
+			name: "nil line",
+			line: nil,
+		},
+		{
+			name: "missing taxes",
+			line: &bill.Line{},
+			err:  "taxes: missing category ISS.",
+		},
+		{
+			name: "empty taxes",
+			line: &bill.Line{
+				Taxes: tax.Set{},
+			},
+			err: "taxes: missing category ISS.",
+		},
+		{
+			name: "missing ISS tax",
+			line: &bill.Line{
+				Taxes: tax.Set{
+					{
+						Category: br.TaxCategoryPIS,
+					},
+				},
+			},
+			err: "taxes: missing category ISS.",
+		},
+	}
+
+	addon := tax.AddonForKey(nfse.V1)
+	for _, ts := range tests {
+		t.Run(ts.name, func(t *testing.T) {
+			err := addon.Validator(ts.line)
+			if ts.err == "" {
+				assert.NoError(t, err)
+			} else {
+				if assert.Error(t, err) {
+					assert.Contains(t, err.Error(), ts.err)
+				}
+			}
+		})
+	}
+}

addons/br/nfse/nfse.go

@@ -0,0 +1,43 @@
+// Package nfse handles extensions and validation rules to issue NFS-e in
+// Brazil.
+package nfse
+
+import (
+	"github.com/invopop/gobl/bill"
+	"github.com/invopop/gobl/cbc"
+	"github.com/invopop/gobl/i18n"
+	"github.com/invopop/gobl/org"
+	"github.com/invopop/gobl/tax"
+)
+
+const (
+	// V1 identifies the NFS-e addon version
+	V1 cbc.Key = "br-nfse-v1"
+)
+
+func init() {
+	tax.RegisterAddonDef(newAddon())
+}
+
+func newAddon() *tax.AddonDef {
+	return &tax.AddonDef{
+		Key: V1,
+		Name: i18n.String{
+			i18n.EN: "Brazil NFS-e 1.X",
+		},
+		Extensions: extensions,
+		Validator:  validate,
+	}
+}
+
+func validate(doc any) error {
+	switch obj := doc.(type) {
+	case *bill.Invoice:
+		return validateInvoice(obj)
+	case *bill.Line:
+		return validateLine(obj)
+	case *org.Item:
+		return validateItem(obj)
+	}
+	return nil
+}

data/addons/br-nfse-v1.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://gobl.org/draft-0/tax/addon-def",
+  "key": "br-nfse-v1",
+  "name": {
+    "en": "Brazil NFS-e 1.X"
+  },
+  "extensions": [
+    {
+      "key": "br-nfse-service",
+      "name": {
+        "en": "Service Code",
+        "pt": "Código Item Lista Serviço"
+      },
+      "desc": {
+        "en": "The service code as defined by the municipality. Typically, one of the codes listed\nin the Lei Complementar 116/2003, but municipalities can make their own changes.\n\nFor further details on the list of possible codes, see:\n\n* https://www.planalto.gov.br/ccivil_03/leis/lcp/lcp116.htm"
+      }
+    }
+  ],
+  "scenarios": null,
+  "corrections": null
+}

data/schemas/bill/invoice.json

@@ -248,6 +248,10 @@
           "items": {
             "$ref": "https://gobl.org/draft-0/cbc/key",
             "oneOf": [
+              {
+                "const": "br-nfse-v1",
+                "title": "Brazil NFS-e 1.X"
+              },
               {
                 "const": "co-dian-v2",
                 "title": "Colombia DIAN UBL 2.X"