API de processos judiciais no n8n com HTTP 202

Uma consulta processual nem sempre termina no momento em que o sistema recebe a requisição. Ao pesquisar um CPF ou CNPJ para uma rotina de cadastro empresarial, por exemplo, a API pode aceitar o pedido e informar que o resultado será preparado depois. É nesse cenário que entender como integrar API de processos judiciais no n8n com HTTP 202 evita um erro comum: tratar uma solicitação aceita como se ela já trouxesse o relatório final.

Este é um tutorial técnico para desenvolvedores e líderes de produto que precisam conectar uma API jurídica a um fluxo interno. A proposta não é presumir endpoints, campos ou cobertura. A implementação deve partir da documentação oficial vigente da API contratada e do objetivo de negócio que motivou a consulta.

O que o HTTP 202 informa, na prática

O status HTTP 202 significa que o servidor aceitou a solicitação para processamento, mas ainda não concluiu a tarefa. Diferentemente de uma resposta 200 com dados prontos, o 202 pede que a sua automação reconheça uma etapa intermediária.

Em uma integração processual, isso costuma ocorrer quando a pesquisa exige consolidação de informações antes da entrega. A resposta inicial pode trazer um identificador da solicitação, uma referência de consulta ou instruções para acompanhar o processamento. O formato exato depende da API.

O ponto central é simples: não grave uma resposta 202 como se ela fosse o resultado jurídico da pesquisa. Grave-a como uma solicitação pendente, com rastreabilidade suficiente para continuar o fluxo depois.

Antes do n8n: defina qual tarefa será integrada

"Consulta processual" pode significar operações muito diferentes. Misturá-las no mesmo fluxo torna a automação difícil de auditar e pode produzir resultados inadequados para a área solicitante.

A descoberta de novos processos por CPF ou CNPJ procura localizar ocorrências relacionadas a uma pessoa ou empresa. É uma tarefa comum em cadastros empresariais, análises de fornecedores e etapas de background check judicial, sempre com critérios internos claros e revisão humana.

O acompanhamento de um processo conhecido por número CNJ é outra operação. Aqui, o sistema já possui o identificador do caso e quer verificar movimentações, situação ou alterações disponíveis na fonte.

Já o acompanhamento de publicações por OAB atende à rotina de escritórios e profissionais que precisam organizar comunicações vinculadas à inscrição. Não é uma busca de processos por documento e não deve ser modelado como tal.

Defina uma dessas tarefas antes de criar o workflow. Para quem precisa operar consultas manualmente, um painel pode ser mais adequado. A API faz sentido quando os dados precisam entrar em um sistema próprio, um cadastro, uma esteira de análise ou uma base de acompanhamento.

Como estruturar a integração no n8n com HTTP 202

No n8n, o fluxo começa normalmente com um gatilho. Pode ser um Webhook recebido do sistema interno, um agendamento ou a leitura de itens em uma fila. Em seguida, um nó de validação confere se os dados de entrada atendem às regras do seu processo antes de chamar a API.

Uma entrada demonstrativa poderia conter um identificador interno e o documento empresarial a pesquisar:

json { "solicitacao_id": "cadastro-4821", "tipo_consulta": "descoberta_por_cnpj", "documento": "12345678000100" }

O nó HTTP Request deve ser configurado conforme a documentação da API: método, URL, autenticação, cabeçalhos e corpo da requisição. Não substitua os valores documentados por exemplos encontrados em outros provedores. Até nomes semelhantes, como request_id, job_id ou consulta_id, podem ter significados diferentes.

Depois da chamada, use uma condição para separar pelo código de status. Se a resposta for 200 e a documentação indicar retorno síncrono, o fluxo pode validar e persistir o resultado. Se for 202, siga para o tratamento assíncrono.

Registre o pedido pendente

Ao receber 202, persista pelo menos o identificador interno da solicitação, o identificador retornado pela API quando houver, a data da requisição, o tipo de pesquisa e o estado pendente. A persistência pode ser feita no banco de dados, CRM ou sistema de fila adotado pela empresa.

Esse registro resolve duas necessidades operacionais. A primeira é permitir que o resultado posterior seja associado ao cadastro correto. A segunda é impedir que uma falha pontual no n8n faça a equipe perder a referência do pedido enviado.

