Integração em produção

Use este guia depois da primeira requisição. Ele reúne os cuidados que evitam consultas duplicadas, resultados incompletos e consumo inesperado.

Dois fluxos de HTTP 202

Resposta	Próxima chamada	Quando parar
202 com URL de /v1/requests/{requestId}	GET na URL informada, com a mesma API Key	Ao receber uma resposta final; se ela for outro recibo de negócio, siga o fluxo daquele recurso
202 com providerRequestId ou identificador específico	Endpoint de status do recurso	No estado terminal definido pelo recurso

O primeiro fluxo acompanha uma requisição HTTP que continua em processamento. A consulta de /v1/requests/{requestId} reproduz o resultado e não repete a operação de negócio.

O segundo é usado, por exemplo, na geração de resumo por IA. O identificador de negócio não é meta.requestId, e a aceitação pode ter a cobrança prevista no endpoint. Não trate todo 202 como gratuito nem todo 200 de status como conclusão: confira também o estado do recurso.

Respeite Retry-After ou pollAfterMs, limite o polling e guarde a URL/identificador para retomar depois. Não crie a operação original novamente a cada tentativa.

Cliente JSON reutilizável

Baixar exemplo JavaScript para backend. O arquivo usa fetch, mantém a API Key no header, limita as consultas de status e aceita somente URLs da própria API para não enviar a chave a outro host.

import { requestJson } from './client.mjs';

const { status, payload } = await requestJson('/v1/processos?cpf_cnpj=00000000000', {
  apiKey: process.env.BUSCAPROCESSOS_API_KEY,
  maxPolls: 60,
});

if (status === 404 && Array.isArray(payload.data?.processos) && payload.data.processos.length === 0) {
  console.log('Consulta concluída sem processos disponíveis.');
} else if (status === 202) {
  console.log("Operação aceita; siga o estado de negócio", payload.data);
} else if (status >= 400) {
  throw new Error(`HTTP ${status}: ${payload.error?.code ?? 'api_error'}`);
} else {
  console.log(payload.data);
}

O CPF é fictício. O exemplo devolve o status e o corpo final para sua aplicação interpretar conforme o recurso. Em 202 sem URL de /v1/requests/{requestId}, devolve o recibo para o fluxo específico; em 429 ou erro, não repete automaticamente a chamada de negócio. O limite padrão é de 60 consultas de status, com timeout de 35 segundos por chamada; adapte ao tempo e ao volume do seu produto.

Erro, resultado vazio e cobertura parcial

São três situações diferentes:

• Erro: credencial, entrada ou fonte impediu a consulta. Trate error.code e o status HTTP.
• Resultado vazio: uma consulta concluída não trouxe itens; o status e a cobrança variam por recurso. Por exemplo, a listagem de processos pode retornar 404 com lista vazia, enquanto BNMP retorna 200 com NADA_CONSTA.
• Cobertura parcial: há dados utilizáveis, mas o conjunto ainda não está completo. Preserve partial, cobertura, coverage e warnings quando presentes.

Não converta campo null em zero ou false. Para importação de uma carteira por OAB, espere a cobertura completa e reconcilie por CNJ, conforme Paginação.

Paginação e repetição

Siga o link retornado e deduplique pela chave do recurso: CNJ para processos, ID para publicações ou resultados. Salve o progresso para não recomeçar a coleta inteira após uma interrupção.

Não presuma que o nome dos campos ou a cobrança por página é igual entre endpoints. Busca por termo e precatórios podem cobrar páginas adicionais; outros fluxos incluem páginas seguintes conforme as regras da consulta.

Uma nova chamada de negócio pode ser uma nova consulta cobrada. Depois de timeout ou perda de conexão, use o identificador/status já recebido para reconciliar. Se não recebeu identificador, confira o estado no painel ou nos endpoints de listagem antes de recriar um monitoramento. A documentação não promete idempotência universal para POST.

Concorrência e eventos

Nas rotas de consulta judicial que usam o perfil padrão, o limite é de 2 requisições por segundo por API Key, com rajada de até 10. Outros recursos podem usar limites diferentes. Ao receber 429, respeite Retry-After e reduza a concorrência.

Para eventos contínuos, configure webhooks quando o plano permitir. Valide a assinatura sobre o corpo bruto, grave e deduplique a entrega de forma durável antes de responder 2xx. Polling de uma consulta pendente não substitui um receptor de eventos.

Operação e suporte

Registre status HTTP, error.code, requestId e searchLogId quando disponíveis. Não registre a API Key, o segredo HMAC ou a query string de links assinados. Consulte Segurança para credenciais e Créditos e preços para consumo.