Paginação e créditos na API judicial com Python

Uma integração pode funcionar bem em testes e ainda consumir créditos além do previsto quando entra em produção. Isso costuma acontecer quando o sistema busca processos em várias páginas, repete chamadas após uma falha ou consulta novamente um resultado que já foi salvo. Na paginação da API de processos judiciais em Python com controle de créditos, o objetivo não é apenas percorrer todos os resultados: é saber o que foi consultado, o que foi persistido e quando parar.

Este tutorial é para desenvolvedores de legaltechs, escritórios e empresas que integram dados processuais ao próprio sistema. A premissa é simples: a API é a conexão entre sistemas, mas a responsabilidade por organizar a coleta, registrar o consumo e tratar erros continua sendo da aplicação cliente.

O que a paginação resolve na consulta processual

Uma busca pode retornar mais itens do que cabem em uma única resposta. Em vez de entregar uma lista extensa de uma só vez, a API divide o resultado em páginas. A sua aplicação recebe a primeira parte, identifica se há uma próxima página e repete a consulta até encerrar a lista ou atingir o limite definido pela operação.

Isso é diferente de repetir a mesma pesquisa sem critério. Se o sistema chama a primeira página dez vezes, ele não avançou na coleta e pode gerar consumo desnecessário. Por isso, a paginação precisa usar um marcador confiável, normalmente o número da página, um cursor ou um token informado na resposta. O formato exato depende da documentação da API utilizada.

Também vale separar três tarefas que, na prática, têm regras diferentes. A descoberta de novos processos por CPF ou CNPJ procura ocorrências associadas a uma pessoa ou empresa. O acompanhamento de um processo já conhecido usa o número CNJ para consultar uma referência específica. Já o monitoramento de publicações por OAB procura comunicações vinculadas à inscrição profissional. Misturar essas rotinas em uma única fila dificulta estimar volume, consumo e finalidade de cada chamada.

Antes do código, defina o teto de créditos

Controle de créditos começa com uma decisão de negócio traduzida em regra técnica. Uma rotina de atualização de carteira não deve continuar indefinidamente só porque ainda existem páginas disponíveis. Ela precisa ter um orçamento por execução, por cliente, por tipo de pesquisa ou por período.

Imagine uma tarefa demonstrativa: atualizar processos descobertos a partir de uma lista de CNPJs de fornecedores. O sistema recebe 200 identificadores, mas a execução foi configurada para interromper a coleta ao atingir o teto interno de 500 créditos. Esse teto não informa o preço nem substitui as regras do contrato. Ele serve para impedir que uma falha de lógica transforme uma rotina recorrente em consumo inesperado.

Registre pelo menos quatro informações a cada chamada: o identificador da execução, o critério pesquisado, o marcador de paginação enviado e o resultado da tentativa. Se a plataforma informar consumo ou saldo na resposta, grave esses dados como evidência operacional, sem assumir que serão iguais para todos os tipos de consulta. Confirme os campos disponíveis na documentação atual antes de implementar.

Modelo de paginação em Python

O exemplo abaixo é propositalmente genérico. Nomes de URL, parâmetros e campos como items ou next_cursor precisam ser adaptados ao contrato oficial da API. O ponto central é a sequência: consultar, validar, persistir, contabilizar e só então avançar.

@dataclass class LimiteDeColeta: creditos_maximos: int creditos_usados: int = 0

def pode_continuar(self, custo_estimado: int = 1) -> bool: return self.creditos_usados + custo_estimado <= self.creditos_maximos

def registrar_consumo(self, quantidade: int = 1) -> None: self.creditos_usados += quantidade

def buscar_paginas(criterio: dict, limite: LimiteDeColeta): cursor = None resultados = []

while limite.pode_continuar(): params = {**criterio} if cursor: params["cursor"] = cursor

resposta = requests.get( "URL_DEFINIDA_NA_DOCUMENTACAO", params=params, timeout=30 ) resposta.raise_for_status() dados = resposta.json()

itens = dados.get("items", []) resultados.extend(itens)

consumo = dados.get("creditos_consumidos", 1) limite.registrar_consumo(consumo)

cursor = dados.get("next_cursor") if not cursor or not itens: break

