Paginação

A API usa paginação por page/limit e, em alguns recursos, por cursor/li.

A paginação permite processar carteiras e históricos de forma controlada, sem carregar todo o universo de dados em uma única execução. Isso melhora estabilidade, previsibilidade de consumo e capacidade de retomar um trabalho interrompido.

Benefícios na automação

processe volumes maiores em lotes previsíveis;
salve progresso e retome do próximo link ou página;
aplique limites de custo e tempo por execução;
distribua páginas em filas sem repetir itens já processados.

Padrões

page + limit

Usado em vários listadores, por exemplo monitoramentos e alguns históricos.

GET /v1/monitoramentos/processos?page=1&limit=20

cursor + li

Usado em listagens que espelham paginação da fonte, como:

GET /v1/processos?cpf_cnpj=00000000000&limit=100

Quando há próxima página, a resposta de /v1/processos pode incluir:

{
  "data": {
    "links": {
      "next": {
        "href": "https://api.buscaprocessos.app.br/v1/processos?cpf_cnpj=00000000000&limit=100&cursor=CURSOR&li=LI",
        "cursor": "CURSOR",
        "li": "LI"
      }
    }
  }
}

Regra de ouro

Siga data.links.next.href exatamente.
Não reconstrua cursor e li manualmente a partir de outros campos.

Limites específicos

`GET /v1/processos`

limit aceito: 50 ou 100
valor padrão: 100
limit inválido → HTTP 422 INVALID_LIMIT

Se a busca direta na PDPJ responder HTTP 500 ou 503 e já existirem processos vinculados ao documento no índice local, a API entrega HTTP 200 com data.partial: true. Nesse caso, data.coverage.verifiedByDocumentSearch é false, officialTotal é null e a contagem é um limite inferior. A busca continua em segundo plano; uma chamada posterior pode trazer o portfólio confirmado e mais processos. A resposta parcial com processos é cobrada como uma listagem normal; confira meta.creditsCharged.

Filtro de tribunais em CPF/CNPJ

Em GET /v1/processos, o parâmetro tribunais aceita até cinco siglas na mesma chamada. Envie as siglas separadas por vírgula ou repita o parâmetro:

curl --request GET \
  --get 'https://api.buscaprocessos.app.br/v1/processos' \
  --data-urlencode 'cpf_cnpj=00000000000' \
  --data-urlencode 'tribunais=TJRJ,TJSP,TJRS' \
  --data-urlencode 'limit=100' \
  --header 'Accept: application/json' \
  --header 'x-api-key: SUA_API_KEY'

Com tribunais informado, a primeira página custa R$ 0,25 por tribunal que retornar ao menos um processo. Tribunais sem resultado não são cobrados. As páginas seguintes indicadas em data.links.next.href não geram nova cobrança. Sem esse filtro, permanece o preço padrão da listagem por CPF/CNPJ.

Consultas por OAB

GET /v1/advogados/processos: limit aceito em 50 ou 100, com padrão 50; os processos são deduplicados por numeroCnj.
GET /v1/advogados/resumo: não tem páginas, mas usa o mesmo portfólio progressivo e pode apresentar contagens provisórias.
nas duas rotas, a primeira resposta pode ser parcial enquanto o histórico oficial é consolidado em segundo plano.

Processos por OAB: resultado progressivo

Uma consulta por OAB pode responder HTTP 200 rapidamente com os processos já indexados e continuar ampliando a cobertura histórica em segundo plano. Durante essa etapa, a quantidade de processos pode crescer entre duas consultas.

Importante: quando data.cobertura.parcial for true, quantidadeProcessos, totalDisponivel, pagination.total e pagination.totalPages são valores provisórios. Não trate essa resposta como uma fotografia completa da carteira.

No endpoint de resumo, quantidadeProcessos, quantidadeRecentes e quantidadeHistoricos também são provisórios enquanto a cobertura estiver parcial. quantidadeAtivosConfirmados permanece uma métrica separada, baseada na confirmação processual disponível, e não deve ser calculada a partir da classificação RECENTE.

Exemplo de cobertura ainda em atualização:

{
  "data": {
    "total": 100,
    "totalDisponivel": 344,
    "pagination": {
      "currentPage": 1,
      "perPage": 100,
      "totalPages": 4,
      "total": 344
    },
    "cobertura": {
      "fonte": "BuscaProcessos",
      "origens": ["BuscaProcessos"],
      "completa": false,
      "parcial": true,
      "motivoParcial": "Carregadas 5 de 52 páginas da fonte oficial.",
      "paginasConsultadas": 5,
      "totalPaginasFonte": 52,
      "atualizadoEm": "2026-08-24T19:21:59.860Z"
    }
  }
}

Há dois usos recomendados:

Tela interativa: exiba os itens disponíveis imediatamente, mostre o estado “atualizando histórico” e faça upsert por numeroCnj. Não anuncie o total provisório como quantidade final.
Importação completa: aguarde data.cobertura.completa === true; então reinicie na página 1 e siga data.links.next.href até ele se tornar null.

Durante uma importação completa:

persista data.cobertura.atualizadoEm como versão da coleta;
deduplique todas as páginas por numeroCnj;
se atualizadoEm mudar durante a varredura, reinicie a paginação ou faça uma reconciliação por CNJ;
mesmo depois de uma cobertura completa, novas publicações oficiais podem acrescentar ou reordenar processos em consultas futuras.

Não faça polling curto da página 1. Cada nova chamada com page=1 é uma nova consulta e pode gerar cobrança; confira sempre meta.creditsCharged. As páginas seguintes da mesma paginação (page > 1) são incluídas sem cobrança adicional, mas só devem ser usadas para uma importação definitiva depois que a cobertura estiver completa.

O mesmo cuidado vale para GET /v1/advogados/resumo: cada nova chamada é uma nova consulta de resumo e pode gerar cobrança. Use a resposta parcial para exibição provisória e defina uma cadência de reconciliação adequada ao produto, sem polling em intervalos curtos.

Certificados

listagem com até 20 itens por página

Consulte a referência de cada endpoint para parâmetros exatos.

Exemplo de loop seguro (TypeScript)

const apiKey = process.env.BUSCAPROCESSOS_API_KEY!;
let url: string | null =
  "https://api.buscaprocessos.app.br/v1/processos?cpf_cnpj=00000000000&limit=100";

while (url) {
  const res = await fetch(url, {
    headers: { "x-api-key": apiKey },
  });
  const body = await res.json();
  if (!res.ok) throw new Error(JSON.stringify(body));

  // processar body.data.processos
  url = body?.data?.links?.next?.href ?? null;
}

Custos e paginação

O comportamento de cobrança depende do recurso. Em processos por OAB, uma nova consulta da página 1 pode ser cobrada, enquanto as páginas seguintes são incluídas. Em outros recursos, páginas adicionais podem gerar consumo.

Use meta.creditsCharged como fonte de verdade e trate paginação como decisão explícita de produto, não como loop ilimitado.

Benefícios na automação​

Padrões​

page + limit​

cursor + li​

Regra de ouro​

Limites específicos​

GET /v1/processos​

Filtro de tribunais em CPF/CNPJ​

Consultas por OAB​

Processos por OAB: resultado progressivo​

Certificados​

Exemplo de loop seguro (TypeScript)​

Custos e paginação​

Relacionados​