API de precatórios: o que ela entrega, quem usa e como integrar

Quem trabalha com precatórios em escala esbarra sempre no mesmo problema: a informação existe, mas está espalhada. O valor está no orçamento, a natureza do crédito está numa decisão, a posição na fila está numa lista de priorização e a cessão anterior está numa movimentação que ninguém leu.

A API de precatórios do BuscaProcessos responde a isso com um endpoint único. GET /v1/precatorios devolve um acervo pesquisável em JSON, com os campos jurídicos que sustentam uma decisão, e com a evidência textual de onde cada sinal veio.

Antes de continuar: o que isso custa hoje#

Conferir um precatório à mão (abrir o processo, ler as movimentações, localizar a natureza do crédito, procurar cessão anterior) leva de 15 a 30 minutos por caso, feito por alguém que sabe o que está lendo. Numa carteira de 300 precatórios, é um mês de trabalho de uma pessoa, e o resultado envelhece assim que termina.

A mesma varredura pela API é uma chamada por lote de 100 documentos, a R$ 0,45, ou R$ 0,10 se você não precisa das partes identificadas naquela passada.

O que a API entrega de fato#

Uma chamada devolve itens que combinam, quando há vínculo seguro:

• processos e requisições individuais da base processual oficial;
• registros orçamentários oficiais do exercício, quando vinculados;
• partes e documentos que o tribunal publicou sem máscara;
• natureza do crédito, preferência, datas, último movimento e situação;
• ordem cronológica e saldo individual, quando a fonte individual responde;
• sinais jurídicos de bloqueio, cessão, penhora, habilitação, impugnação e trânsito em julgado, cada um com o trecho que o originou.

O ponto que diferencia esse retorno de uma busca textual é a rastreabilidade. Cada classificação vem acompanhada de fonte_natureza, consultado_em e evidencia. Você consegue auditar como e quando aquele rótulo foi obtido, em vez de aceitar um campo sem procedência.

Quem usa, e para quê#

Fundos e compradores de precatório#

É o uso de maior valor. Antes de uma cessão, a pergunta não é "existe o precatório?", e sim "esse crédito é alimentar ou comum, tem superpreferência reconhecida, em que posição da fila está, e há alguma cessão, penhora ou bloqueio anterior registrado?".

A API devolve natureza_credito, preferencia, fundamento_preferencia, posicao_ordem_cronologica, eventos_juridicos e uma classificação risco_cessao com os fatores que a motivaram. O roteiro completo está em due diligence de precatório antes de comprar.

Escritórios com carteira de precatórios#

Conciliação em lote. Um escritório com centenas de clientes aguardando pagamento precisa saber quais tiveram movimentação relevante e quais entraram em um exercício orçamentário. cpf_cnpj_partes aceita 100 documentos por chamada e devolve o diagnóstico de cada um. O passo a passo está em como consultar precatórios por CPF ou CNPJ em lote.

Legaltechs, fintechs e times de produto#

Quem constrói produto precisa de JSON estável, paginação previsível, erro estruturado e preço por chamada. A API entrega os quatro, e o plano inicial dá R$ 50 em créditos para avaliar sem cartão e sem falar com vendas. Se você já integrou outros endpoints, o caminho é o mesmo descrito em integrar a API de processos com Python e Node.js.

A primeira chamada#

Guarde a chave numa variável de ambiente do servidor. Não a coloque em JavaScript entregue ao navegador, em repositório ou em log.

curl --get 'https://api.buscaprocessos.app.br/v1/precatorios' \
  --data-urlencode 'uf=SP' \
  --data-urlencode 'valor_minimo=100000' \
  --data-urlencode 'ordenar=valor_desc' \
  --data-urlencode 'limit=20' \
  --header "x-api-key: $BUSCAPROCESSOS_API_KEY" \
  --header 'Accept: application/json'

Em Node.js 22 ou superior, com fetch nativo:

const params = new URLSearchParams({
  cpf_cnpj_partes: documentos.join(','),
  incluir_requisicoes: 'true',
  limit: '100',
});

const response = await fetch(
  `https://api.buscaprocessos.app.br/v1/precatorios?${params}`,
  {
    headers: { 'x-api-key': process.env.BUSCAPROCESSOS_API_KEY },
    redirect: 'error',
    signal: AbortSignal.timeout(60000),
  },
);