return resultados ```

Há duas escolhas relevantes nesse modelo. A primeira é interromper a rotina antes da próxima chamada quando o orçamento local não permite continuar. A segunda é usar o consumo retornado pela resposta apenas se esse campo fizer parte do contrato real. Se a API não fornecer essa informação, o controle interno pode trabalhar com uma estimativa por requisição, desde que isso fique claro para quem administra a integração.

Um detalhe aparentemente pequeno evita muitos erros: não avance o cursor antes de gravar os itens recebidos. Se a aplicação falhar depois de receber a resposta e antes de persistir os dados, você precisará saber qual página foi processada de fato. Caso contrário, a retomada pode pular resultados ou buscar a mesma página sem controle.

## Persistência evita repetição e melhora a retomada

Guardar apenas a lista final em memória não é suficiente para uma integração recorrente. Em uma base de dados, crie um registro de execução com status como `iniciada`, `concluída`, `interrompida_por_limite` ou `falhou`. Salve também o último cursor concluído, a data da coleta e uma chave que identifique o critério pesquisado.

Para cada processo retornado, use uma chave de unicidade coerente com a finalidade. No acompanhamento de casos conhecidos, o número CNJ tende a ser a referência principal. Em uma descoberta por CPF ou CNPJ, o mesmo processo pode aparecer em mais de uma busca ou em diferentes execuções. Nesse cenário, a sua modelagem precisa distinguir o processo da associação encontrada, sem criar duplicatas desnecessárias.

Uma estratégia prática é persistir cada item em transação e só marcar a página como concluída depois que todos os itens forem gravados. Se a execução cair no meio, a próxima tentativa retoma do último ponto confirmado. Dependendo da API, repetir uma página pode ser inevitável após uma falha. O importante é que a persistência suporte reprocessamento sem multiplicar registros nem disparar notificações duplicadas.

## Trate falhas sem transformar a retentativa em loop

Uma resposta temporariamente indisponível não deve encerrar toda a coleta, mas também não justifica repetir chamadas sem fim. Defina poucas tentativas, registre o erro e aplique espera progressiva entre elas. Erros de autenticação, parâmetros inválidos ou permissão insuficiente normalmente exigem correção de configuração, não novas tentativas automáticas.

O limite de créditos deve ser verificado também nas retentativas. Uma chamada que falhou após chegar ao servidor pode ter sido processada do outro lado, conforme o comportamento documentado. Por isso, registre um identificador de requisição quando houver e prefira retomar a partir do estado persistido. Não presuma que uma exceção de rede significa ausência de consumo.

Além disso, defina um limite de páginas por execução. Ele protege a aplicação contra respostas inesperadas, filtros muito amplos e erros de paginação em que o cursor não muda. Se o novo cursor for igual ao anterior, interrompa a tarefa e sinalize o problema para análise.

## Como validar a rotina antes de liberar em produção

Comece com um conjunto pequeno e conhecido de critérios de busca. Valide se a primeira página é salva, se a próxima página usa o marcador correto e se o encerramento acontece quando não há continuação. Depois, simule uma interrupção entre a resposta e a persistência para conferir a retomada.

Teste também o comportamento no teto de créditos. A aplicação deve parar de forma explícita, gravar o motivo e permitir que uma nova execução seja iniciada com orçamento autorizado. Para equipes que operam grande volume, um painel interno com execução, critério, páginas processadas e status costuma ser mais útil do que um log técnico isolado.

Por fim, compare os campos recebidos com a finalidade declarada da rotina. Dados processuais exigem contexto: a existência de um processo não comprova culpa, não equivale a uma certidão e não deve gerar reprovação automática em decisões de RH, fornecedores ou crédito. Respeite também as restrições da fonte, incluindo dados indisponíveis por segredo de justiça ou por limites de cobertura confirmados para a integração.

## Paginação previsível começa com estado bem registrado

Uma boa integração não é a que chama a API mais rápido. É a que consegue explicar, em qualquer momento, qual critério pesquisou, até onde avançou, o que salvou e por que interrompeu. Com paginação persistente, teto de créditos e retentativas limitadas, a consulta deixa de ser uma sequência opaca de requisições e passa a ser uma rotina auditável para o produto e para a operação.

Antes de ampliar o volume, confira na documentação oficial quais são os parâmetros de paginação, os campos de resposta e as regras de consumo aplicáveis ao seu caso. Esse cuidado no início evita que uma simples coleta recorrente se torne uma fonte de dados duplicados, custo difícil de prever e manutenção desnecessária.

> [Conheça a API de consulta processual do BuscaProcessos](https://buscaprocessos.app.br/api-integracoes) e confira os recursos e a documentação para integrar pesquisas processuais ao seu sistema.