Pular para o conteúdo principal

Paginação e filtros

A LightHouse API pagina listas via parâmetros de query (PageIndex/PageSize) — não existe um schema de request nomeado para paginação (o corpo, quando a operação usa GET, não é enviado; os filtros e a paginação vão todos na query string).

Sobre este guia

Não existe um schema FiltroOcorrenciaWithPagination na spec publicada — os filtros de ocorrências (GET /v3/ocorrencias e equivalentes) são parâmetros de query individuais, entre eles PageIndex e PageSize. Este guia documenta o mecanismo real.

Parâmetros de paginação​

Presentes nas listagens principais (GET /v1|v2|v3/ocorrencias, GET /v1/atividades, etc.):

ParâmetroObrigatórioFaixaDescrição
PageIndexSiminteiro, começa em 1Índice da página. Testado: PageIndex=0 não retorna erro — retorna uma lista vazia silenciosamente (ver troubleshooting abaixo).
PageSizeSim1 a 100Quantidade de itens por página.

A resposta é um array simples dos itens da página (OcorrenciasListV3, AtividadesAgendadasList etc.) — não vem envelopada com totalCount/totalPages/hasNextPage. Para saber o total, use o endpoint de contagem correspondente (GET /v3/ocorrencias/count, GET /v1/ocorrencias/count) antes de paginar.

Exemplo: buscar ocorrências, página a página​

EmpresaId vai no header HTTP, não na query — ver a tabela canônica de contexto de empresa (esses dois endpoints usam o padrão "header obrigatório").

# 1. Descubra o total antes de paginar
curl "https://lighthousev2.lkp.app.br/v3/ocorrencias/count" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "EmpresaId: 123"
# -> 247

# 2. Peça páginas de 100 em 100 (o máximo permitido por PageSize), começando em PageIndex=1
curl "https://lighthousev2.lkp.app.br/v3/ocorrencias?PageIndex=1&PageSize=100" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "EmpresaId: 123"

Combine PageIndex/PageSize com os demais filtros do endpoint (DataInicio, DataTermino, ExecutorId, EmitenteId etc. — ver Glossário de IDs e enums) para reduzir o volume antes de paginar, em vez de baixar tudo e filtrar no cliente. Para filtrar por status (ex.: ocorrências abertas), use StatusIds — ver Glossário → status de ocorrência (v3).

Como iterar sem loop infinito​

Como a resposta não informa se há mais páginas, o critério de parada é o tamanho da página retornada:

  1. Peça a contagem total (GET .../count) e calcule totalPaginas = ceil(total / PageSize) — use isso como limite superior do loop, nunca um while (true).
  2. A cada chamada, se o array retornado vier vazio ou com menos itens que PageSize, é a última página — pare, mesmo que o cálculo do passo 1 sugerisse mais uma volta.
  3. Sempre imponha também um limite absoluto de iterações no código do agente (ex.: nunca mais que totalPaginas, com uma margem pequena) — mesmo com os dois critérios acima, um agente autônomo não deve depender só da condição de parada da API para não rodar indefinidamente.
pagina = 1
total = GET /v3/ocorrencias/count?...
maxPaginas = ceil(total / pageSize)

enquanto pagina <= maxPaginas:
    itens = GET /v3/ocorrencias?PageIndex=pagina&PageSize=pageSize&...
    processar(itens)
    se tamanho(itens) < pageSize:
        parar  # ultima pagina
    pagina += 1

Recebendo [] ou 0 inesperado?​

A API não retorna erro nesses dois casos — ela responde uma lista vazia (ou contagem 0) silenciosamente, como se a consulta fosse válida e não tivesse resultado. Antes de concluir que não há dados, confira:

  1. Header EmpresaId ausente nos endpoints que o exigem (ver tabela canônica de contexto de empresa) — sem ele, alguns endpoints retornam vazio em vez de erro de autorização.
  2. PageIndex=0 — a paginação começa em 1; PageIndex=0 retorna [] mesmo havendo registros.

Boas práticas​

  • Prefira PageSize=100 (o máximo) para reduzir o número de chamadas, salvo se a integração precisar de respostas menores por chamada.
  • Use os endpoints de contagem (/count) para dashboards que só precisam do número total — não pagine uma listagem inteira só para contar itens.
  • Combine filtros de negócio (período, unidade, status) com a paginação — isso reduz o número de páginas necessárias, não só o tamanho de cada uma.
  • Ver Rate limiting — cada página é uma requisição; um loop de paginação mal dimensionado pode consumir uma fatia relevante do limite de 1200 req/h.