Como atualizar múltiplos processos de uma vez usando a API do Escavador

O fluxo é simples

Basicamente, o processo funciona em três etapas:

1. Você envia o lote — uma única chamada POST com a lista de processos.
2. O Escavador processa — cada processo é enfileirado e consultado nos Tribunais de forma assíncrona.
3. Você consulta o resultado — a qualquer momento, você verifica o progresso usando o ID do lote que recebeu na etapa 1.

Sobre a cobrança: ela é feita individualmente por processo, com a mesma tarifa da atualização unitária. Se você enviar o mesmo número CNJ mais de uma vez no lote, o sistema descarta automaticamente as duplicatas — você paga apenas uma vez por processo.

Antes de começar

Para usar essa funcionalidade você vai precisar de:

• Uma conta ativa na API Paga do Escavador com créditos suficientes.
• Um Bearer Token válido para autenticar suas requisições.
• Caso queira receber notificações quando cada processo for concluído (enviar_callback), a URL de webhook precisa estar configurada no seu painel da API.
• Caso queira baixar os autos completos dos processos, você precisa fornecer credenciais de acesso ao tribunal — pode ser um usuário e senha, ou um certificado digital cadastrado na sua conta.

Passo 1 — Enviando o lote

Faça uma chamada POST para:

POST https://api.escavador.com.br/api/v2/processos/lote/solicitar-atualizacao

No corpo da requisição, você passa a lista de processos e as opções que quiser. O único campo obrigatório dentro de cada processo é o numero_cnj:

{
  "processos": [
    { "numero_cnj": "0802517-35.2019.8.23.0010" },
    { "numero_cnj": "3001263-93.2016.8.06.0072" },
    { "numero_cnj": "1030006-97.2015.8.26.0114" }
  ],
  "enviar_callback": true
}

Opções disponíveis

Além da lista de processos, você pode configurar o comportamento do lote com estes parâmetros:

O que você recebe de volta

Assim que o lote é criado, a API responde imediatamente — sem esperar o processamento terminar. A resposta traz o ID do lote e um resumo inicial com todos os processos ainda no status pendente:

{
  "id": 56,
  "status_geral": "PENDENTE",
  "criado_em": "2026-02-10T14:22:25+00:00",
  "total": 3,
  "pendente": 3,
  "sucesso": 0,
  "nao_encontrado": 0,
  "erro": 0,
  "processos": {
    "pendente": [
      { "numero_cnj": "3001263-93.2016.8.06.0072" },
      { "numero_cnj": "1030006-97.2015.8.26.0114" }
    ],
    "sucesso": [],
    "nao_encontrado": [],
    "erro": []
  }
}

Importante: guarde o campo id — você vai precisar dele para acompanhar o progresso do lote.

Passo 2 — Acompanhando o progresso

Para saber como está o seu lote, faça uma chamada GET passando o ID recebido:

GET https://api.escavador.com.br/api/v2/processos/lote/{id}/status

Você vai receber o mesmo formato da resposta anterior, agora com os contadores e listas atualizados conforme os processos vão sendo concluídos. Quando status_geral aparecer como FINALIZADO, significa que todos os processos terminaram — com sucesso ou com erro:

{
  "id": 56,
  "status_geral": "FINALIZADO",
  "criado_em": "2026-02-10T14:22:25+00:00",
  "total": 3,
  "pendente": 0,
  "sucesso": 2,
  "nao_encontrado": 0,
  "erro": 1,
  "processos": {
    "pendente": [],
    "sucesso": [
      { "numero_cnj": "3001263-93.2016.8.06.0072" },
      { "numero_cnj": "1030006-97.2015.8.26.0114" }
    ],
    "nao_encontrado": [],
    "erro": [
      {
        "numero_cnj": "0802517-35.2019.8.23.0010",
        "motivo": "LOGIN_INVALIDO"
      }
    ]
  }
}

Os processos que terminarem em sucesso já têm dados atualizados e podem ser consultados normalmente pelo endpoint de capa:

GET https://api.escavador.com.br/api/v2/processos/numero_cnj/{numero}

