Bem-vindo ao Portal NCM

Novo Endpoint Unificado

O novo endpoint /api/buscar-ncm-completo/:ncm realiza busca integrada em ambos os bancos:

Fluxo de Busca

1. Verificação de Entrada: Valida NCM com 8 dígitos
2. Busca MySQL: Procura na tabela ncm
   • Critério: codigo_ncm = ?
   • Retorna: Dados de tributação base (ICMS, PIS, COFINS, IPI, etc.)
   • Se não encontrar: Marca como não encontrado mas continua
3. Busca Oracle: Procura na tabela FAT_REF_NCM_COD_TRIB
   • Critério: NCM BETWEEN NCM_INICIAL AND NCM_FINAL
   • Retorna: Todas as referências que cobrem este NCM
   • Dados incluem: Empresa, Revenda, Categoria, UF, Tributação Específica
4. Consolidação: Retorna objeto com dados de ambos os bancos

Resposta da API

{
  "ncm": "12345678",
  "busca": {
    "mysql": {
      "encontrado": true,
      "total": 3,
      "mensagem": "3 dados de tributação base encontrado(s)"
    },
    "oracle": {
      "encontrado": true,
      "total": 5,
      "mensagem": "5 referência(s) de tributação encontrada(s)"
    }
  },
  "mysql": [ /*dados base*/ ],
  "oracle": [ /*referências oracle*/ ],
  "status_geral": "ENCONTRADO"
}

Vantagens

Tabela FAT_REF_NCM_COD_TRIB

Esta é a tabela principal que armazena as referências de tributação por faixa de NCM.

Colunas Principais

Campo	Descrição	Exemplo
EMPRESA	Identificador da empresa (FK GER_EMPRESA)	1 (Scardua)
REVENDA	Código da revenda/filial	'01', '02'
NCM_INICIAL	NCM inicial da faixa coberta	12345600
NCM_FINAL	NCM final da faixa coberta	12345699
CATEGORIA	Categoria de cliente (FK GER_CATEGORIA_CLIENTE)	'01 - Consumidor'
TIPO_TRANSACAO	Tipo de movimento (venda, etc)	'2'
UF	Estado de destino (FK GER_UF)	'MG', 'SP'
PCT_PIS / PCT_COFINS	Percentual de impostos	2.30, 10.80
COD_TRIBUTACAO_ORI/DEST	Código fiscal origem/destino (FK GER_CODIGO_TRIBUTACAO)	'T001', 'T002'

Hierarquia de Busca

O que é Validação

A validação compara os padrões base (MySQL) com as referências criadas (Oracle) para verificar conformidade tributária.

Critérios de Validação

Status de Validação

✓ CORRETO	Referência Oracle conforme com padrão MySQL
⚠️ ALERTA	Pequenas discrepâncias encontradas
✗ ERRO	Referência não encontrada ou dados inconsistentes

Fluxo Detalhado

1. Busca todas as referências Oracle para o NCM
2. Para cada referência:
   • Valida se empresa/revenda existe
   • Busca padrão no MySQL com critérios: NCM + Categoria + Empresa + UF Origem + UF Destino
   • Se encontrar: Compara dados tributários
   • Se não encontrar: Registra como erro
3. Computa resumo: Total ✓, ⚠️, ✗ e percentual de conformidade

Estrutura MySQL

Tabela Principal: ncm

Armazena padrões base de tributação por NCM, categoria de cliente, empresa e estados.

codigo_ncm (PK)
├─ categoria_cliente
├─ empresa
├─ icms_dentro, icms_fora
├─ pis, cofins, ipi
├─ bc_pis_cof, bc_icms
├─ mva
├─ uf_emissor, uf_destino
├─ aliquota
├─ ativo
└─ data_modificado

Estrutura Oracle

Tabelas Relacionadas:

1. FAT_REF_NCM_COD_TRIB (Principal)

EMPRESA (FK GER_EMPRESA)
├─ REVENDA (FK GER_REVENDA)
├─ NCM_INICIAL, NCM_FINAL
├─ TIPO_TRANSACAO (FK FAT_TIPO_TRANSACAO)
├─ CATEGORIA (FK GER_CATEGORIA_CLIENTE)
├─ UF (FK GER_UF)
├─ COD_TRIBUTACAO_ORI (FK GER_CODIGO_TRIBUTACAO)
├─ COD_TRIBUTACAO_DEST (FK GER_CODIGO_TRIBUTACAO)
├─ CODFISCAL_OPERACAO (FK FAT_CODFISCAL_OPERACAO)
├─ PCT_PIS, PCT_COFINS
├─ PCT_MARGEM_LUCRO_NCM
├─ SITUACAO (FK VEI_SITUACAO)
└─ (outros campos de base e benefício fiscal)

