Pagamentos
Filtrar Pagamentos
Aprenda a filtrar pagamentos por campos do pagamento e por metadata usando o endpoint GET /stores//payments/filter.
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 headerAuthorization 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 depage. O cursor é suportado somente quando sortBy=createdAt (padrão):
- Faça a primeira chamada sem
cursor. - Se
hasMorefortrue, a resposta traz o camponextCursor. - Envie esse
nextCursorno parâmetrocursorda próxima requisição para buscar a página seguinte.
nextCursor, hasMore e limit (sem total/totalPages):
cursorepagenão podem ser usados juntos (400 INVALID_PAGINATION).- Usar
cursorcomsortBydiferente decreatedAtretorna400 INVALID_CURSOR_SORT. nextCursor: nullcomhasMore: falseindicam o fim da lista (a API responde200com array vazio).- Filtros de metadata muito amplos continuam podendo retornar
422 FILTER_TOO_BROAD.
✅ Exemplo de requisição
🧠 Exemplo para metadata aninhada
Filtrar pormetadata.items[0].product.sold = 19:
📦 Resposta de sucesso (200)
A primeira chamada (semcursor) já retornanextCursorehasMorena 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→limitfora do intervalo permitido (1a100)400 INVALID_PAGINATION_PAGE→pageinválida400 INVALID_PAGINATION_CURSOR→cursorinválido ou malformado400 INVALID_PAGINATION→pageecursorutilizados juntos400 INVALID_CURSOR_SORT→cursorusado comsortBydiferente decreatedAt401 API_KEY_NOT_PROVIDED→ headerAuthorizationnão enviado401 INVALID_API_KEY→ API key inválida401 UNAUTHENTICATED→ usuário não autenticado403 USER_DISABLED→ usuário desativado ou removido403 NO_ACTIVE_SUBSCRIPTION→ plano inativo ou expirado404 STORE_NOT_FOUND→ loja não encontrada ou não pertence à conta422 FILTER_TOO_BROAD→ filtro por metadata muito amplo; refinemetadataKey/metadataValue429 RATE_LIMIT_EXCEEDED→ limite de requisições por minuto do plano excedido500 INTERNAL_SERVER_ERROR→ erro interno503 SERVICE_UNAVAILABLE→ serviço temporariamente indisponível