Como consultar precatórios por CPF ou CNPJ em lote

Um escritório com carteira de precatórios enfrenta uma tarefa recorrente e chata: descobrir, entre centenas de clientes, quais tiveram movimentação relevante e quais entraram em um exercício orçamentário.

Feito documento a documento, isso é inviável. A API de precatórios resolve com uma chamada por lote: até 100 CPFs ou CNPJs de uma vez, com diagnóstico individual de cada documento.

A conta, antes do passo a passo#

Uma carteira de 500 clientes conferida manualmente no portal de cada tribunal são cerca de 40 horas de alguém qualificado, e precisa ser refeita a cada ciclo.

Pela API, são 5 chamadas de 100 documentos. A R$ 0,45 por página com as partes identificadas, isso dá R$ 2,25 para a carteira inteira; com incluir_partes=false, R$ 0,50. Os R$ 50 de crédito que vêm no cadastro cobrem essa varredura mais de vinte vezes.

1. Prepare a lista#

Reúna os documentos apenas com dígitos, sem pontuação. Remova duplicados: documento repetido no mesmo lote consome espaço do limite de 100 sem trazer nada novo.

Registre, ao lado de cada documento, o nome que você espera encontrar. Na conciliação, divergência entre o nome do seu cadastro e o nome publicado é sinal de homônimo ou de cadastro desatualizado, e precisa ser tratada antes de virar decisão.

Consulte apenas documentos relacionados à finalidade do seu trabalho. Uma carteira de clientes é uma finalidade legítima e delimitada; uma varredura ampla de documentos sem relação com a operação não é.

2. Monte a chamada#

O parâmetro é cpf_cnpj_partes, com os documentos separados por vírgula:

curl --get 'https://api.buscaprocessos.app.br/v1/precatorios' \
  --data-urlencode 'cpf_cnpj_partes=00000000000,00000000000000' \
  --data-urlencode 'incluir_requisicoes=true' \
  --data-urlencode 'limit=100' \
  --header "x-api-key: $BUSCAPROCESSOS_API_KEY" \
  --header 'Accept: application/json'

Em Python:

import os
import requests

lote = documentos[:100]

response = requests.get(
    "https://api.buscaprocessos.app.br/v1/precatorios",
    headers={"x-api-key": os.environ["BUSCAPROCESSOS_API_KEY"]},
    params={
        "cpf_cnpj_partes": ",".join(lote),
        "incluir_requisicoes": "true",
        "limit": 100,
    },
    timeout=60,
)
response.raise_for_status()
payload = response.json()

Mais de 100 documentos na mesma chamada devolve HTTP 400. Documento com dígito verificador inválido também.

3. Comece pequeno#

Antes da carteira inteira, rode cinco documentos com incluir_partes=false. Você conhece o formato da resposta gastando R$ 0,10 e confirma que os campos que o seu fluxo precisa estão de fato preenchidos para os seus casos.

Só então ligue incluir_partes, que vem como true por padrão e leva a consulta para R$ 0,45. A diferença de 4,5 vezes se justifica quando nome e documento da parte entram na decisão; numa varredura de triagem, muitas vezes não entram.

4. Leia o diagnóstico por documento#

Esta é a parte que a maioria das integrações ignora. Além dos itens encontrados, a resposta traz data.documentos_consultados, com o resultado de cada documento do lote.

Três desfechos são diferentes entre si:

Desfecho	Como tratar
Encontrado	Há registro vinculado ao documento no índice
Não encontrado	Nada foi localizado, com cobertura completa
NAO_ENCONTRADO_NO_INDICE_PARCIAL	Nada foi localizado, mas o índice ainda não está completo

O terceiro caso não é uma negativa. Enquanto meta.search.coverage.status não for COMPLETE, ausência de resultado significa ausência no índice disponível naquele instante. Se a sua tela mostrar "nenhum precatório encontrado" nos três casos, você vai transformar uma informação incompleta em uma conclusão, e alguém vai decidir com base nela.

5. Percorra a paginação#

paginator.total é exato dentro do índice no instante da chamada. Siga links.next até ele ser null.

Cada página concluída gera cobrança própria, informada em meta.creditsCharged. Um lote de 100 documentos cujos resultados cabem em uma página gera uma cobrança; se os resultados ocuparem três páginas, são três.

Se a resposta não couber na janela síncrona, a API devolve HTTP 202 com data.statusUrl e Retry-After. Consulte a URL de status com a mesma chave. Não repita a chamada original, ou você paga duas vezes pela mesma consulta.

6. Exporte e concilie#

Depois de rodar a consulta no Playground, exporte a resposta em XLSX. O arquivo chega dividido em abas:

• Resumo: indicadores, cobertura, filtros e alertas da consulta;
• Oportunidades: uma linha por item, com credor, ente devedor, natureza, ano orçamentário e valores;
• Pagamentos: status e evidências por requisição;
• Pendencias para aquisicao: o que falta conferir em cada caso;
• Requisicoes: uma linha por requisição, com identificadores e situação;
• Partes: nomes, papéis e documentos publicados, ligados ao CNJ;
• Consultas CPF-CNPJ: o desfecho de cada documento do lote;
• Metodologia: a semântica dos campos e os limites de interpretação.

Use o CNJ como chave de cruzamento com o seu cadastro. A aba Consultas CPF-CNPJ é a que fecha a conciliação: ela responde "o que aconteceu com cada documento que eu mandei", inclusive os que não retornaram nada.

Uma advertência sobre o que o lote não responde#

A consulta em lote é excelente para descobrir e priorizar. Ela não confirma pagamento individual, não identifica o beneficiário final e não emite alerta quando algo muda.

Para saber se um caso específico avançou, a consulta precisa ser repetida. E antes de qualquer decisão com efeito financeiro, vale o roteiro completo de due diligence de precatório.

A referência de todos os parâmetros e campos está no guia da API de precatórios.

Comece pelo seu próprio lote#

Pegue 20 clientes da sua carteira, rode uma chamada com incluir_partes=false e veja o que volta. Custa R$ 0,10 e responde, em um minuto, se a API cobre os seus casos, que é a única pergunta que importa antes de integrar.