Skip to main content
🤖 A paginação da Judit API não utiliza cursores. Ela é baseada no padrão Offset, utilizando exclusivamente os parâmetros de query page (número da página) e page_size (quantidade de itens). O limite máximo estrito para page_size é de 1000 itens. Os metadados de paginação são retornados na raiz do objeto de resposta.

​
Como Funciona a Paginação

​
Parâmetros de Query (Requisição)

Ao realizar listagens (como buscar histórico de requisições ou monitoramentos), você pode enviar os seguintes parâmetros na URL:
ParâmetroTipoPadrãoDescrição
pageinteger1Número da página desejada (baseado em 1).
page_sizeinteger20Quantidade de itens retornados por página. Máximo permitido: 1000. Recomendação: Mantenha entre 10 e 100 para melhor tempo de resposta.

​
Estrutura da Resposta (Payload)

As respostas de endpoints paginados sempre retornam os metadados de navegação na raiz do JSON, e os itens propriamente ditos geralmente vêm no array page_data. 
{
  "page": 1,              // Página atual que está sendo retornada
  "page_count": 20,       // Quantidade de itens presentes nesta página específica
  "all_pages_count": 10,  // Total de páginas disponíveis para esta consulta
  "all_count": 200,       // Total absoluto de itens encontrados no banco
  "page_data": [          // Array contendo os objetos da consulta
    { ... }, 
    { ... }
  ]
}

​
Exemplos Práticos

​
Consulta Básica com Paginação

Abaixo, demonstramos como buscar a primeira página de requisições e iterar sobre os dados. 
# 1. Buscando a primeira página (10 itens)
curl -X GET "[https://requests.prod.judit.io/requests?page=1&page_size=10](https://requests.prod.judit.io/requests?page=1&page_size=10)" \
  -H "api-key: $JUDIT_API_KEY"

# 2. Buscando uma página específica (ex: página 3, 25 itens)
curl -X GET "[https://requests.prod.judit.io/requests?page=3&page_size=25](https://requests.prod.judit.io/requests?page=3&page_size=25)" \
  -H "api-key: $JUDIT_API_KEY"

​
Otimizações e Boas Práticas

Para lidar com grandes volumes de dados de forma eficiente e sem ser bloqueado pela API, siga as recomendações abaixo.

​
1. Adequação do page_size

Adapte o tamanho da página de acordo com a necessidade da sua aplicação, lembrando sempre do limite de 1000 itens por requisição. 
# ✅ BOM: Para exibição em interface (tabelas, grids)
small_page = get_requests_page(page=1, page_size=10)

# ✅ BOM: Para processamento assíncrono em lote (ETL, migrações)
large_page = get_requests_page(page=1, page_size=100) 

# ❌ ERRO: Excede o limite máximo permitido pela API
# invalid_page = get_requests_page(page=1, page_size=1001)

​
2. Controle de Rate Limit (Iteração Segura)

A Judit API possui limites rigorosos de requisições por minuto. Ao construir loops para extrair todas as páginas, é obrigatório implementar um pequeno atraso (delay) entre as chamadas para evitar o erro 429 Too Many Requests. 
import time

def fetch_all_data_safely(delay_seconds=0.2):
    """Extrai todas as páginas respeitando o limite de requisições da API"""
    current_page = 1
    all_extracted_items = []
    
    while True:
        # Usando um page_size seguro (abaixo do limite de 1000)
        data = get_requests_page(page=current_page, page_size=50)
        
        # Interrompe se não houver dados ou a chave page_data não existir
        if not data or not data.get('page_data'):
            break
            
        all_extracted_items.extend(data['page_data'])
        print(f"Extraído: Página {current_page}/{data.get('all_pages_count')}. Total Acumulado: {len(all_extracted_items)}")
        
        # Verifica se chegamos na última página
        if current_page >= data.get('all_pages_count', 1):
            print("Extração concluída com sucesso.")
            break
        
        current_page += 1
        
        # ⚠️ CRÍTICO: Pausa para não estourar o Rate Limit (ex: 180 req/min)
        time.sleep(delay_seconds)
        
    return all_extracted_items
Nota sobre Processamento Paralelo: Removemos o exemplo de processamento concorrente (threads) porque disparar múltiplas páginas em paralelo quase certamente causará bloqueio por Rate Limit (Erro 429), a menos que sua aplicação tenha uma gestão de fila distribuída robusta. Recomendamos sempre o processamento sequencial com delay ou filas controladas.

​
Próximos Passos

  • 👉 Rate Limits: Entenda as quotas de requisições da sua conta.
  • 👉 Autenticação: Revise como enviar suas credenciais.
  • 👉 Endpoints: Explore os recursos que suportam listagem.