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}
ItemValor
URL completahttps://api.buscaprocessos.app.br/v1/processos
Authx-api-key (ou Bearer)
Query obrigatóriacpf_cnpj ou document
Query opcionalpage, limit (50 ou 100), cursor, li
Referência/reference/listarprocessospordocumento

Pré-requisitos

  1. Conta com e-mail confirmado
  2. API Key em /dashboard/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 (sem débito de uso nesse caminho de zero resultados no handler atual).

Erros frequentes nesta chamada

HTTPCódigoCausa
400MISSING_DOCUMENTSem cpf_cnpj/document
401API_KEY_REQUIRED / INVALID_API_KEYAuth
403INSUFFICIENT_CREDITSSaldo
422INVALID_DOCUMENTDocumento inválido
422INVALID_LIMITlimit diferente de 50 ou 100
429Rate limit
502UPSTREAM_UNAVAILABLEFonte 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 usam a API real e consomem créditos reais da conta.

Próximos passos