A triagem de NF-e em XML no n8n deve receber o arquivo por um canal autorizado, verificar sua estrutura, identificar a empresa destinatária e registrar o documento uma única vez no ERP. O fluxo precisa distinguir nota, protocolo e evento fiscal. Converter XML para JSON é uma etapa técnica; isso não comprova autenticidade nem autoriza lançamento tributário.
Um desenho seguro mantém o XML original, trabalha com campos validados e envia dúvidas para revisão. A catalogação organiza documentos e relaciona itens a cadastros internos. A classificação fiscal e a escrituração seguem as regras e a responsabilidade da equipe contábil da empresa.
Resumo rápido
- Preserve XML original, origem e impressão digital do arquivo recebido.
- Valide estrutura e versão antes de mapear campos para o ERP.
- Use a chave de acesso como texto e proteja a gravação contra duplicidade.
- Trate cancelamento como evento vinculado, com retorno e histórico próprios.
- Classifique para revisão quando não houver regra aprovada de cadastro.
Defina o que a triagem pode decidir
O objetivo inicial deve ser estreito: receber documentos de entrada, identificar destinatário, fornecedor e itens e preparar registros para análise. Não misture esse fluxo com emissão de notas de serviço, pagamento de fornecedores ou apuração de impostos. Cada uma dessas operações tem regras e consequências próprias.
O Portal Nacional da NF-e reúne o Manual de Orientação ao Contribuinte e seus anexos. Use essa documentação e as atualizações aplicáveis como contrato técnico. Não derive o leiaute de um único arquivo recebido nem assuma que todos os XMLs fiscais têm a mesma estrutura.
Separe três resultados: documento catalogado, documento tecnicamente validado e lançamento aprovado. Uma nota pode estar catalogada enquanto aguarda confirmação de situação ou revisão do cadastro. Essa distinção evita que o usuário interprete “importação concluída” como autorização fiscal.
Para quem já faz conferência posterior com arquivos de escrituração, o guia de conciliação entre SPED e notas de entrada cobre outra etapa. Aqui a prioridade é construir uma entrada confiável no ERP, preservando identidade, origem e eventos desde o recebimento.
Receba e processe XML como entrada não confiável
Escolha canais autorizados: integração com provedor contratado, pasta de recebimento controlada ou anexos de uma caixa dedicada. Autenticar a origem ajuda, mas não elimina a validação do conteúdo. Um arquivo enviado pelo fornecedor errado ou destinado a outra filial precisa ser segregado.
Antes de interpretar o documento, limite o tamanho aceito e registre nome original, horário de chegada, canal e hash. O hash é uma impressão digital útil para identificar bytes iguais. Ele não demonstra que a nota é autêntica e não substitui a chave de acesso como identidade do documento fiscal.
Como recomendação de implementação, use um serviço de validação isolado, com biblioteca XML mantida, resolução de entidades externas desabilitada e sem acesso a arquivos locais ou rede durante o processamento. Recuse DTD e entradas fora dos limites definidos. Teste essas propriedades na biblioteca concreta; não presuma proteção porque o arquivo termina em .xml.
Não escreva uma expressão regular para substituir um analisador XML. Namespaces, atributos e elementos repetidos fazem parte da estrutura. Remover esses elementos indiscriminadamente pode transformar documentos diferentes em objetos aparentemente iguais, prejudicando validação e associação de itens.
O nó XML do n8n converte XML para JSON e JSON para XML. A documentação descreve uma conversão de formato. A implantação precisa acrescentar validação de schema, verificação fiscal e controles de segurança em componentes adequados, sem atribuir essas funções automaticamente ao nó.
Normalize campos sem perder informação
O Portal Nacional mantém uma área de esquemas XML oficiais. Selecione o conjunto aplicável à versão do documento e às notas técnicas pertinentes. Mantenha essa seleção versionada e monitore atualizações com a equipe responsável pelo sistema fiscal.
Armazene chave de acesso e identificadores como texto. Conversão para número pode perder precisão ou zeros relevantes. Para valores, use representação decimal definida no contrato da integração. Para datas e horários, preserve o valor original e normalize separadamente para consulta e exibição.
| Campo ou grupo | Tratamento sugerido | Quando interromper |
|---|---|---|
| Identidade do documento | Chave textual e referência ao original | Chaves incompatíveis entre partes do arquivo |
| Destinatário | Vínculo com cadastro da empresa | Empresa fora do escopo autorizado |
| Itens | Lista com identidade por documento e item | Estrutura inesperada ou cadastro ambíguo |
| Valores | Decimais e campos de origem preservados | Campo exigido ausente ou ilegível |
| Eventos | Registro separado ligado à chave | Evento sem retorno ou vínculo suficiente |
Inclua uma transformação explícita para itens: um documento com um item e outro com vários devem produzir sempre uma lista no modelo interno. Bibliotecas podem representar um elemento único como objeto e repetições como lista. Teste os dois casos antes de gravar no ERP.
Guarde o conteúdo original fora dos logs operacionais e conceda acesso por função. No log, prefira identificador do processamento, etapa, motivo da falha e referência ao arquivo protegido. Retenção e guarda fiscal devem ser definidas com os responsáveis; o histórico de execuções do n8n não deve ser o único arquivo da empresa.
Implemente idempotência e atualização por eventos
Idempotência significa poder repetir uma solicitação sem criar um segundo efeito equivalente. Para catalogação, imponha unicidade por empresa, ambiente e chave da NF-e, conforme o modelo de dados adotado. Produção e homologação devem permanecer separados para evitar registros de teste na operação real.
Faça a proteção no banco ou no serviço responsável pela escrita. Consultar antes de inserir não basta: duas execuções podem encontrar ausência ao mesmo tempo. Uma restrição de unicidade permite reconhecer a corrida e retornar o registro existente em vez de duplicar a entrada.
O hash tem outra função: dois arquivos idênticos podem ser tratados como reenvio simples. Se a chave é igual e o hash mudou, investigue a estrutura recebida e o contexto. Não sobrescreva o original sem histórico nem conclua automaticamente que o fornecedor corrigiu a nota.
O cancelamento da NF-e é tratado como evento na documentação oficial. Guarde pedido e retorno quando disponíveis e interprete a situação conforme o protocolo e as regras técnicas aplicáveis. Um texto no nome do arquivo, um e-mail ou uma solicitação isolada não comprovam registro do cancelamento.
Separe identidade da nota e identidade do evento. Um modelo de eventos deve incluir chave, tipo, sequência e evidência do retorno pertinente. Eventos recebidos antes do XML completo podem ficar pendentes de associação. Ao chegar a nota, o fluxo consulta o histórico antes de disponibilizar o documento para a operação.
Se o ERP não respondeu após uma tentativa de gravação, não repita cegamente. Consulte a referência externa que você enviou. Quando a API não oferecer mecanismo idempotente, use um serviço intermediário com controle transacional e reconciliação. A documentação do ERP deve orientar esse contrato.
Classifique itens e integre com o ERP
Comece com regras de cadastro aprovadas: fornecedor, código do produto usado por ele, unidade comercial, descrição e vínculo ao item interno. Uma correspondência precisa de revisão quando o fornecedor muda a unidade ou reutiliza um código para outra mercadoria. Similaridade de texto sozinha é insuficiente.
Separe categoria operacional e classificação fiscal. Sugerir “material de embalagem” para encaminhamento interno é diferente de decidir tratamento tributário. O fluxo pode sugerir um centro de custo ou cadastro, mas deve mostrar a regra aplicada e preservar os campos fiscais originais para avaliação da equipe.
Use o nó HTTP Request para falar com a API documentada do ERP ou com um serviço intermediário aprovado. Crie estados como aguardando cadastro, pronto para revisão e registrado. A resposta da integração deve conter o identificador do ERP, o resultado da operação e o vínculo ao processamento.
Se usar IA para sugerir correspondência de descrição, forneça somente os dados necessários e um catálogo limitado. A saída é uma sugestão estruturada com possibilidade de “sem correspondência”. Não permita que textos de observações fiscais se tornem instruções para alterar o fluxo ou autorizar operações.
A documentação do n8n sobre tratamento de erros ajuda a desenhar o caminho técnico de falha. Falta de cadastro, por outro lado, é uma pendência prevista do negócio. Encaminhe-a à equipe certa sem tratá-la como indisponibilidade da infraestrutura.
Exemplo: distribuidora de embalagens em Campinas
Imagine uma distribuidora fictícia em Campinas, São Paulo, que recebe XMLs de fornecedores em uma caixa dedicada. Este cenário é ilustrativo: não representa obrigação tributária específica nem resultado medido de implantação.
O n8n recebe um arquivo, grava o original e solicita validação ao serviço isolado. A empresa destinatária corresponde à filial cadastrada. O documento contém caixas e bobinas, mas o código da bobina ainda não tem vínculo com o cadastro interno. O fluxo cataloga a nota e abre pendência somente para esse item.
Um comprador revisa a unidade e associa o código ao produto correto. A decisão fica ligada à versão da regra e ao usuário responsável. Em outro documento, o mesmo nome comercial pode designar uma embalagem diferente; por isso a aprovação não vira uma regra genérica baseada apenas em palavras parecidas.
Mais tarde, o fornecedor reenvia o mesmo XML. O hash e a chave apontam para o registro existente. A integração acrescenta a ocorrência de recebimento ao histórico e devolve o identificador já criado. Nenhuma nova entrada financeira é aberta.
Em seguida chega um evento de cancelamento com evidência do retorno. O fluxo vincula o evento e encaminha o registro para revisão operacional e fiscal, especialmente se houve movimentação posterior no ERP. Atualizar a situação documental não significa apagar estoque, contas ou lançamentos sem análise.
Na homologação, a equipe repete esses casos e ainda simula timeout, nota de outra empresa e evento chegando antes da nota. Para estruturar o piloto, use o roteiro de testes antes de colocar uma automação com IA em produção. Observe o estado final no ERP, além do resultado exibido pelo n8n.
Erros comuns
Tratar XML bem formado como documento autorizado. Leitura técnica, validação estrutural e verificação de situação são verificações diferentes. Mostre ao usuário quais foram efetivamente executadas e quais estão pendentes.
Usar o nome do arquivo como chave. O fornecedor pode renomear o mesmo documento ou enviar nomes iguais para arquivos diferentes. Baseie o vínculo nos identificadores fiscais e preserve a origem como informação adicional.
Reprocessar tudo após uma falha parcial. Se parte dos itens já foi registrada, reiniciar sem controle pode duplicar efeitos. Mantenha checkpoints, referências externas e uma estratégia de reconciliação para descobrir o que o ERP efetivamente gravou.
Apagar uma nota cancelada. Preserve nota e eventos, com histórico da situação. Os ajustes posteriores nos processos da empresa devem seguir procedimentos aprovados. Excluir o original destrói evidência necessária para compreender o que aconteceu.
Transformar sugestão em decisão fiscal. Um modelo de linguagem pode produzir uma categoria plausível e ainda assim errada. Permissões restritas e revisão dos casos ambíguos devem fazer parte do processo. O guia de segurança e LGPD na implantação de IA complementa os cuidados com acesso e envio de documentos.
Perguntas frequentes
Preciso de IA para ler NF-e em XML?
Não. A estrutura deve ser processada por ferramentas determinísticas. IA pode auxiliar em tarefas delimitadas, como sugerir correspondência de descrições, com revisão. Ela não substitui schema, protocolos ou regras fiscais.
O nó XML do n8n verifica assinatura digital?
A documentação consultada apresenta conversão entre XML e JSON. Não atribua verificação de assinatura ao nó por esse motivo. Use componentes específicos e validados para as verificações necessárias ao seu processo.
Posso importar uma nota antes de concluir todos os cadastros?
Você pode catalogar o documento em estado pendente, se o ERP e a política interna permitirem. Deixe explícito que isso não equivale a lançamento aprovado e bloqueie operações que dependam da informação ausente.
Como tratar cancelamento recebido antes da nota?
Registre o evento em uma área pendente, com chave e evidências. Quando a nota chegar, associe o histórico e aplique a revisão prevista. Não descarte o evento apenas porque ainda falta o documento principal.
Quanto tempo devo guardar os arquivos?
Defina a política com a equipe fiscal e jurídica conforme as obrigações aplicáveis. Configure repositório, acesso e retenção de acordo com essa decisão. Não use a retenção padrão de logs como definição de guarda fiscal.
