O Configurador é o cérebro fiscal da plataforma. Em vez de digitar CFOP e CST item a item em cada nota — e correr o risco de errar —, você cadastra uma vez as regras da sua operação na forma de Cenários Tributários. Na hora de emitir, o Motor de Determinação Fiscal lê o contexto da operação (o que está sendo vendido, para quem, de onde para onde) e escolhe sozinho o cenário certo, preenchendo CFOP, CST e alíquotas.
É o equivalente a um "configurador de tributos" de um ERP de grande porte, porém com nomenclatura própria e integrado ao restante da Solution Makers (emissão de NF-e, exceções fiscais, SPED e a Reforma Tributária).
Cinco peças compõem o configurador. Entender cada uma facilita o resto do guia:
O coração do sistema. Um conjunto de filtros (quando se aplica) + os CFOPs e as regras de tributo (o que fazer). É o "perfil fiscal" da operação.
Dentro do cenário, uma linha por tributo (ICMS, PIS, COFINS…): define CST, alíquota, redução de base, MVA-ST, alíquota interestadual.
A tabela oficial de códigos de operação (entrada 1/2/3xxx, saída 5/6/7xxx). Já vem com ~110 CFOPs prontos; o cenário aponta para eles.
O "rótulo de negócio" da nota: VENDA, VENDA_ST, BONIFICACAO, DEVOLUCAO, EXPORTACAO… É um dos filtros do cenário.
Agrupa produtos com a mesma tributação (por NCM). Opcional, mas útil quando o tratamento muda por tipo de mercadoria.
Ajuste pontual que sobrescreve o cenário em casos específicos (um NCM, uma UF). Já existia na plataforma e é aplicada como camada por cima.
Você não escolhe o cenário num menu. O motor escolhe, seguindo três testes nesta ordem:
Cada filtro do cenário é uma lista. A regra é simples: lista vazia = serve para qualquer valor; lista preenchida = a nota precisa conter aquele valor. Os filtros são: Natureza, UF de origem, UF de destino, Perfil da contraparte, Regime da contraparte, Grupo tributário e NCM.
CFOP estadual (5xxx).CFOP interestadual (6xxx).CFOP exterior (7xxx).Um cenário só entra na disputa se a data da nota estiver dentro da sua vigência (início/fim, ambos opcionais). Isso permite cadastrar regras que mudam em uma data futura — essencial para a transição da Reforma Tributária.
| Cenário | Prioridade | Filtros | Resultado p/ "venda interna a contribuinte" |
|---|---|---|---|
| VENDA-ST-SP | 10 | natureza VENDA_ST · UF dest SP | Não casa (natureza é VENDA) |
| VENDA-INTERNA | 50 | natureza VENDA · UF org=dest | ✅ Vence → CFOP 5102 |
| VENDA-GERAL | 100 | natureza VENDA (sem UF) | Casaria, mas perde p/ o de prioridade 50 |
Do ponto de vista de quem emite, o trabalho é mínimo:
O cadastro do cliente define o perfil da contraparte (contribuinte / não-contribuinte / consumidor final / órgão público / exterior) e a UF de destino — entradas que o motor usa.
Ex.: Venda, Venda com ST, Bonificação, Devolução, Exportação. É o filtro de negócio principal.
Informe produto, quantidade e valor. O NCM ajuda o motor a refinar, mas é opcional. Não precisa digitar o CFOP.
O sistema chama o motor e preenche CFOP, CST e alíquotas de cada item, mostrando qual cenário foi aplicado e eventuais avisos.
Confira a prévia, ajuste se necessário e emita. O que você informar manualmente sempre prevalece sobre o motor.
# Pré-determina CFOP/CST/alíquotas dos itens (prévia para a tela) POST /api/erp/faturamento/determinar-itens { "clienteId":"…", "naturezaCodigo":"VENDA", "itens":[{ "ncm":"3402.20.00", "qtd":10, "valorUnit":25.0 }] } # Na emissão, itens sem CFOP são resolvidos pelo motor automaticamente POST /api/erp/faturamento/documentos
Quando o cliente não tem XMLs para importar, monta-se na mão. Em Cenários → + Novo cenário:
Código (ex. VENDA-INTERNA), nome legível e prioridade (lembre: específico = número menor).
Naturezas, UF origem, UF destino, perfil da contraparte, NCMs, grupos. Deixe vazio o que for "qualquer".
Estadual, interestadual e/ou exterior — o motor escolhe pela abrangência da nota.
Para cada tributo, informe CST, alíquota e, quando couber, redução de base, MVA-ST e alíquota interestadual.
Use a aba Simulador para validar antes de emitir: informe um caso real e veja CFOP, tributos e avisos.
O caminho mais rápido para quem já emite notas (no ERP atual ou em outro sistema). Em Cenários → 📥 Aprender de XMLs:
AUTO-<cfop>-<uf>-<cst>).Em Cenários → 📋 Modelos prontos há modelos pré-configurados que preenchem o formulário para você revisar (as alíquotas são sugestões — ajuste à sua UF e regime):
| Modelo | Uso típico |
|---|---|
| Venda dentro do estado | Venda a contribuinte na mesma UF — CFOP 5102 |
| Venda fora do estado | Venda interestadual a contribuinte — CFOP 6102 |
| Venda a não contribuinte | Interestadual com DIFAL — CFOP 6108 |
| Venda com ST | ICMS por substituição tributária — CFOP 5405/6404 |
| Bonificação / brinde | Remessa sem cobrança — CFOP 5910/6910 |
| Devolução de venda | CFOP 5202 / 1202 |
| Exportação | Saída não tributada — CFOP 7102 |
| Simples Nacional | Venda interna sob o regime |
| Serviço (ISS) | Prestação tributada pelo ISS |
Resumo dos tributos que o configurador trata na saída. Os CSTs abaixo são os mais comuns; consulte a legislação da sua UF/regime para os casos específicos.
Imposto estadual sobre circulação de mercadorias. O CST indica a situação: 00 tributado integralmente, 20 com redução de base, 40/41 isento/não tributado, 60 ICMS cobrado anteriormente por ST, 90 outras. A alíquota varia por UF e por operação.
O substituto recolhe antecipadamente o ICMS de toda a cadeia. Usa MVA (Margem de Valor Agregado) para presumir a base do varejo. CFOPs típicos: 5405/6404 (substituído) e 5401/6401 (substituto).
Diferencial de alíquota em vendas interestaduais a não contribuinte/consumidor final: recolhe-se a diferença entre a alíquota interna do destino e a interestadual. Relevante no e-commerce.
Imposto federal sobre produtos industrializados. Incide na saída do estabelecimento industrial (ou equiparado). Alíquota conforme a TIPI por NCM.
Contribuições federais. No regime não-cumulativo (lucro real) há crédito sobre insumos; no cumulativo (lucro presumido) não. CSTs de saída comuns: 01 tributável alíquota básica, 06 alíquota zero, 07 isenta, 49 outras saídas.
Imposto municipal sobre serviços — entra quando a natureza é prestação de serviço (NFS-e). Alíquota definida pelo município.
| Tributo | Esfera | Base no configurador |
|---|---|---|
| ICMS | Estadual | CST, alíquota, redução BC, alíq. interestadual |
| ICMS_ST | Estadual | CST, MVA, alíquota |
| ICMS_DIFAL | Estadual | alíquota interna destino × interestadual |
| IPI | Federal | CST, alíquota |
| PIS / COFINS | Federal | CST, alíquota |
| ISS | Municipal | alíquota |
A EC 132/2023 cria o IVA Dual, que substitui gradualmente os tributos atuais entre 2026 e 2033:
O configurador já reconhece CBS, IBS e IS como tributos nas regras de cenário. Como a transição é por data, use a vigência dos cenários para fazer o sistema trocar de regra sozinho no ano certo — cadastre o cenário "novo regime" com vigência iniciando na data prevista.
O outro lado do configurador: apurar quanto de imposto você tem a recuperar nas compras, e cruzar com o que tem a pagar nas vendas. Em Entradas / Crédito:
Notas de compra recebidas (tpNF = entrada). Clique em "Apurar (prévia)" para ver, ou "Apurar e registrar" para gravar.
ICMS por item (excluindo CSTs sem direito a crédito — 40/41/50/60), e IPI/PIS/COFINS destacados. Agrupa por período (AAAA-MM).
A tabela "Apuração / Compensação" cruza crédito (entradas) × débito (NF-e de saída autorizadas) por período e tributo.
Leitura do saldo, por tributo e período:
Nenhum cenário cobriu a combinação da nota. Crie um cenário que case com ela (ou um fallback genérico para a natureza), ou informe o CFOP no item manualmente.
Outro cenário com prioridade menor (número mais baixo) também casou e venceu. Revise as prioridades — o específico deve vir antes do genérico.
Use uma Exceção Fiscal filtrando pelo NCM; ela sobrescreve o cenário só naquele caso, sem duplicar cenários.
Rode o seed do configurador: npm run seed:fiscal:configurador. Ele popula ~110 CFOPs e as naturezas básicas.
Verifique o CST de ICMS dos itens — CSTs 40/41/50/60 não geram crédito. IPI/PIS/COFINS dependem de estarem destacados no XML.