Paginação, filtros e ordenação

Como paginar, filtrar e ordenar listas e como ler o formato de resposta das listas.

Toda rota que devolve uma coleção grande (produtos, pedidos, usuários, promoções...) é paginada: você pede uma página de cada vez e a resposta diz quantas existem. As convenções abaixo valem para todas as rotas /api/v1/....

Paginar

Query parameters

pageintegerpadrão: 1

Número da página, a partir de 1. Zero, negativo ou texto voltam para 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora desse intervalo, volta a 20 (não é limitado a 100).

A resposta repete a paginação aplicada:

200Uma página de produtos

json

{
  "products": [
    { "id": "6a1f1d0c-2f0a-4e0f-9d0b-0e4b8f3b2a11", "name": "Camiseta Algodão", "sku": "CAM-001" }
  ],
  "total": 4986,
  "page": 1,
  "per_page": 20,
  "total_pages": 250
}

Campos da resposta

productsarray

A lista. A chave tem o nome do recurso no plural e muda de rota para rota (orders, users, vendors, promotions...).

totalinteger

Quantos itens existem para o filtro atual, somando todas as páginas.

pageinteger

A página devolvida.

per_pageinteger

O tamanho de página realmente aplicado (20 se você enviou um valor inválido).

total_pagesinteger

Quantas páginas existem: ceil(total / per_page).

Varrer tudo

Para exportar uma coleção inteira, avance page até passar de total_pages. Use per_page=100 e, se os dados mudam enquanto você lê, ordene por um campo estável (sort_by=created_at&sort_dir=asc) para não pular nem repetir itens.

bash

for page in 1 2 3; do
  curl -s "$BASE_URL/api/v1/admin/products?page=$page&per_page=100&sort_by=created_at&sort_dir=asc" \
    -H "Authorization: Bearer $TOKEN" | jq '.products | length'
done

Filtrar

Os filtros são parâmetros planos na URL, sem colchetes. Os nomes variam por rota e estão documentados em cada página, mas seguem padrões:

Padrão	Exemplo	Como funciona
Igualdade	`status=A`, `vendor_id=<uuid>`	Traz só os itens com aquele valor.
Busca de texto	`search=camiseta`	Procura em vários campos (nome, SKU, e-mail...), sem diferenciar maiúsculas.
Vários valores	`category_ids=a,b` ou `category_ids=a&category_ids=b`	Aceita lista separada por vírgula ou o parâmetro repetido.
Faixa de valor	`min_total=1000&max_total=5000`	Em centavos.
Faixa de data	`date_from=2026-10-01&date_to=2026-10-31`	`AAAA-MM-DD` ou RFC 3339. Com só a data, o dia final entra por inteiro.

Dois cuidados: um filtro por id com UUID mal formado pode responder 500 em algumas rotas (confira o formato antes de enviar), e um valor de status que a loja não conhece devolve lista vazia, não erro.

Ordenar

Query parameters

sort_bystring

Campo de ordenação. Os valores aceitos dependem da rota (por exemplo created_at, total, order_number). Valor desconhecido é ignorado e vale o padrão da rota.

sort_dirstringpadrão: desc

ascdesc

Direção. O padrão varia por rota.

Erros comuns

Pedir per_page=500 esperando 100. Você recebe 20: valores acima de 100 não são cortados, voltam ao padrão.
Parar na primeira página vazia. Compare page com total_pages, e trate a lista null.
Paginar sem ordem estável. Se itens são criados durante a leitura, a ordem padrão pode repetir ou pular linhas. Fixe sort_by.
Usar total como contagem exata o tempo todo. Ele reflete o filtro no momento da chamada; em dados que mudam muito, trate-o como estimativa.
Enviar datas em Unix timestamp. Use AAAA-MM-DD ou RFC 3339 (Ids, dinheiro e datas).

Veja também

Listar pedidos

Um exemplo completo de filtros e ordenação.

Ids, dinheiro e datas

Formatos de valores e datas.

Limites de requisições

Quantas páginas por minuto.

Paginação, filtros e ordenação

Como paginar, filtrar e ordenar listas e como ler o formato de resposta das listas.

Paginar

Query parameters

pageintegerpadrão: 1

Número da página, a partir de 1. Zero, negativo ou texto voltam para 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora desse intervalo, volta a 20 (não é limitado a 100).

A resposta repete a paginação aplicada:

200Uma página de produtos

json

{
  "products": [
    { "id": "6a1f1d0c-2f0a-4e0f-9d0b-0e4b8f3b2a11", "name": "Camiseta Algodão", "sku": "CAM-001" }
  ],
  "total": 4986,
  "page": 1,
  "per_page": 20,
  "total_pages": 250
}

Campos da resposta

productsarray

A lista. A chave tem o nome do recurso no plural e muda de rota para rota (orders, users, vendors, promotions...).

totalinteger

Quantos itens existem para o filtro atual, somando todas as páginas.

pageinteger

A página devolvida.

per_pageinteger

O tamanho de página realmente aplicado (20 se você enviou um valor inválido).

total_pagesinteger

Quantas páginas existem: ceil(total / per_page).

Varrer tudo

bash

for page in 1 2 3; do
  curl -s "$BASE_URL/api/v1/admin/products?page=$page&per_page=100&sort_by=created_at&sort_dir=asc" \
    -H "Authorization: Bearer $TOKEN" | jq '.products | length'
done

Filtrar

Os filtros são parâmetros planos na URL, sem colchetes. Os nomes variam por rota e estão documentados em cada página, mas seguem padrões:

Padrão	Exemplo	Como funciona
Igualdade	`status=A`, `vendor_id=<uuid>`	Traz só os itens com aquele valor.
Busca de texto	`search=camiseta`	Procura em vários campos (nome, SKU, e-mail...), sem diferenciar maiúsculas.
Vários valores	`category_ids=a,b` ou `category_ids=a&category_ids=b`	Aceita lista separada por vírgula ou o parâmetro repetido.
Faixa de valor	`min_total=1000&max_total=5000`	Em centavos.
Faixa de data	`date_from=2026-10-01&date_to=2026-10-31`	`AAAA-MM-DD` ou RFC 3339. Com só a data, o dia final entra por inteiro.

Ordenar

Query parameters

sort_bystring

Campo de ordenação. Os valores aceitos dependem da rota (por exemplo created_at, total, order_number). Valor desconhecido é ignorado e vale o padrão da rota.

sort_dirstringpadrão: desc

ascdesc

Direção. O padrão varia por rota.

Erros comuns

Pedir per_page=500 esperando 100. Você recebe 20: valores acima de 100 não são cortados, voltam ao padrão.
Parar na primeira página vazia. Compare page com total_pages, e trate a lista null.
Paginar sem ordem estável. Se itens são criados durante a leitura, a ordem padrão pode repetir ou pular linhas. Fixe sort_by.
Usar total como contagem exata o tempo todo. Ele reflete o filtro no momento da chamada; em dados que mudam muito, trate-o como estimativa.
Enviar datas em Unix timestamp. Use AAAA-MM-DD ou RFC 3339 (Ids, dinheiro e datas).

Veja também

Listar pedidos

Um exemplo completo de filtros e ordenação.

Ids, dinheiro e datas

Formatos de valores e datas.

Limites de requisições

Quantas páginas por minuto.