const payload = await response.json();
if (response.status === 202) {
  console.log({ statusUrl: payload.data?.statusUrl });
} else if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${payload.error?.code}`);
} else {
  console.log({
    itens: payload.data?.items?.length ?? 0,
    cobrado: payload.meta?.creditsCharged,
  });
}

O exemplo faz uma requisição e imprime metadados, não os dados das partes. Observe o retorno e o consumo antes de automatizar um lote.

Os filtros que importam#

Parâmetro	Para que serve
cpf_cnpj_partes	Até 100 CPFs/CNPJs por chamada, separados por vírgula
numero_cnj	Restringe a um processo
tribunal / uf	Tribunal exato; uf cobre TJs e TREs, para TRF e TRT use tribunal
ente_devedor / cnpj_ente_devedor	Devedor por nome parcial ou CNPJ exato
ano_orcamentario	Ativa o acervo orçamentário oficial do exercício
natureza_credito	alimentar ou comum, só com classificação confirmada
superpreferencia	true exige reconhecimento; false exige ausência expressa
valor_minimo / valor_maximo	Faixa monetária
risco_aquisicao	BAIXO, MODERADO, REQUER_REVISAO ou NAO_CALCULADO
ordenar	analise_desc (padrão), valor_desc, posicao_asc, risco_asc, entre outros

Sem uf e sem tribunal, a ordenação padrão analise_desc coloca primeiro os registros mais completos: com CNJ, documento do credor, CNPJ do devedor, ano orçamentário, situação analisada e valor. Registros parciais continuam acessíveis nas páginas seguintes: a prioridade não os elimina.

Preço e cobrança#

Chamada	Preço
GET /v1/precatorios (padrão, com partes identificadas)	R$ 0,45
GET /v1/precatorios?incluir_partes=false	R$ 0,10

incluir_partes vem como true. Se você não precisa de nome e documento das partes naquela varredura, passe incluir_partes=false explicitamente e pague 4,5 vezes menos.

A cobrança é por página concluída, e uma página devolve até 100 itens. meta.creditsCharged e meta.creditsRemaining informam o valor debitado e o saldo a cada resposta. Os preços de todos os endpoints estão na página da API.

Por que não há mensalidade#

Avaliar dados de precatórios normalmente custa caro antes de começar: o padrão do mercado é mensalidade na casa dos milhares de reais, ou uma reunião comercial antes de você sequer ver o preço.

Aqui o modelo é crédito pré-pago. Você paga por consulta concluída, não por mês. Não há contrato mínimo, não há assinatura para cancelar, e o cadastro já vem com R$ 50 em créditos, o suficiente para 500 páginas de triagem, ou 111 páginas com as partes identificadas.

Como ler a resposta sem errar#

Esta é a parte que separa uma integração boa de um prejuízo. A regra central:

null significa não disponível ou não comprovado pela fonte consultada. Nunca converta null em false, zero, "quitado" ou "sem risco".

Situação de pagamento#

status_pagamento distingue três situações, e nenhuma delas significa "não pago":

Valor	Significado
NAO_ANALISADO	O histórico de movimentações ainda não foi lido
SEM_AFIRMACAO_NA_FONTE	O histórico foi lido e o tribunal não afirma pagamento
PAGO, PARCIALMENTE_PAGO, EM_ACORDO	Há afirmação na fonte, com o trecho literal na evidência

A distinção importa porque os tribunais escrevem de formas diferentes. A Justiça do Trabalho costuma declarar a quitação nos autos; a maior parte dos tribunais estaduais não. SEM_AFIRMACAO_NA_FONTE é o resultado honesto e frequente, não uma falha da consulta.

Ano orçamentário não é data de pagamento#

Ao informar ano_orcamentario, a base principal passa a ser o acervo orçamentário oficial daquele exercício, com cobertura federal. O ano indica inclusão no orçamento. Não é data prometida de pagamento nem confirmação de que alguém recebeu.

Parte credora não é beneficiário final#

requisicoes[].parte_credora identifica o credor daquela requisição, conforme publicado. A parte credora do resumo do processo não é copiada para requisições sem titular identificado, justamente para não inventar titularidade. Confirmar quem efetivamente recebe exige os autos.

Os dois scores medem coisas diferentes#

confiabilidade_dados.score (0 a 100) mede procedência, identificação e completude dos campos disponíveis. confianca_correspondencia (0 a 1) mede apenas a segurança do vínculo entre bases. Nenhum dos dois representa chance de pagamento, liquidez, ausência de risco ou validade de uma cessão.

Paginação, cobertura e HTTP 202#

paginator.total é exato dentro do índice disponível no instante da chamada. Siga links.next até ele ser null para percorrer todas as páginas.

Enquanto meta.search.coverage.status não for COMPLETE, um documento sem resultado recebe NAO_ENCONTRADO_NO_INDICE_PARCIAL. Isso é diferente de uma negativa definitiva, e a diferença precisa sobreviver até a interface do seu produto.

Se a resposta não couber na janela síncrona, a API devolve HTTP 202 com data.statusUrl, Location e Retry-After. Consulte a URL de status com a mesma chave; não repita a chamada original.

HTTP	Significado
400	Parâmetro inválido, mais de 100 documentos ou consulta indisponível por privacidade
401	Chave ausente, inválida ou revogada
403	Créditos insuficientes ou restrição da conta
429	Limite temporário; respeite Retry-After
500	Falha transitória; registre meta.requestId para o suporte

Relatórios XLSX e PDF#

Depois de executar /v1/precatorios no Playground, a resposta atual pode ser exportada em XLSX ou PDF. O XLSX é o formato indicado para carteira, conciliação e prospecção: traz abas separadas de Oportunidades, Pagamentos, Pendencias para aquisicao, Requisicoes, Partes, Consultas CPF-CNPJ e Metodologia, preservando o CNJ como chave de cruzamento e registrando filtros, requestId e cobertura.

Para uma carteira completa, percorra todas as páginas da API e prefira o XLSX. O PDF serve à revisão e ao compartilhamento de uma página específica.

O que a API não faz#

Ser explícito aqui evita quebra de expectativa depois:

• não confirma pagamento individual sem evidência publicada pela fonte oficial;
• não identifica o beneficiário final de um crédito;
• não emite alerta ou monitoramento de mudança de status de precatório;
• não substitui certidão, os autos nem parecer jurídico;
• não acessa processo em segredo de justiça.

Os sinais de risco e os eventos jurídicos são fatuais e vêm com evidência, mas servem para direcionar a revisão humana. A ausência de um sinal nunca é garantia de inexistência do fato.

Por onde começar#

Três passos, hoje:

1. Crie a conta e gere a chave. Leva menos de cinco minutos e não pede cartão.
2. Rode a primeira consulta com limit=5 e incluir_partes=false, para conhecer o formato gastando R$ 0,10.
3. Ligue incluir_partes só nas varreduras em que o nome e o documento realmente entram na decisão.

Os R$ 50 do cadastro cobrem a avaliação inteira. Se ao fim dela a API não resolver o seu caso, você não gastou nada além do tempo.