Entrar
.md

Parâmetros de listagem

Todo endpoint de listagem da API Guper entende uma gramática de querystring compartilhada para filtragem, ordenação e paginação. Aprendeu em um recurso, vale para todos.

q[] ou QON? Esta é a gramática q[], para ler e listar: buscar um cliente, filtrar pedidos, paginar um relatório. O QON é outra coisa — expressões aninhadas em JSON que servem só para montar audiência no construtor de segmentação. Para achar um cliente por CPF ou e-mail, é q[], aqui — não QON.

Filtragem — q[coluna][operador]=valor

q[coluna][operador]=valor
  • coluna — pode ser composta, separada por ; ou |.
  • operador — um dos:
Operador Significado Equivalente SQL
E igual =
!E diferente !=
B anterior <
BE anterior ou igual <=
A posterior >
AE posterior ou igual >=
IS é IS NULL
!IS não é IS NOT NULL
IN contido IN (1, 2, …)
!IN não contido NOT IN (1, 2, …)
L like LIKE "valor"
!L not like NOT LIKE "valor"
LL left-like LIKE "%valor"
!LL not left-like NOT LIKE "%valor"
RL right-like LIKE "valor%"
!RL not right-like NOT LIKE "valor%"
LRL left+right like LIKE "%valor%"
!LRL not left+right like NOT LIKE "%valor%"
S busca busca por termo em uma ou mais colunas

Múltiplos valores

Operadores que aceitam múltiplos valores devem ser configurados em sequência:

q[coluna][IN]=1&q[coluna][]=2&q[coluna][]=3

Gera coluna IN (1, 2, 3).

Filtro NULL

q[coluna][IS]=null

Ordenação — o[coluna]=direção

o[coluna]=direção
  • coluna — coluna pela qual ordenar.
  • direção — ASC / asc / 1 para ascendente, DESC / desc / 0 para descendente.

Paginação — e=entries&p=page

Parâmetro Default Observações
e (entries) 20 Itens por página. Máximo 1000. 0 significa sem limite.
p (page) 1 Mínimo 1.

Exemplos

Faixa de datas

A mesma coluna aceita dois operadores na mesma consulta — é assim que se monta um intervalo:

GET /api/register/customer?q[createdAt][AE]=2026-08-01 00:00:00&q[createdAt][BE]=2026-08-31 23:59:59

Gera createdAt >= '2026-08-01 00:00:00' AND createdAt <= '2026-08-31 23:59:59'.

Cuidado com a data sem hora no BE. q[createdAt][BE]=2026-08-31 significa 2026-08-31 00:00:00 — tudo que aconteceu durante o dia 31 fica de fora. Ou vá até 23:59:59, ou use B (menor que) no dia seguinte:

q[createdAt][AE]=2026-08-01&q[createdAt][B]=2026-09-01

Um lado só também vale, quando o intervalo é aberto:

q[order_date][AE]=2026-08-01     → de 1º de agosto em diante
q[order_date][B]=2026-08-01      → antes de 1º de agosto

Lembre de aplicar URL-encode nos valores: o espaço vira %20 (ou +), e 2026-08-01 00:00:00 vira 2026-08-01%2000%3A00%3A00.

Cliente por e-mail exato

GET /api/register/customer?q[email][E]=maria@exemplo.com

Buscar cliente é isto — a listagem filtrada. Não use create nem get-or-create para consultar: eles escrevem, e criam o cliente que você só queria procurar.

Um trecho do texto

GET /api/register/customer?q[name][LRL]=silva

LRL é "contém" (LIKE '%silva%'). Como casa qualquer pedaço, q[email][LRL]=x@gmail.com também traz maria.mx@gmail.com — para duplicidade real, use E.

Buscar em várias colunas de uma vez

GET /api/register/customer?q[name;email][S]=maria silva

O termo é quebrado por espaço: cada palavra precisa aparecer em pelo menos uma das colunas. Palavras combinam com E, colunas com OU.

Vários valores na mesma coluna

GET /api/order/data?q[status][IN]=completed&q[status][]=shipped

Preenchido ou vazio

q[canceledAt][IS]=null      → só os não cancelados
q[canceledAt][!IS]=null     → só os cancelados

Tudo junto

GET /api/order/data?q[status][E]=completed&q[order_date][AE]=2026-08-01&q[order_date][B]=2026-09-01&o[order_date]=desc&e=50&p=2

Segunda página de 50 pedidos concluídos em agosto/2026, dos mais novos para os mais antigos.

Antes de sair filtrando

  • Coluna não filtrável é ignorada em silêncio. Alguns recursos limitam quais colunas aceitam filtro; se você mandar outra, ela é descartada sem erro — e a resposta volta sem aquele filtro, com mais linhas do que você esperava. Confirme o resultado em vez de assumir.
  • Sem operador é igualdade: q[status]=completed faz o mesmo que q[status][E]=completed.
  • O nome da coluna muda por serviço. É createdAt no register e order_date / createAt no order — use o mesmo nome que aparece na resposta do endpoint.
  • e=0 (ou e=all) desliga o limite. Em base grande isso é uma resposta enorme e uma consulta cara; prefira paginar.