Como integrar a API de processos judiciais com Python e Node.js

A API de processos judiciais do BuscaProcessos permite incorporar consultas por CPF ou CNPJ ao backend de um sistema. O ponto de entrada deste tutorial é GET /v1/processos: ele localiza registros por documento e devolve JSON para a sua aplicação.

Este guia é público. A referência completa de endpoints, os guias de autenticação e os exemplos adicionais continuam no ReadMe, com acesso pela conta.

Antes da primeira chamada#

Você precisa de uma conta com acesso à API, uma chave ativa e créditos para a operação. Guarde a chave em uma variável de ambiente do servidor chamada BUSCAPROCESSOS_API_KEY. Defina TEST_DOCUMENT com um CPF ou CNPJ válido para o seu teste autorizado, apenas com dígitos.

Não coloque a chave no JavaScript entregue ao navegador, em repositórios ou em logs. Os exemplos abaixo fazem uma requisição: não repetem automaticamente a consulta nem percorrem todas as páginas. Isso permite observar o retorno e o consumo antes de automatizar um lote.

Exemplo com Node.js#

Use Node.js 22 ou superior, com fetch nativo. Salve como consulta.mjs e execute node consulta.mjs após definir as variáveis de ambiente.

const apiKey = process.env.BUSCAPROCESSOS_API_KEY;
const document = process.env.TEST_DOCUMENT;
if (!apiKey || !document) throw new Error('Defina a chave e TEST_DOCUMENT');

const url = new URL('https://api.buscaprocessos.app.br/v1/processos');
url.searchParams.set('cpf_cnpj', document);

const response = await fetch(url, {
  headers: { 'x-api-key': apiKey, Accept: 'application/json' },
  redirect: 'error',
  signal: AbortSignal.timeout(60000),
});
const body = await response.json();

if (response.status === 202) {
  console.log({
    status: 'PROCESSANDO',
    statusUrl: response.headers.get('Location') || body.data?.statusUrl,
    retryAfter: response.headers.get('Retry-After'),
  });
} else if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${body.error?.code || 'API_ERROR'}`);
} else {
  console.log({
    registrosNestaPagina: body.data?.processos?.length ?? 0,
    proximaPagina: body.data?.links?.next ?? null,
  });
}

O exemplo imprime metadados, sem despejar os dados das partes no terminal. Em sua aplicação, use o corpo da resposta concluída para construir a interface ou o fluxo de análise.

Exemplo com Python#

Em um ambiente virtual Python 3.10 ou superior, instale requests com python -m pip install requests. Salve como consulta.py e execute python consulta.py com as mesmas variáveis de ambiente.

import os
import requests

api_key = os.environ['BUSCAPROCESSOS_API_KEY']
document = os.environ['TEST_DOCUMENT']

response = requests.get(
    'https://api.buscaprocessos.app.br/v1/processos',
    params={'cpf_cnpj': document},
    headers={'x-api-key': api_key, 'Accept': 'application/json'},
    timeout=(10, 60),
    allow_redirects=False,
)
body = response.json()

if response.status_code == 202:
    print({
        'status': 'PROCESSANDO',
        'statusUrl': response.headers.get('Location') or body.get('data', {}).get('statusUrl'),
        'retryAfter': response.headers.get('Retry-After'),
    })
elif not 200 <= response.status_code < 300:
    code = body.get('error', {}).get('code', 'API_ERROR')
    raise RuntimeError(f'HTTP {response.status_code}: {code}')
else:
    data = body.get('data', {})
    print({
        'registrosNestaPagina': len(data.get('processos', [])),
        'proximaPagina': data.get('links', {}).get('next'),
    })

Como concluir uma consulta que retorna HTTP 202#

HTTP 202 significa que a consulta continua em processamento. Não interprete esse retorno como uma lista vazia de processos.

1. Guarde o requestId e a URL de acompanhamento informada em Location ou data.statusUrl.
2. Aguarde o intervalo indicado por Retry-After.
3. Faça um GET na URL de acompanhamento com a mesma chave, mantendo esse ciclo enquanto receber 202.
4. Ao receber a resposta final, verifique o status HTTP antes de ler data.processos.

Antes de enviar a chave a uma URL recebida na resposta, valide que ela usa HTTPS e pertence a api.buscaprocessos.app.br. Resolva caminhos relativos contra essa origem e recuse redirecionamentos para outros hosts. Defina um prazo máximo de acompanhamento e permita retomar a consulta pendente pelo identificador, sem disparar novamente a busca inicial.

Se houver erro de rede, timeout ou resposta não JSON, registre o problema sem expor a chave ou o documento. Um timeout do cliente não prova que a consulta deixou de ser processada. Consulte as regras de erros e acompanhamento no ReadMe antes de implementar novas tentativas automáticas.

Paginação e créditos#

Uma página de resultados não representa necessariamente todos os registros encontrados. Na resposta concluída, verifique data.links.next. Se houver outra página, planeje a continuidade e valide a origem do link antes de enviar a chave.

Confira as regras de cada operação na página da API e seus preços. Listagem por documento, consulta de capa, movimentações e documentos são recursos distintos. Teste um volume pequeno e acompanhe os metadados de consumo antes de aumentar a concorrência.

API ou painel para a equipe?#

A API atende sistemas que precisam incorporar a consulta ao próprio fluxo. Para uma equipe que trabalha com planilhas e revisão pelo navegador, conheça o painel de background check para empresas e o guia de fornecedores em lote.

Para iniciar uma integração, veja os recursos da API jurídica. Para detalhes do contrato e exemplos por endpoint, entre na documentação ReadMe.