Pagos
Filtrar Pagos
Aprende a filtrar pagos por campos del pago y por metadata usando el endpoint GET /stores//payments/filter.
GET
Filter payments
📌 Endpoint
GET /stores/{storeId}/payments/filter
Filtra los pagos de una tienda con soporte de paginación, ordenación y filtros por metadata.
🔐 Autenticación
Ruta privada. Envía el headerAuthorization con tu API key y plan activo.
🧾 Parámetro de ruta
🔎 Query params
🔄 Paginación por cursor
Para listas grandes (más de ~100 elementos), prefiere la paginación por cursor en lugar depage. El cursor solo se soporta cuando sortBy=createdAt (por defecto):
- Realiza la primera llamada sin
cursor. - Si
hasMoreestrue, la respuesta trae el camponextCursor. - Envía ese
nextCursoren el parámetrocursorde la siguiente solicitud para buscar la página siguiente.
nextCursor, hasMore y limit (sin total/totalPages):
cursorypageno pueden usarse juntos (400 INVALID_PAGINATION).- Usar
cursorconsortBydistinto decreatedAtdevuelve400 INVALID_CURSOR_SORT. nextCursor: nullconhasMore: falseindican el fin de la lista (la API responde200con array vacío).- Los filtros de metadata muy amplios pueden seguir devolviendo
422 FILTER_TOO_BROAD.
✅ Ejemplo de solicitud
🧠 Ejemplo para metadata anidada
Filtrar pormetadata.items[0].product.sold = 19:
📦 Respuesta de éxito (200)
La primera llamada (sincursor) ya devuelvenextCursoryhasMoreen la paginación, permitiendo iniciar la paginación por cursor sin llamadas extras.
⚠️ Posibles errores
400 INVALID_DATA→ parámetros inválidos (incluidas fechas que no estén en formato RFC3339/ISO-8601)400 INVALID_PAGINATION_LIMIT→limitfuera del intervalo permitido (1a100)400 INVALID_PAGINATION_PAGE→pageinválida400 INVALID_PAGINATION_CURSOR→cursorinválido o malformado400 INVALID_PAGINATION→pageycursorusados juntos400 INVALID_CURSOR_SORT→cursorusado consortBydistinto decreatedAt401 API_KEY_NOT_PROVIDED→ headerAuthorizationno enviado401 INVALID_API_KEY→ API key inválida401 UNAUTHENTICATED→ usuario no autenticado403 USER_DISABLED→ usuario desactivado o eliminado403 NO_ACTIVE_SUBSCRIPTION→ plan inactivo o expirado404 STORE_NOT_FOUND→ tienda no encontrada o no pertenece a la cuenta422 FILTER_TOO_BROAD→ filtro por metadata muy amplio; refinemetadataKey/metadataValue429 RATE_LIMIT_EXCEEDED→ límite de solicitudes por minuto del plan excedido500 INTERNAL_SERVER_ERROR→ error interno503 SERVICE_UNAVAILABLE→ servicio temporalmente no disponible