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áticaq[], 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/1para ascendente,DESC/desc/0para 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-31significa2026-08-31 00:00:00— tudo que aconteceu durante o dia 31 fica de fora. Ou vá até23:59:59, ou useB(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]=completedfaz o mesmo queq[status][E]=completed. - O nome da coluna muda por serviço. É
createdAtno register eorder_date/createAtno order — use o mesmo nome que aparece na resposta do endpoint. e=0(oue=all) desliga o limite. Em base grande isso é uma resposta enorme e uma consulta cara; prefira paginar.