Primeira requisição

Use a listagem de processos por CPF/CNPJ para validar autenticação, host, créditos e parsing de resposta.

Além do teste técnico, esta chamada demonstra o primeiro ganho prático da integração: transformar um documento em uma lista estruturada de processos que pode alimentar triagem, cadastro, análise ou uma jornada de aprofundamento por CNJ.

O valor desta operação

• elimina a transcrição manual dos resultados para o seu sistema;
• permite verificar pessoas ou empresas dentro do fluxo do seu produto;
• funciona como ponto de entrada para capa, movimentações, documentos e IA;
• possibilita selecionar apenas os casos relevantes antes de gerar novas consultas;
• entrega metadados de consumo e correlação junto com o resultado.

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

1. Conta com e-mail confirmado
2. API Key em API Keys
3. Saldo de créditos disponível
4. 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.requestId

Python

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.document
• data.documentType (cpf ou cnpj)
• data.envolvido
• data.processos (lista)
• data.total
• data.pagination
• data.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 quando não houver resultados; esse cenário não gera débito de uso.

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

1. Normalize o documento antes da chamada.
2. Não dispare automaticamente capa/movimentações/documentos/IA para todos os processos da lista.
3. Persista meta.requestId para suporte.
4. Trate 429 com Retry-After.

Testar no painel

Abra o Playground.
As chamadas são feitas em produção e consomem créditos da conta.

Próximos passos

• Consulta por CNJ
• Movimentações
• Webhooks
• Erros