2. Tabelas de Suporte

• GER_EMPRESA: Empresas do grupo
• GER_REVENDA: Revendas/filiais com UF
• GER_CATEGORIA_CLIENTE: Categorias de clientes
• GER_UF: Estados brasileiros
• GER_CODIGO_TRIBUTACAO: Códigos de tributação
• FAT_TIPO_TRANSACAO: Tipos de movimento
• FAT_CODFISCAL_OPERACAO: CFOPs (Código Fiscal Operação)
• VEI_SITUACAO: Status de validação

Mapeamento Empresa

MySQL	Oracle
Comercial Scardua	1
Tração Fort	2
Porto Livre	3

Funcionalidade Principal

A aba "Referências" permite buscar faixas de NCM criadas no Oracle que ainda não possuem cadastro na base MySQL.

Como Usar

1. Selecionar Empresa (obrigatório): Escolha entre Comercial Scardua, Tração Fort ou Porto Livre
2. Revenda (opcional): Filtrar por uma revenda específica
3. Categoria do Cliente (opcional): Selecione uma categoria se quiser refinar a busca
4. Operação (opcional): Filtrar por tipo de transação (P21, V21, etc)
5. Clique em "Buscar NCM sem Cadastro" para executar a busca

Resultado da Busca

A tabela retorna faixas/ranges de NCM (não NCMs individuais), mostrando:

• Range NCM: Faixa de NCM inicial até final (ex: 27100001 a 27109900)
• Inicial/Final: Números que delimitam a faixa
• Qtd. NCMs: Quantidade total de NCMs nessa faixa
• Empresa/Revenda/Categoria: Informações do filtro
• Status:
  • 🟢 Com Cadastro: Pelo menos um NCM da faixa existe no MySQL
  • 🔴 Sem Cadastro: Nenhum NCM da faixa foi encontrado no MySQL

📥 Exportar Resultados

O botão "Exportar Sem Cadastro" aparece quando há faixas sem cadastro encontradas. Clique para baixar um arquivo CSV com:

• Todas as faixas que NÃO têm cadastro no MySQL
• Informações completas (empresa, revenda, categoria, operação, UF)
• Arquivo nomeado com timestamp: ncm-ranges-sem-cadastro-2026-03-16T14-35-20.csv

Fluxo de Dados

1. QUERY ORACLE (FAT_REF_NCM_COD_TRIB)
   ↓ Obtém faixas de NCM com filtros aplicados
   └─ Retorna: range(inicial, final), empresa, revenda, categoria, etc

2. QUERY MYSQL (tabela ncm)
   ↓ Busca todos os códigos registrados para a empresa
   └─ Retorna: lista de NCMs cadastrados

3. COMPARAÇÃO
   ↓ Verifica se pelo menos 1 NCM de cada range existe no MySQL
   ↓ Marca como: COM_CADASTRO (existe) ou SEM_CADASTRO (não existe)
   └─ Retorna: lista completa de ranges com status

4. APRESENTAÇÃO E EXPORTAÇÃO
   ↓ Exibe ranges em tabela interativa
   └─ Permite exportar ranges sem cadastro em CSV

Exemplo de Resposta

{
  "erro": false,
  "mensagem": "Encontrados 1 range(s) COM cadastro e 0 SEM cadastro",
  "filtros": {
    "empresa": "1",
    "revenda": "1",
    "categoria": "20",
    "operacao": "P21"
  },
  "total": 1,
  "com_cadastro": 1,
  "sem_cadastro": 0,
  "total_ncms": 9900,
  "resultado_ncm": [
    {
      "ncm_range": "27100001 a 27109900",
      "ncm_inicial": "27100001",
      "ncm_final": "27109900",
      "quantidade_ncm": 9900,
      "empresa": 1,
      "revenda": 1,
      "categoria": "20 - Grupo Scardua",
      "tipo_transacao": "P21",
      "uf": "MG",
      "status": "COM_CADASTRO",
      "amostra_encontrada": "27100001"
    }
  ]
}

⚠️ Observações Importantes