Afiliados
Buscar Afiliados
Aprende a buscar afiliados y mostrar la información completa usando GET /stores//affiliates.
GET
List affiliates
📌 Endpoint
GET /stores/{storeId}/affiliates
Busca y filtra los afiliados de la tienda. Con statistics=true, la respuesta incluye las estadísticas (ingresos netos — ya descontadas las tasas de la pasarela de pago —, ventas y clics calculados en el momento) y las métricas del período (from/to).
⚙️ Cómo se resuelve la comisión
En el momento de la venta, el porcentaje se resuelve por ítem:- Entre las reglas
commissionRulesdel afiliado, se consideran las que encajan con el ítem:PRODUCT→ el ítem es el producto (targetId);CATEGORY→ el ítem pertenece a la categoría (targetId);COUPON→ el cupón aplicado al pago es (targetId);DEFAULT→ siempre encaja con cualquier ítem.
- Vence la regla de menor
positionentre las que encajaron. - Si ninguna otra encaja, la
DEFAULT(mayorposition) es el porcentaje por defecto del afiliado.
La validación detargetIdocurre en el POST/PUT: paraPRODUCT,CATEGORYyCOUPONdebe existir en la tienda. Las reglas cuyotargetse eliminó después son ignoradas en la resolución, sin afectar la venta.
🔐 Autenticación
- Ruta privada.
- Requiere el header
Authorizationcon tu API key y plan activo.
🔎 Parámetros de consulta
🔄 Paginación por cursor
Para listas grandes (más de ~100 ítems), prefiere la paginación por cursor en lugar depage:
- Haz 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:
cursorypageno pueden usarse juntos (400 INVALID_PAGINATION).nextCursor: nullconhasMore: falseindican el fin de la lista (la API responde200con array vacío).
✅ Ejemplo de solicitud — lista con filtros
✅ Ejemplo de solicitud — información completa de un afiliado
📦 Respuesta exitosa (200)
La primera llamada (sincursor) ya devuelvenextCursoryhasMoreen la paginación, permitiendo iniciar la paginación por cursor sin llamadas extra.
⚠️ Posibles errores
400 INVALID_DATA→ parámetros inválidos (id,name,emailinválido o mayor de 120 caracteres,code,status,from,toostoreId)400 INVALID_PAGINATION_LIMIT→limitfuera del intervalo permitido (1a100)400 INVALID_PAGINATION_PAGE→pageinválida400 INVALID_PAGINATION_CURSOR→cursorinválido o malformado400 INVALID_PAGINATION→pageycursorutilizados juntos401 API_KEY_NOT_PROVIDED→ headerAuthorizationno enviado401 INVALID_API_KEY→ API key inválida401 UNAUTHENTICATED→ usuario no autenticado403 USER_DISABLED→ usuario deshabilitado403 NO_ACTIVE_SUBSCRIPTION→ sin plan activo404 STORE_NOT_FOUND→ tienda no encontrada404 AFFILIATE_NOT_FOUND→idinformado no encontrado (aplica solo en modo offset, sincursor)429 RATE_LIMIT_EXCEEDED→ límite de solicitudes por minuto excedido500 INTERNAL_SERVER_ERROR→ error interno503 SERVICE_UNAVAILABLE→ servicio no disponible