O que significa cada status

Status geral do lote (status_geral):

Status por processo:

E se eu não guardei o ID?

Sem problema. Você pode consultar o lote mais recente da sua conta sem precisar do ID:

GET https://api.escavador.com.br/api/v2/processos/lote/status

A estrutura de resposta é exatamente a mesma.

Consultando as informações após a atualização

Vale reforçar um ponto importante: a atualização em lote não retorna os dados dos processos diretamente. Ela apenas dispara a atualização nos Tribunais e informa o status de cada processo (sucesso, erro, etc.).

Para acessar as informações atualizadas — movimentações, partes, andamentos — você precisa consultar cada processo individualmente, usando o endpoint espcífico:

GET https://api.escavador.com.br/api/v2/processos/numero_cnj/{NUMERO_CNJ}

O fluxo completo, portanto, fica assim: você usa o lote para atualizar tudo de uma vez, aguarda o status_geral chegar em FINALIZADO e, em seguida, percorre a lista de processos com sucesso fazendo uma chamada individual para cada um.

Erros que podem acontecer

Número CNJ fora do padrão

Se algum processo da lista tiver um número inválido, o lote inteiro é rejeitado antes mesmo de ser criado. A resposta indica exatamente qual item está com problema:

{
  "code": "UNPROCESSABLE_ENTITY",
  "message": "Não foi possível processar a solicitação",
  "errors": {
    "processos.0.numero_cnj": [
      "O número '0802517-35.2019.0.23.1111' não está no formato CNJ."
    ]
  }
}

Verifique se todos os números seguem o formato NNNNNNN-NN.NNNN.N.NN.NNNN e tente novamente.

Processo já está sendo atualizado

Quando algum processo da lista já tem uma atualização recente ou em andamento, a API não cria o lote e retorna os detalhes de cada processo bloqueado:

{
  "code": "UNPROCESSABLE_ENTITY",
  "message": "Não foi possível processar a solicitação",
  "errors": {
    "0802517-35.2019.8.23.0010": {
      "message": "Esse processo já está sendo atualizado.",
      "appends": {
        "ultima_verificacao": {
          "id": 519,
          "status": "NA_FILA",
          "criado_em": "2026-02-10T16:01:05+00:00",
          "numero_cnj": "0802517-35.2019.8.23.0010",
          "concluido_em": null
        }
      }
    }
  }
}

Nesse caso, você tem duas saídas: retirar o processo da lista, ou reenviar o lote com "ignorar_atualizados": true. Com essa opção, o sistema simplesmente pula os processos que já estão atualizados e processa apenas os demais — o lote só falha mesmo se nenhum processo puder ser criado.

Pedir autos e documentos_publicos ao mesmo tempo

Essas duas opções são exclusivas. Escolha apenas uma delas por lote.

Pedir autos sem fornecer credenciais

Para baixar autos, o tribunal precisa autenticar sua identidade. Você precisa passar "utilizar_certificado": true (caso tenha um certificado cadastrado) ou os campos usuario e senha com as credenciais do tribunal.

Usar enviar_callback sem webhook configurado

Se você ativar o callback mas não tiver uma URL de webhook cadastrada no painel da API, a requisição será recusada. Configure a URL antes de usar essa opção.

Dicas para usar melhor

• Polling com moderação: como o processamento é assíncrono, consulte o status do lote a cada 5 minutos. Intervalos muito curtos não aceleram o processamento e sobrecarregam sua integração desnecessariamente.
• Prefira o webhook: se puder, use enviar_callback: true em vez de ficar consultando o status manualmente. Você receberá uma notificação assim que cada processo for concluído, sem precisar fazer nenhuma chamada extra.
• Lotes grandes: o limite é de 500 processos por lote. Para volumes maiores, divida a lista em vários lotes e acompanhe cada um pelo seu respectivo ID.
• Listas mistas: se sua lista pode conter processos que já foram atualizados recentemente, envie com ignorar_atualizados: true para evitar que o lote seja rejeitado por causa deles.