Importação por XML — onboarding

Para que serve

Acelerar a entrada de dados no Manto ERP a partir de XMLs de NF-e/NFC-e que o cliente já possui (saídas e entradas anteriores). O sistema lê os XMLs, agrupa duplicados, valida e — após sua revisão — cria os cadastros mestres em massa.

Não confundir com NF-e de Entrada (Fiscal → NF-e de Entrada). Esse módulo é apenas extração de cadastros — não movimenta estoque/custo/financeiro/fiscal.

Quem pode usar

Por padrão, apenas o usuário Administrador do tenant. Se um consultor de implantação for fazer o onboarding, peça temporariamente a senha do admin ou use um usuário com perfil Administrador.

Tipos disponíveis

• Clientes — extraídos do <dest> de NF-e de saída (emitidas pelas filiais do tenant).
• Fornecedores — extraídos do <emit> de NF-e de entrada (recebidas pelas filiais do tenant).
• Produtos — extraídos do <det>/<prod> de NF-e de entrada ou saída. Match em cascata: EAN/GTIN → (CNPJ fornecedor + cProd) → (NCM + descrição normalizada). Cria Produto + ProdutoAliasXml para reuso em NF-e de Entrada operacional.
• Tributações — extraídas do <det>/<imposto> de qualquer XML válido. Agrupa combinações observadas (CFOP + CST + alíquota + tributo) e sugere FiscalPerfil + FiscalImposto inativos para revisão manual.

Como usar

1. Menu lateral → Onboarding → Importação por XML.
2. Clique em Nova importação.
3. Escolha o tipo (Clientes ou Fornecedores) e a filial padrão (a empresa dos cadastros importados).
4. Faça upload dos arquivos. Aceita .xml individuais ou .zip com vários XMLs. Limite: 5.000 XMLs ou 200 MB por upload.
5. Aguarde o processamento. O sistema:
   • Rejeita XMLs cujo CNPJ emitente/destinatário não pertence a nenhuma filial do tenant.
   • Agrupa XMLs com o mesmo documento (CNPJ ou CPF) numa única linha de preview.
   • Compara com cadastros já existentes e sugere CRIAR / ATUALIZAR / IGNORAR.
6. Tela de preview:
   • Selecione as linhas que quer importar (checkbox).
   • Edite linhas com lápis se quiser corrigir antes de importar.
   • Filtre por ação, UF, status, busca por documento/razão.
   • Remova linhas que não quer importar (lixeira) — não afeta cadastros já criados.
7. Clique em Confirmar (N) para criar/atualizar os cadastros.

O que acontece em cada ação

• Novo (CRIAR): cria um Cliente/Fornecedor/Produto com os dados do XML.
  • Cliente/Fornecedor: ainda cria um contato genérico "Importação XML" se houver e-mail ou telefone, e em PJ enriquece via consulta CNPJ (CNAEs, sócios, situação, IE, endereço, geocoding para clientes).
  • Produto: cria com nome=descrição, NCM, CEST, unidade. Não preenche preço/custo/perfil fiscal. Em paralelo cria um ProdutoAliasXml para que próximas NF-e de Entrada já reconheçam o produto pelo cProd ou EAN do fornecedor.
• Atualizar (ATUALIZAR): sobrescreve no cadastro existente apenas os campos que não estão vazios na linha (preserva dados curados).
• Ignorar (IGNORAR): dado idêntico ao já cadastrado — pré-marcado como desmarcado na seleção. Você pode forçar atualização clicando no lápis e mudando a ação.

Tributações — fluxo específico

Diferente dos outros tipos, Tributações mostra o preview em cards (não tabela). Cada card representa uma combinação tributária única observada nos XMLs:

• Cabeçalho: tipo de operação (VENDA/COMPRA), CFOP, NCM.
• Corpo: CST/alíquota de cada tributo (ICMS, IPI, PIS, COFINS), com badges para ICMS-ST e FCP quando presentes.
• Produtos exemplo: até 10 produtos que apresentaram esta combinação.
• Validações: avisos sobre dados faltantes ou divergentes.

