Skip to content

feat: add versioned official domain catalogs #79

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vitormattos merged 1 commit into from
Oct 4, 2026
Merged

feat: add versioned official domain catalogs #79

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions REUSE.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,3 +26,11 @@ path = [
precedence = "override"
SPDX-FileCopyrightText = "Sistema Nacional NFS-e / Governo Federal"
SPDX-License-Identifier = "CC-BY-ND-3.0"

[[annotations]]
path = [
"resources/domains/*.tsv"
]
precedence = "override"
SPDX-FileCopyrightText = "Sistema Nacional NFS-e / Governo Federal"
SPDX-License-Identifier = "CC-BY-ND-3.0"
40 changes: 40 additions & 0 deletions resources/domains/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
<!--
SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
SPDX-License-Identifier: AGPL-3.0-or-later
-->

# Versioned NFS-e domain tables

These offline TSV snapshots normalize the production domain annexes currently listed by the
Sistema Nacional NFS-e portal. Runtime validation never scrapes the portal.

| Snapshot | Official source | Version | Mirror workbook Git blob |
| --- | --- | --- | --- |
| Municipalities / countries | https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual/anexo_a-municipio_ibge-paises_iso2-v1-00-snnfse-20251210.xlsx | ANEXO_A v1.00 (20251210) | `8fd9a9cf85e36352966ff7f9052b7136908fc431` |
| NBS / national service list | https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual/anexo_b-nbs2-lista_servico_nacional-snnfse-v1-01-20260122.xlsx | ANEXO_B v1.01 (20260122) | `a2eab7f0e2fa54a7f22bce0ad29b1b7b751f64d1` |
| IBS/CBS operation indicators | https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual/anexo-c-indop-ibscbs-snnfse-v1-01.xlsx | ANEXO_C v1.01 (20260122) | `d4eafbdf4d1d58f846999db290b12715e0cd33bb` |

The workbook mirror is the public `stackin-io/data-source` repository. The normalized TSVs
were cross-checked against the independently generated tables in
`rafael-negrao/nfse-nacional-service`.

## RTC correlation table

The Portal NFS-e currently describes **Anexo VIII v1.01.00** (Item de Serviço × NBS ×
`cClassTrib` × `cIndOp`) as an initial work in progress and explicitly states that no
business rules in Production or the RTC pilot are based on it.

For that reason this package does **not** reject fiscal data based on Anexo VIII. A future
advisory correlation helper may expose it for suggestions, but normative validation must wait
for the portal to make the correlation contract authoritative.

## Updating

When an official annex changes:

1. record the exact official workbook URL and published version;
2. retain the source workbook checksum/blob metadata used for extraction;
3. regenerate the corresponding TSV without inventing missing descriptions or codes;
4. update the version constant in `OfficialDomainCatalog`;
5. update cardinality and representative-code tests;
6. review downstream mapping changes explicitly instead of silently coercing old values.
28 changes: 28 additions & 0 deletions resources/domains/indicadores-operacao-ibscbs-v1.01.tsv
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Indicadores de operação IBS/CBS — ANEXO_C-INDOP_IBSCBS-SNNFSe-v1.01-20260122
# Formato: cIndOp<TAB>característica do fornecimento<TAB>local a identificar no DF-e
020101 Execução de operações com bem imóvel, bem imaterial, inclusive direito, relacionado a bem imóvel Localidade do imóvel (1)
020201 Execução de serviços sobre bem imóvel Localidade do imóvel (1)
020301 Execução dos serviços de administração e intermediação de bens imóveis Localidade do imóvel (1)
030101 Execução de serviços diversos exclusivamente prestados fisicamente sobre a pessoa ou integralmente fruídos presencialmente por pessoa física (2) Estabelecimento do fornecedor
030102 Execução de serviços diversos exclusivamente prestados fisicamente sobre a pessoa ou integralmente fruídos presencialmente por pessoa física (2) Endereço do adquirente
030103 Execução de serviços diversos exclusivamente prestados fisicamente sobre a pessoa ou integralmente fruídos presencialmente por pessoa física (2) Endereço do destinatário
030104 Execução de serviços diversos exclusivamente prestados fisicamente sobre a pessoa ou integralmente fruídos presencialmente por pessoa física (2) Endereço diverso do fornecedor, adquirente ou destinatário
040101 Execução de serviços de planejamento, organização e administração de feiras, exposições, congressos, espetáculos, exibições e congêneres Local do Evento
050101 Execução de serviços diversos fisicamente prestados sobre bem móvel material Estabelecimento do fornecedor
050102 Execução de serviços diversos fisicamente prestados sobre bem móvel material Endereço do adquirente
050103 Execução de serviços diversos fisicamente prestados sobre bem móvel material Endereço do destinatário
050104 Execução de serviços diversos fisicamente prestados sobre bem móvel material Endereço diverso do fornecedor, adquirente ou destinatário
050201 Execução de serviços portuários Local da prestação
060101 Execução de serviços de transporte de passageiros Local de início do transporte
070101 Execução de serviços de transporte de carga Endereço fornecido para entrega
070102 Execução de serviços de transporte de carga Local da retirada
080101 Execução de serviços de exploração de via Local da prestação, correspondente à extensão da via explorada e proporcional ao território dos entes tributantes
100101 Execução de operações de cessão de espaço para prestação de serviços publicitários Local do domicílio principal do adquirente (3)
100102 Execução de operações de cessão de espaço para prestação de serviços publicitários Local do domicílio do destinatário, nos casos de adquirente residente ou domiciliado no exterior (5)(6)
100201 Execução de operações de cessão de espaço para prestação de serviços publicitários Local do domicílio principal do destinatário (6)
100301 Execução dos demais serviços em operações não especificadas anteriormente ou, nos serviços de que trata o inc. III, estes sejam, ainda que parcialmente, prestados à distância (2) Local do domicílio principal do adquirente (3)
100302 Execução dos demais serviços em operações não especificadas anteriormente ou, nos serviços de que trata o inc. III, estes sejam, ainda que parcialmente, prestados à distância (2) Local do domicílio do destinatário, nos casos de adquirente residente ou domiciliado no exterior (5)(6)
100401 Execução dos demais serviços em operações não especificadas anteriormente ou, nos serviços de que tratam o inc. III, estes sejam, ainda que parcialmente, prestados à distância Local do domicílio principal do destinatário (6)
100501 Execução de demais operações não especificadas anteriormente com bens móveis imateriais, inclusive direitos Local do domicílio principal do adquirente (3)
100502 Execução de demais operações não especificadas anteriormente com bens móveis imateriais, inclusive direitos Local do domicílio do destinatário, nos casos de adquirente residente ou domiciliado no exterior (5)(6)
100601 Execução de demais operações não especificadas anteriormente com bens móveis imateriais, inclusive direitos Local do domicílio principal do destinatário (6)
Loading
Loading