GuidesOneMux

Crie um fluxo de extração de dados recuperável no n8n

Projete um fluxo de extração no n8n que valide registros, tente novamente após falhas transitórias e encaminhe exceções para revisão humana sem gerar gravações duplicadas.

AI

Resumo · TL;DR

Um projeto prático para extrair registros estruturados no n8n, separar falhas transitórias de dados inválidos e recuperar o processamento com segurança após interrupções.

Principais pontos

  • Valide os campos extraídos antes de qualquer gravação no destino e encaminhe registros inválidos para revisão, em vez de repetir as tentativas.
  • Use tentativas limitadas para falhas transitórias, com registro persistente das tentativas e um caminho claro de escalonamento quando o limite for atingido.
  • Proteja as gravações no destino com um mecanismo atômico de idempotência e reconcilie resultados ambíguos antes de tentar novamente.
  • Use a aprovação de ferramentas do AI Agent do n8n para ações arriscadas iniciadas pelo agente; crie um caminho de revisão separado para corrigir dados extraídos.
Nesta página (8)

Comece com um contrato de recuperação

Para extração em produção no n8n, torne cada documento recuperável de forma independente: armazene sua identidade e seu estado de processamento, valide os campos extraídos antes de gravá-los, tente novamente apenas falhas que possam ser resolvidas e encaminhe os casos não resolvidos para uma pessoa. Um fluxo bem-sucedido não é apenas aquele que pode ser executado novamente; é aquele que pode ser executado novamente sem duplicar ou perder um registro silenciosamente.

O exemplo abaixo extrai dados de faturas e grava os registros aprovados em um sistema de destino. Trata-se de um projeto ilustrativo, não de um fluxo testado. As opções dos nós e as integrações variam conforme a versão do n8n e o destino; verifique-as no seu ambiente.

Pré-requisitos e estrutura do fluxo

Você precisa de uma instância do n8n, acesso a uma fonte de documentos e a um serviço de extração, um banco de dados persistente ou armazenamento de estado equivalente, um destino para os registros validados e um canal de revisão. Restrinja o acesso aos documentos de origem e às mensagens de revisão de acordo com sua sensibilidade.

Use esta sequência lógica:

  1. Acionar e registrar: Receba uma referência ao documento. Crie ou localize uma tarefa persistente usando um ID estável da fonte e a versão do documento.
  2. Extrair: Busque o documento e solicite campos estruturados ao extrator escolhido.
  3. Validar: Verifique os dados retornados em relação a um contrato explícito.
  4. Encaminhar: Envie registros válidos para o caminho de gravação e registros inválidos para uma fila de revisão.
  5. Gravar e reconciliar: Grave usando uma chave de idempotência estável e, em seguida, registre o ID do destino e o resultado.
  6. Recuperar: Um fluxo agendado separado identifica tarefas prontas para nova tentativa ou paradas além de um limite operacional.

Um ID de execução do gatilho é útil para rastreamento, mas não é uma identidade confiável do documento entre execuções. Prefira um ID de documento do sistema de origem combinado com uma versão ou um resumo do conteúdo. Defina como um documento corrigido recebe uma nova versão antes de ativar o reprocessamento automático.

Valide o registro extraído antes de gravar

Neste exemplo, exija invoice_id, currency e amount_minor. Represente valores em unidades monetárias menores, como centavos, para evitar arredondamento de ponto flutuante durante a validação. O contrato pressupõe que o extrator já converteu o valor de acordo com as regras da moeda; uma implementação real também deve verificar se a moeda é aceita e se qualquer conversão é adequada.

Coloque um nó Code após a extração. O JavaScript ilustrativo a seguir verifica cada item recebido e retorna um resultado que pode ser revisado, em vez de lançar um erro quando os dados são inválidos. Configure o nó para processar todos os itens recebidos e garanta que o JSON de cada item seja o registro extraído antes da execução desse nó.

