Jurisdições fiscais

Uma Jurisdição fiscal é um local que cobra imposto — um país, um estado ou província, uma cidade. É a base de todo o motor de impostos, porque toda questão fiscal começa com “onde?”: onde está o vendedor, onde está o comprador e, portanto, quais impostos se aplicam. Acertando as jurisdições, as regras acima delas praticamente se escrevem sozinhas.

A parte inteligente — e o que é preciso entender antes de qualquer outra coisa — é que as jurisdições formam uma hierarquia. O Reino Unido contém Inglaterra, Escócia, País de Gales e Irlanda do Norte. O Brasil contém São Paulo, Rio de Janeiro e outros 25 estados. O motor usa essa estrutura de pai e filho para que uma regra definida uma única vez em nível de país se aplique automaticamente a todos os locais dentro dele.

A hierarquia — e a correspondência por ancestralidade

Cada jurisdição pode apontar para um pai. Registros de país não têm pai; um estado aponta para seu país; uma cidade aponta para seu estado. Isso produz uma árvore:

Ao avaliar uma transação, o motor não olha apenas a jurisdição exata — ele percorre a árvore para cima e reúne o local mais todos os seus ancestrais. Um cliente na Inglaterra produz o conjunto {GB-ENG, GB}. Uma regra então corresponde se sua jurisdição estiver em qualquer lugar desse conjunto. Assim:

• Uma regra direcionada a GB corresponde ao cliente da Inglaterra (porque GB é um ancestral).
• Uma regra direcionada a GB-ENG também corresponde (correspondência exata).
• Uma regra direcionada a GB-SCT não corresponde (a Escócia não está no conjunto).

Essa “correspondência por ancestralidade” é o motivo pelo qual uma regra em nível de país cobre uma nação inteira, ao mesmo tempo em que você ainda pode descer para uma regra em nível de estado quando um único estado difere (exatamente como funcionam as alíquotas de ICMS por estado no Brasil).

Os campos — com valores do Reino Unido e do Brasil

Uma jurisdição é um registro pequeno e deliberado. Aqui está cada campo, o que ele faz e um valor real dos pacotes de carga inicial fornecidos — um registro do Reino Unido (Inglaterra) ao lado de um registro do Brasil (São Paulo), ambos em nível de Estado/Província, para que você possa comparar itens equivalentes.

O Código é a chave — trate-o com cuidado

De todos esses campos, Código é o que mais importa. É a chave de correspondência do motor, a chave de upsert da carga inicial e um ID Externo — o que significa que é estável entre atualizações de sandbox e upgrades de pacote de um jeito que os IDs de registro do Salesforce não são. A convenção é rigorosa e é aplicada:

Como o motor usa as jurisdições

Ao contabilizar uma fatura, as jurisdições cumprem quatro funções. Você não configura nada disso — é o motor lendo seus registros — mas conhecer essas funções explica por que seus códigos e pais precisam estar corretos.

1 · Percorre a ancestralidade de ambas as partes

O motor carrega cada jurisdição uma vez e, para o vendedor e o comprador, monta o conjunto de local mais ancestrais. Vendedor em São Paulo → {BR-SP, BR} (o conjunto de origem). Comprador no Rio → {BR-RJ, BR} (o conjunto de destino).

2 · Faz a correspondência das regras com esses conjuntos

Uma Regra fiscal só é acionada se suas jurisdições de origem e destino estiverem nos conjuntos correspondentes (um campo em branco na regra significa “qualquer”). Esse é o mecanismo de ancestralidade em ação — uma regra BR corresponde tanto a SP quanto a RJ; uma regra BR-RJ corresponde apenas ao Rio.

3 · Deriva a operação fiscal a partir dos códigos

O motor compara os dois códigos para classificar a transação — inteiramente a partir do texto:

Essa operação derivada alimenta diretamente Operações Fiscais e decide, para o Brasil, se você está no conjunto de regras interestaduais (e, portanto, se o DIFAL se aplica).

4 · Controla o nexo fiscal

Antes de qualquer imposto ser cobrado, o motor verifica se sua entidade está registrada para coletar imposto na jurisdição do comprador — e aceita um registro em qualquer ancestral. Um único registro US-TX cobre um comprador em uma cidade do Texas; um registro GB cobre as quatro nações do Reino Unido. (Veja Registro Fiscal de Entidade.)

Dados reais: jurisdições do Reino Unido e do Brasil

Veja o que os pacotes de carga inicial realmente criam.

🇬🇧 Reino Unido — 5 registros

O VAT vale para todo o Reino Unido, então as quatro nações existem principalmente por completude e para os poucos casos que diferem (a Irlanda do Norte segue as regras de VAT da UE para mercadorias, sob o Windsor Framework). Todas as regras de VAT ficam em nível de GB.

🇧🇷 Brasil — 28 registros (uma amostra)

O Brasil precisa de todos os estados porque as alíquotas e adicionais de ICMS realmente diferem por estado — SP a 18%, RJ a 20% com um adicional de 2% para o fundo de combate à pobreza. A hierarquia permite que cada estado tenha suas próprias regras, enquanto os impostos federais compartilhados (IPI, PIS, COFINS) ficam em nível de BR.

Exemplo prático: por que São Paulo → Rio é “interestadual”

Um vendedor de São Paulo emite uma fatura para um cliente do Rio de Janeiro. Veja as jurisdições em ação:

Essa única mudança — a jurisdição do comprador — reformula todo o resultado fiscal. É por isso que acertar a Jurisdição fiscal em cada Conta de cliente é tão importante.

Proteções integradas

Quatro regras de validação mantêm os dados de jurisdição íntegros — porque o motor depende disso:

Configuração e manutenção

• Normalmente você não cria esses registros manualmente. O Assistente de carga inicial de impostos cria o conjunto completo de jurisdições de um país — primeiro os países, depois seus filhos — na ordem correta, para que os pais sempre existam antes dos registros que apontam para eles.
• Desative, não exclua. Desmarcar Is Active remove uma jurisdição da correspondência preservando o histórico em faturas anteriores. Excluir uma jurisdição da qual registros históricos dependem os deixaria órfãos.
• Adicione um nível apenas quando um imposto precisar dele. A carga inicial usa os níveis País e Estado/Província; Município, Distrito e Região existem para impostos municipais (o ISS do Brasil, distritos especiais dos EUA) — adicione-os quando uma regra realmente tiver como alvo esse nível.

O que vem a seguir

1. Tipos de impostos — os impostos que uma jurisdição cobra.
2. Regras fiscais — regras delimitadas a uma jurisdição.
3. Registro Fiscal de Entidade — registrar-se para coletar em uma jurisdição.
4. Assistente de carga inicial de impostos — carregar jurisdições automaticamente.

Perguntas frequentes