Evite usar somente o documento consultado como chave de controle. Uma empresa pode solicitar mais de uma busca para o mesmo CPF ou CNPJ em momentos distintos e com finalidades diferentes. Um identificador interno por solicitação facilita auditoria, reprocessamento e conferência.

Escolha entre consulta posterior e callback

APIs assíncronas costumam informar um de dois modelos: consulta posterior do status ou entrega de resultado por callback. A documentação define qual deles está disponível e como usá-lo.

No modelo de consulta posterior, o n8n espera um intervalo definido pela sua regra operacional e chama o endpoint de acompanhamento com o identificador retornado. O fluxo precisa prever estados como pendente, concluído, indisponível ou erro, conforme a especificação da API. Não faça tentativas em sequência sem intervalo: além de gerar chamadas desnecessárias, isso pode esbarrar em limites de uso.

No modelo de callback, crie um Webhook no n8n para receber a notificação do provedor. O endpoint deve aceitar apenas o método previsto, registrar o evento recebido e localizar a solicitação pendente pelo identificador de correlação. Se a API oferecer assinatura de mensagens, valide-a de acordo com a documentação antes de processar o conteúdo.

Em ambos os modelos, responda à comunicação recebida com o status esperado pelo provedor. Uma resposta incorreta pode levar a novas tentativas de entrega ou a um resultado marcado como não confirmado.

Valide o JSON antes de usar o resultado

Quando o retorno final chegar, o trabalho não termina no nó HTTP. Dados processuais podem conter campos ausentes, listas vazias, informações não disponíveis ou estruturas diferentes conforme a consulta. O workflow precisa validar o JSON antes de atualizar registros internos.

Separe a informação bruta recebida da informação transformada para uso no seu sistema. Armazenar o retorno original, quando permitido pela política da empresa e pela finalidade da operação, ajuda na rastreabilidade. Já a camada transformada pode conter apenas os campos necessários ao cadastro, à triagem ou ao acompanhamento.

Por exemplo, um sistema pode precisar apenas indicar que a consulta foi concluída e disponibilizar o resultado para análise autorizada. Não é necessário replicar todos os campos da resposta em áreas que não usam aquela informação. O princípio é reduzir circulação interna de dados e manter o contexto da consulta.

Também diferencie resultado vazio de ausência de informação. A inexistência de registros retornados em uma consulta não comprova que não existam pendências, processos em outras fontes ou ocorrências não alcançadas pela pesquisa. Da mesma forma, a existência de processo não comprova culpa, risco ou motivo automático para reprovação de uma pessoa ou empresa.

Tratamento de falhas e reprocessamento

Um fluxo utilizável precisa saber quando parar. Erros de autenticação, dados inválidos, indisponibilidade temporária e respostas inesperadas exigem tratamentos distintos.

Para falhas temporárias, estabeleça tentativas limitadas e intervalos progressivos, conforme as regras da API e a criticidade da operação. Para erros de validação, direcione a solicitação para revisão em vez de reenviá-la indefinidamente. Para uma resposta sem identificador de correlação ou com estrutura fora do esperado, registre o evento e acione o canal técnico responsável.

A deduplicação também merece atenção. Antes de criar uma nova consulta, verifique se já existe uma solicitação pendente com o mesmo contexto de negócio. Isso não significa bloquear toda nova busca sobre o mesmo documento. Significa evitar que a mesma ação seja disparada duas vezes por reenvio de formulário, falha de rede ou repetição de evento.

Um fluxo que a equipe consegue explicar

A melhor integração não é a que apenas retorna dados. É a que permite responder, com clareza, o que foi solicitado, quando a API aceitou o pedido, quando o resultado chegou, qual sistema recebeu a atualização e quem pode analisá-la.

No n8n, documente cada etapa com nomes objetivos: validar entrada, solicitar consulta, registrar pendência, receber resultado, validar retorno e atualizar cadastro. Isso reduz a dependência de quem montou o primeiro workflow e facilita ajustes quando a documentação da API mudar.

Antes de colocar a automação em produção, teste entradas válidas, documentos com formatação incorreta, respostas 202, resultados finais, callbacks repetidos e indisponibilidades. Depois, consulte a documentação oficial atual da API para confirmar autenticação, limites, campos, estados e formas de acompanhamento. Esse cuidado transforma o HTTP 202 de um aparente erro em parte previsível da operação.