Filtros e Paginação

Os endpoints de listagem da plataforma suportam filtragem via query string e paginação baseada em cursor, cujo os filtros são aplicados antes da paginação.

Filtros

Os endpoints de listagem aceitam filtros via query string. Os campos disponíveis variam por endpoint, mas o padrão de operadores é uniforme em toda a plataforma.

Formato

<campo>_<operador>=<valor>

Operadores suportados

Sufixo	Operador SQL	Descrição
_eq	=	Igual
_ne	<>	Diferente
_gt	>	Maior que
_lt	<	Menor que
_ge	>=	Maior ou igual
_le	<=	Menor ou igual
_lk	LIKE	Busca parcial (contém)
_in	IN	Lista de valores separados por vírgula

Regras

• Os nomes dos campos estarão descritos nos endpoints que fizer sentido.
• Para _in, os valores são separados por vírgula sem espaços.
• Múltiplos filtros podem ser combinados na mesma requisição.

Exemplos de filtros

Filtrar por status exato

curl https://yby-dev.positivolabs.com.br/v1/transactions \
  -H "Authorization: Bearer <access_token>" \
  -G \
  --data-urlencode "status_eq=APPROVED"

Filtrar por valor mínimo

curl https://yby-dev.positivolabs.com.br/v1/transactions \
  -H "Authorization: Bearer <access_token>" \
  -G \
  --data-urlencode "amount_gt=1000"

Filtrar por data a partir de

curl https://yby-dev.positivolabs.com.br/v1/transactions \
  -H "Authorization: Bearer <access_token>" \
  -G \
  --data-urlencode "created_at_ge=2025-01-01"

Busca parcial em texto

curl https://yby-dev.positivolabs.com.br/v1/merchants \
  -H "Authorization: Bearer <access_token>" \
  -G \
  --data-urlencode "merchant_name_lk=mercado"

Múltiplos valores (IN)

curl https://yby-dev.positivolabs.com.br/v1/transactions \
  -H "Authorization: Bearer <access_token>" \
  -G \
  --data-urlencode "status_in=APPROVED,PENDING"

---

Paginação

Todos os endpoints de listagem da plataforma utilizam paginação baseada em cursor (cursor-based pagination). Esse modelo é mais eficiente e consistente que paginação por offset, especialmente em conjuntos de dados que mudam com frequência.

Como funciona

O cursor é um token opaco retornado pela API na resposta. Para buscar a próxima página, basta reenviar esse token na próxima requisição. Quando a resposta retornar cursor: null, não há mais registros.

Parâmetros de Query

Parâmetro	Tipo	Padrão	Máximo	Descrição
cursor	string	—	—	Token retornado pela resposta anterior. Omitir na primeira página.
limit	integer	20	100	Quantidade de itens por página
order_by	string	—	—	Campo utilizado para ordenação (ex.: created_at)
sort	string	—	—	Direção da ordenação: ASC ou DESC

Estrutura da Resposta

Todos os endpoints paginados retornam o mesmo envelope:

Campo	Tipo	Descrição
metadata.cursor	string | null	Token para a próxima página. null indica última página.
metadata.limit	integer	Quantidade de itens retornados na página
data	array	Lista de registros da página atual

Regras

• O cursor é opaco — trate-o como uma caixa preta. Não o construa nem interprete manualmente.
• Omitir o parâmetro cursor equivale a buscar a primeira página.
• metadata.cursor: null na resposta indica que não há próxima página.
• O limite máximo é 100; o padrão é 20.

Primeira página

Request

curl https://yby-dev.positivolabs.com.br/v1/merchants \
  -H "Authorization: Bearer <access_token>" \
  -G \
  --data-urlencode "limit=20" \
  --data-urlencode "order_by=created_at" \
  --data-urlencode "sort=DESC"

Resposta

{
  "metadata": {
    "cursor": "d6uo5nc42nrc73gv867g",
    "limit": 20
  },
  "data": [
    { "id": "d6uo5nc42nrc73gv867g", "..." : "..." }
  ]
}

Próxima página

Request

curl https://yby-dev.positivolabs.com.br/v1/merchants \
  -H "Authorization: Bearer <access_token>" \
  -G \
  --data-urlencode "limit=20" \
  --data-urlencode "order_by=created_at" \
  --data-urlencode "sort=DESC" \
  --data-urlencode "cursor=d6uo5nc42nrc73gv867g"

Resposta — última página

{
  "metadata": {
    "cursor": null,
    "limit": 20
  },
  "data": [
    { "id": "d59gpddc93gc73jvje0g", "..." : "..." }
  ]
}