return $input.all().map((item) => {
  const record = item.json;
  const errors = [];

  if (typeof record.invoice_id !== 'string' || !record.invoice_id.trim()) {
    errors.push('invoice_id must be a non-empty string');
  }
  if (typeof record.currency !== 'string' || !/^[A-Z]{3}$/.test(record.currency)) {
    errors.push('currency must be a three-letter uppercase code');
  }
  if (!Number.isSafeInteger(record.amount_minor) || record.amount_minor < 0) {
    errors.push('amount_minor must be a non-negative safe integer');
  }

  return {
    json: {
      record,
      validation: { valid: errors.length === 0, errors },
    },
  };
});

Em seguida, adicione um nó IF que verifique validation.valid. Preserve o ID da tarefa e a referência à fonte junto com essa saída, seja no próprio item ou por meio de uma consulta ao armazenamento de estado. A regex verifica o formato de um código de moeda, não se ele corresponde a uma moeda realmente aceita. Acrescente verificações de negócio, como correspondência do fornecedor e detecção de faturas duplicadas, antes da gravação.

Respostas malformadas que não possam ser analisadas como um item precisam de um caminho de erro próprio. Não suponha que o nó de validação receberá um registro utilizável após toda falha de extração. Armazene um diagnóstico seguro e encaminhe falhas persistentes de análise para revisão.

Defina regras de novas tentativas e escalonamento

Deixe explícitas as decisões sobre novas tentativas. A política a seguir é um ponto de partida, não uma garantia de que todos os serviços usem esses códigos de status da mesma forma.

FalhaAção inicialApós o limite ou a investigação
Tempo limite excedido, falha de conexão ou erro temporário do serviçoTente novamente com um intervalo limitado e variação aleatória. Respeite o intervalo de nova tentativa documentado, quando informado.Marque para investigação por um operador.
Limite de taxaAguarde conforme a orientação do serviço; reduza a concorrência, se necessário.Escalone se a tarefa não puder avançar dentro de sua janela de serviço.
Campo ausente ou falha na validação de negócioNão repita a mesma solicitação indefinidamente; encaminhe o registro e os erros para revisão.Valide novamente o registro corrigido antes de gravá-lo.
Erro de autenticação ou permissãoInterrompa as tentativas automáticas e alerte um operador.Retome após a correção das credenciais ou permissões.
Tempo limite excedido na gravação, com resultado desconhecidoVerifique o destino usando a chave estável da operação antes de outra gravação.Reconcilie manualmente se o resultado continuar desconhecido.

Por exemplo, permita até três tentativas totais de extração, com esperas de aproximadamente um e cinco minutos entre elas, além de variação aleatória. Registre de forma persistente o número de tentativas, a categoria do último erro, o próximo horário permitido e o desfecho final. Decida se um intervalo determinado pelo provedor tem precedência sobre as esperas desse exemplo. Evite combinar tentativas no nível do nó com tentativas agendadas sem contabilizar ambas: caso contrário, o número real de tentativas pode ultrapassar a política.

Use as configurações disponíveis de tratamento de erros e novas tentativas do n8n quando apropriado, mas não dependa apenas de um log de execução como fila. Um fluxo agendado de recuperação deve consultar o estado persistente das tarefas e reivindicar as tarefas elegíveis de forma atômica, para que dois workers não processem a mesma tarefa simultaneamente. Verifique as configurações exatas dos nós e o comportamento de bloqueio do banco de dados na sua implantação.

Torne as gravações seguras para recuperação

Antes da primeira gravação no destino, persista uma chave de operação estável derivada da identidade e da versão do documento de origem. Reutilize essa mesma chave em todas as novas tentativas. O destino deve garantir a unicidade ou respeitar uma chave de idempotência atomicamente; verificar se um registro existe e depois inseri-lo em uma operação separada deixa o processo vulnerável a workers concorrentes.

