# Dicionário do modelo de cadastro fiscal para varejo

**Versão:** 0.1, 02/10/2026. **Natureza:** modelo educacional da TaxUp; não é leiaute oficial, parecer ou arquivo pronto para importação em ERP.

O CSV foi desenhado para separar dado de origem, decisão tributária, trilha de evidência e homologação técnica. Nem todo campo será obrigatório em toda empresa. O leiaute final depende do ERP, das operações e do critério de aceite contratados.

## Identidade e qualidade do item

| Campo | Função | Observação |
|---|---|---|
| `id_registro_origem` | Preservar a chave da base recebida. | Nunca substituir silenciosamente; o de-para precisa voltar à origem. |
| `sku` | Código comercial ou operacional do item. | Não presume unicidade entre empresas, filiais ou sistemas. |
| `gtin` | Identificador comercial, quando existente e aplicável. | Ausência não prova duplicidade nem impede classificação. |
| `descricao_origem` | Guardar o texto exatamente recebido. | Necessário para auditoria e reconciliação. |
| `descricao_normalizada` | Descrição saneada, com atributos materiais. | Não apagar marca, unidade, composição, modelo ou dimensão quando diferenciarem o item. |
| `marca`, `modelo`, `unidade`, `embalagem`, `quantidade_embalagem` | Separar atributos escondidos na descrição. | Apoiam deduplicação; não bastam isoladamente. |
| `natureza_item` | Distinguir revenda, ativo, uso empresarial e outros grupos. | Não confundir “uso empresarial” com “uso ou consumo pessoal” do art. 57 da LC 214/2025. |
| `finalidade_uso` | Registrar a destinação operacional conhecida. | Pode exigir validação da área usuária. |

## Classificação e contexto da operação

| Campo | Função | Observação |
|---|---|---|
| `ncm_atual` | Registrar a classificação fiscal vigente na base. | Deve ser validada por atributos do produto e fonte adequada; não é sinônimo de tratamento IBS/CBS. |
| `fonte_ncm` | Identificar o lastro usado para a NCM. | Ex.: Classif, consulta formal, laudo ou outra fonte documentada. |
| `operacao` | Delimitar o fato operacional analisado. | Compra, venda, transferência, bonificação, devolução e baixa podem exigir regras distintas. |
| `contraparte_perfil` | Registrar o perfil relevante do fornecedor ou adquirente. | Não inserir dado pessoal desnecessário; usar categorias quando possível. |
| `canal` | Distinguir loja, e-commerce, marketplace e outros canais. | O canal pode alterar documento, fluxo e evidência, sem necessariamente alterar o produto. |
| `estabelecimento`, `uf_origem`, `uf_destino` | Preservar local e entidades da operação. | A granularidade deve seguir a decisão e o modelo de dados da empresa. |
| `cst_ibs_cbs` | Registrar a situação tributária da operação. | Não escolher apenas por prefixo ou por analogia textual. |
| `cclasstrib` | Registrar a classificação tributária aplicável à operação. | A mesma NCM pode aparecer com tratamentos distintos; o código deve manter contexto e vigência. |

## Evidência, versão e governança

| Campo | Função | Observação |
|---|---|---|
| `base_legal` | Identificar dispositivo ou ato pertinente. | Evitar referência genérica à “Reforma Tributária”. |
| `fonte_oficial_url` | Apontar para a fonte primária aberta. | URL precisa ser verificável e coerente com a conclusão. |
| `versao_tabela` | Registrar a versão do CST × cClassTrib ou de outro artefato técnico. | Tabelas mudam; valor sem versão perde auditabilidade. |
| `vigencia_inicio`, `vigencia_fim` | Delimitar o período de aplicação. | `vigencia_fim` pode ficar vazio quando realmente aberta. |
| `regra_id`, `familia_regra` | Ligar itens à regra homogênea aplicada em lote. | A regra deve expor critérios de inclusão e exclusão. |
| `nivel_confianca` | Separar aplicação determinística de caso ambíguo. | O critério deve ser definido antes do processamento, não ajustado para esconder exceções. |
| `motivo_excecao` | Explicar por que o item saiu do lote automático. | Ex.: descrição insuficiente, conflito de atributos, materialidade ou fonte inconclusiva. |
| `status_revisao` | Mostrar o estado real do item. | Nunca chamar item não revisado de homologado. |
| `responsavel_decisao` | Identificar quem aprovou a premissa tributária. | Pessoa ou função real; não confundir com quem digitou o código. |
| `responsavel_configuracao` | Identificar quem configurou o sistema. | Pode ser equipe interna, fornecedor ou integrador. |
| `data_revisao` | Registrar a data da decisão material. | Não renovar automaticamente a cada leitura do arquivo. |
| `evidencia` | Referenciar relatório, documento, amostra ou decisão preservada. | Não armazenar credencial ou dado sensível no CSV público. |

## ERP, teste e aceite

| Campo | Função | Observação |
|---|---|---|
| `erp_campo_destino` | Registrar onde a decisão deve chegar no sistema. | O nome varia por ERP e versão. |
| `teste_id` | Ligar a regra a um caso de homologação. | O teste precisa ter entrada, resultado esperado e evidência. |
| `resultado_teste` | Registrar o estado observado. | “Não executado” é diferente de aprovado. |
| `aceite` | Preservar a decisão do aprovador. | Aceite pode ter ressalva; não equivale a certificação legal permanente. |
| `observacoes` | Guardar informação residual relevante. | Não usar como depósito para atributos que merecem coluna estruturada. |

## Uso seguro

1. Conservar a base original e gerar uma cópia de trabalho.
2. Definir o que significa “item” antes de contar volume.
3. Tratar deduplicação, classificação e homologação como etapas diferentes.
4. Aplicar regra em lote apenas quando atributos e operação forem realmente homogêneos.
5. Reconciliar quantidade recebida, processada, excepcionada, revisada e aceita.
6. Adaptar o modelo ao ERP somente após confirmar campos, versões, ambiente e responsável pela carga.