Primeira requisição
Use a listagem de processos por CPF/CNPJ para validar autenticação, host, créditos e parsing de resposta.
Endpoint
GET /v1/processos?cpf_cnpj={documento}| Item | Valor |
|---|---|
| URL completa | https://api.buscaprocessos.app.br/v1/processos |
| Auth | x-api-key (ou Bearer) |
| Query obrigatória | cpf_cnpj ou document |
| Query opcional | page, limit (50 ou 100), cursor, li |
| Referência | /reference/listarprocessospordocumento |
Pré-requisitos
- Conta com e-mail confirmado
- API Key em
/dashboard/keys - Saldo de créditos disponível
- Backend com a variável
BUSCAPROCESSOS_API_KEY
cURL
export BUSCAPROCESSOS_API_KEY='bp_live_SUA_CHAVE'
curl --request GET \
--url 'https://api.buscaprocessos.app.br/v1/processos?cpf_cnpj=00000000000' \
--header "x-api-key: ${BUSCAPROCESSOS_API_KEY}" \
--header 'Accept: application/json'O valor
00000000000é fictício e serve apenas de placeholder. Substitua por um documento válido no seu teste controlado.
TypeScript
const apiKey = process.env.BUSCAPROCESSOS_API_KEY;
if (!apiKey) throw new Error("BUSCAPROCESSOS_API_KEY ausente");
const cpfCnpj = process.env.TEST_DOCUMENT ?? "00000000000";
const res = await fetch(
`https://api.buscaprocessos.app.br/v1/processos?cpf_cnpj=${encodeURIComponent(cpfCnpj)}`,
{
headers: {
"x-api-key": apiKey,
Accept: "application/json",
},
},
);
const payload = await res.json();
if (!res.ok) {
const code = payload?.error?.code;
const message = payload?.error?.message;
throw new Error(`HTTP ${res.status} ${code ?? ""}: ${message ?? res.statusText}`);
}
const { data, meta } = payload;
// data.document, data.processos, data.links.next
// meta.creditsRemaining, meta.requestIdPython
import os
import requests
api_key = os.environ["BUSCAPROCESSOS_API_KEY"]
document = os.environ.get("TEST_DOCUMENT", "00000000000")
r = requests.get(
"https://api.buscaprocessos.app.br/v1/processos",
params={"cpf_cnpj": document},
headers={"x-api-key": api_key},
timeout=60,
)
if r.status_code >= 400:
raise SystemExit(f"{r.status_code}: {r.text}")
print(r.json())PHP
<?php
$apiKey = getenv('BUSCAPROCESSOS_API_KEY');
$document = getenv('TEST_DOCUMENT') ?: '00000000000';
$url = 'https://api.buscaprocessos.app.br/v1/processos?cpf_cnpj=' . urlencode($document);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'x-api-key: ' . $apiKey,
'Accept: application/json',
],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status >= 400) {
fwrite(STDERR, "HTTP $status: $body\n");
exit(1);
}
echo $body, PHP_EOL;O que esperar na resposta
Sucesso com processos
HTTP 200 com:
data.documentdata.documentType(cpfoucnpj)data.envolvidodata.processos(lista)data.totaldata.paginationdata.links.next(quando houver próxima página por cursor)meta.creditsRemaining,meta.requestId,meta.searchLogId,meta.servedAt
Lista vazia
Pode retornar HTTP 404 com data.processos: [] e total: 0 (sem débito de uso nesse caminho de zero resultados no handler atual).
Erros frequentes nesta chamada
| HTTP | Código | Causa |
|---|---|---|
| 400 | MISSING_DOCUMENT | Sem cpf_cnpj/document |
| 401 | API_KEY_REQUIRED / INVALID_API_KEY | Auth |
| 403 | INSUFFICIENT_CREDITS | Saldo |
| 422 | INVALID_DOCUMENT | Documento inválido |
| 422 | INVALID_LIMIT | limit diferente de 50 ou 100 |
| 429 | — | Rate limit |
| 502 | UPSTREAM_UNAVAILABLE | Fonte indisponível |
Paginação
Quando existir próxima página, use o link retornado em data.links.next.href em vez de reconstruir cursor e li manualmente.
Veja Paginação.
Boas práticas de custo
- Normalize o documento antes da chamada.
- Não dispare automaticamente capa/movimentações/documentos/IA para todos os processos da lista.
- Persista
meta.requestIdpara suporte. - Trate 429 com
Retry-After.
Testar no painel
Abra o Playground.
As chamadas usam a API real e consomem créditos reais da conta.