Se o destino não tiver esse recurso, use um armazenamento intermediário com uma restrição atômica de unicidade e um processo de reconciliação. Isso, por si só, não pode garantir efeitos exatamente uma vez em um sistema separado: uma gravação pode ser bem-sucedida nesse sistema enquanto seu processo perde a resposta. Nesse caso, consulte o destino por uma referência externa estável antes de tentar novamente ou encaminhe o caso a um operador se não for possível consultar o destino de forma confiável.

Acompanhe estados como received, extracting, review_required, ready_to_write, write_unknown e completed. Defina uma concessão ou prazo para o trabalho em andamento e faça com que a recuperação examine concessões expiradas. Armazene o ID do registro no destino somente após confirmar a gravação. Mantenha o histórico de tentativas e transições de estado para que um operador possa explicar o que aconteceu sem expor conteúdo desnecessário do documento nos logs.

Adicione revisão humana no ponto certo

Para uma saída de extração inválida, crie uma tarefa de revisão contendo a referência à fonte, os campos propostos, os erros de validação e o ID da tarefa. Ofereça uma forma autenticada de aprovar uma correção ou rejeitar a tarefa. Quando houver uma correção, registre quem fez a alteração e quando, execute novamente a validação e use o mesmo caminho de gravação protegido. Defina um responsável pelo escalonamento e um prazo para revisões não atendidas; não interprete o silêncio como aprovação.

Um recurso separado do n8n se aplica quando um AI Agent chama uma ferramenta. A documentação do n8n sobre human-in-the-loop informa que chamadas de ferramentas selecionadas podem ser pausadas para aprovação ou recusa, mostrando ao revisor a ferramenta e os parâmetros propostos. No painel Tools do Agent, adicione uma etapa de revisão humana, configure um canal compatível e conecte as ferramentas que exigem aprovação. A documentação também recomenda informar ao agente em seu system prompt quais ferramentas exigem aprovação e como lidar com uma recusa.

Essa aprovação de ferramenta não substitui a validação de esquema nem uma fila genérica de correção de registros. Uma ferramenta aprovada é executada com a entrada proposta pela IA; se um revisor precisar alterar os campos extraídos, use um caminho de correção e valide novamente antes de qualquer gravação.

Verificações operacionais antes do lançamento

  • Teste um campo ausente, uma resposta de extração malformada, um limite de taxa, uma credencial expirada e uma revisão recusada.
  • Simule uma gravação no destino que seja bem-sucedida, mas não retorne resposta; confirme que a recuperação reconcilia o resultado em vez de inserir novamente às cegas.
  • Confirme que workers de recuperação concorrentes não possam reivindicar a mesma tarefa e que os limites de tentativas incluam todas as camadas de novas tentativas.
  • Gere alertas para tarefas de revisão antigas, tentativas esgotadas, concessões expiradas e resultados de gravação desconhecidos. Verifique se um operador consegue localizar a fonte e retomar ou encerrar cada tarefa com segurança.

Comece com limites conservadores de tentativas e regras de revisão, depois ajuste-os usando as categorias de falha observadas. Mantenha os controles de validação e idempotência mesmo com a expansão da automação.

Fontes

Perguntas frequentes

Um fluxo no n8n deve tentar novamente um registro que falhou na validação de esquema?

Em geral, não com a mesma entrada e configuração. Encaminhe-o para revisão ou para um processo de correção definido e valide o registro corrigido antes de gravá-lo. Uma política de nova extração com limite próprio pode ser apropriada quando a causa for transitória.

A revisão humana do n8n valida automaticamente os dados extraídos?

Não. O recurso documentado de revisão de ferramentas do AI Agent pede que uma pessoa aprove ou recuse uma chamada de ferramenta proposta. A validação de esquema e qualquer processo de correção de registros precisam de um fluxo próprio.

Como um fluxo pode evitar gravações duplicadas após um tempo limite excedido?

Reutilize uma chave de operação estável e faça com que o destino a aplique de forma atômica. Se o resultado for desconhecido, reconcilie-o com o destino antes de tentar novamente; escale o caso quando não for possível determinar o resultado.

Artigos relacionados