Threshold de captura: combinações com menos de 3 ocorrências são descartadas como "amostras raras". Para ajustar, edite o THRESHOLD_OCORRENCIAS em apps/api-core/src/modules/importacao-xml/extratores/tributacoes.extrator.ts.

Confirmação de tributação:

• Cria 1 FiscalPerfil por tipo_operacao distinto, nomeado Importação XML #N (VENDA|COMPRA). O perfil entra com ativo=false.
• Dentro do perfil, cria 1 FiscalImposto por tributo presente na combinação (ICMS, ICMS_ST se houver, FCP se houver, IPI, PIS, COFINS). Todos com ativo=false.
• Não sobrescreve regras existentes — divergências de alíquota viram aviso e a linha vira CRIAR (cria nova entrada inativa para o usuário comparar).

Importante — IBS/CBS: a Reforma Tributária (NT 2025.002 / LC 214/2025) não vem em XMLs antigos. Os campos IBS/CBS dos cadastros ficam em branco — configure separadamente em Fiscal → Reforma Tributária.

Após importar: vá em Fiscal → Perfis Fiscais, encontre o perfil "Importação XML #...", revise as alíquotas/CSTs em FiscalImposto, e ative as entradas que quiser usar na emissão. Você pode mover entradas para outros perfis, ou copiar e excluir o perfil de importação após aproveitar o conteúdo.

Mesclagem manual (apenas Produtos)

Produtos podem aparecer "duplicados" no preview quando o cadastro vem por descrição (fallback) ou quando o mesmo produto teve EAN trocado entre fornecedores. Para resolver:

1. Selecione 2+ linhas no preview.
2. Clique em Mesclar (N).
3. Escolha qual linha é a sobrevivente (a que vai virar cadastro) e, para cada campo (descrição, NCM, CEST, unidade, origem), qual valor preservar.
4. Confirme — as N-1 linhas perdedoras ficam marcadas como consumidas (ocultas do preview), e seus XMLs de origem ficam acumulados na sobrevivente para o histórico.

Linhas já confirmadas (status IMPORTADO) não podem ser mescladas — o cadastro já existe; nesses casos use o módulo de Produtos diretamente.

XMLs rejeitados

Aparecem na aba Arquivos enviados com o motivo (ex.: "CNPJ emitente não pertence a nenhuma filial do tenant", "XML duplicado na sessão", "Erro ao processar XML"). Não bloqueiam os outros XMLs do mesmo lote.

Histórico

Aba Histórico lista todas as ações da sessão (upload, processamento, edições, confirmações, cancelamento) com usuário e timestamp. Append-only.

Limites

• 5.000 XMLs por sessão; 200 MB por upload; 2 MB por XML.
• 2.000 linhas por confirmação (subdividir se for maior).
• Sessão fica em staging por 30 dias após concluida_em (cleanup automático no futuro).

Roteiro de smoke test

1. Tenha pelo menos uma Filial com CNPJ válido cadastrada.
2. Pegue 3-5 XMLs reais de NF-e (entrada e/ou saída) emitidos para/por essa filial. Use também 1 XML de outra empresa como "controle" — esse deve ser rejeitado.
3. Cenário Clientes:
   • Crie sessão Clientes, suba os XMLs de saída (e o controle).
   • O controle aparece como REJEITADO em "Arquivos enviados".
   • Os destinatários únicos aparecem em "Preview".
   • Confirme alguns. Verifique em Cadastros → Clientes que os registros foram criados.
4. Cenário Fornecedores:
   • Crie sessão Fornecedores, suba os XMLs de entrada.
   • Os emitentes únicos aparecem em "Preview".
   • Confirme. Verifique em Cadastros → Fornecedores.
5. Re-importar o mesmo XML: deve ser rejeitado como "XML duplicado na sessão".
6. Cancelar uma sessão em andamento: muda status para CANCELADA, linhas ficam preservadas para auditoria.