Pular para o conteúdo principal
GET
Filter payments

📌 Endpoint

GET /stores/{storeId}/payments/filter Filtra pagamentos de uma loja com suporte a paginação, ordenação e filtros por metadata.

🔐 Autenticação

Rota privada. Envie o header Authorization com sua API key e plano ativo.

🧾 Parâmetro de rota


🔎 Query params


🔄 Paginação por cursor

Para listas grandes (mais de ~100 itens), prefira paginação por cursor no lugar de page. O cursor é suportado somente quando sortBy=createdAt (padrão):
  1. Faça a primeira chamada sem cursor.
  2. Se hasMore for true, a resposta traz o campo nextCursor.
  3. Envie esse nextCursor no parâmetro cursor da próxima requisição para buscar a página seguinte.
No modo cursor, a paginação é retornada apenas com nextCursor, hasMore e limit (sem total/totalPages):
  • cursor e page não podem ser usados juntos (400 INVALID_PAGINATION).
  • Usar cursor com sortBy diferente de createdAt retorna 400 INVALID_CURSOR_SORT.
  • nextCursor: null com hasMore: false indicam o fim da lista (a API responde 200 com array vazio).
  • Filtros de metadata muito amplos continuam podendo retornar 422 FILTER_TOO_BROAD.

✅ Exemplo de requisição


🧠 Exemplo para metadata aninhada

Filtrar por metadata.items[0].product.sold = 19:

📦 Resposta de sucesso (200)

A primeira chamada (sem cursor) já retorna nextCursor e hasMore na paginação, permitindo iniciar a paginação por cursor sem chamadas extras.

⚠️ Possíveis erros

  • 400 INVALID_DATA → parâmetros inválidos (incluindo datas fora do formato RFC3339/ISO-8601)
  • 400 INVALID_PAGINATION_LIMIT → limit fora do intervalo permitido (1 a 100)
  • 400 INVALID_PAGINATION_PAGE → page inválida
  • 400 INVALID_PAGINATION_CURSOR → cursor inválido ou malformado
  • 400 INVALID_PAGINATION → page e cursor utilizados juntos
  • 400 INVALID_CURSOR_SORT → cursor usado com sortBy diferente de createdAt
  • 401 API_KEY_NOT_PROVIDED → header Authorization não enviado
  • 401 INVALID_API_KEY → API key inválida
  • 401 UNAUTHENTICATED → usuário não autenticado
  • 403 USER_DISABLED → usuário desativado ou removido
  • 403 NO_ACTIVE_SUBSCRIPTION → plano inativo ou expirado
  • 404 STORE_NOT_FOUND → loja não encontrada ou não pertence à conta
  • 422 FILTER_TOO_BROAD → filtro por metadata muito amplo; refine metadataKey/metadataValue
  • 429 RATE_LIMIT_EXCEEDED → limite de requisições por minuto do plano excedido
  • 500 INTERNAL_SERVER_ERROR → erro interno
  • 503 SERVICE_UNAVAILABLE → serviço temporariamente indisponível

Autorizações

Authorization
string
header
padrão:YOUR_API_KEY_HERE
obrigatório

Parâmetros de caminho

storeId
string
obrigatório
Required string length: 1 - 50

Parâmetros de consulta

page
integer
padrão:1
Intervalo obrigatório: x >= 1
limit
integer
padrão:20
Intervalo obrigatório: 1 <= x <= 100
cursor
string

Opaque cursor from previous page (do not combine with page; only valid when sortBy=createdAt).

id
string<uuid>
uuid
string<uuid>
name
string
email
string<email>
cpf
string
status
enum<string>
Opções disponíveis:
PENDING,
APPROVED,
REJECTED,
CANCELLED,
REFUNDED,
CHARGED_BACK,
EXPIRED
price
number
minPrice
number
maxPrice
number
coupon
boolean
gateway
enum<string>
Opções disponíveis:
MERCADOPAGO,
EFI_BANK,
ASAAS,
STRIPE
shipment
enum<string>
Opções disponíveis:
PENDING,
PREPARING,
SHIPPED,
DELIVERED,
RETURNED,
CANCELLED
createdAtFrom
string<date-time>
createdAtTo
string<date-time>
updatedAtFrom
string<date-time>
updatedAtTo
string<date-time>
productId
string<uuid>
metadataKey
string
metadataValue
string
sortBy
enum<string>
padrão:createdAt
Opções disponíveis:
createdAt,
updatedAt,
price,
name,
email
sortOrder
enum<string>
padrão:desc
Opções disponíveis:
asc,
desc

Resposta

Filter payments.

code
string
obrigatório
Exemplo:

"PAYMENTS_FILTERED"

payments
object[]
obrigatório
pagination
object
obrigatório