Saltar al contenido principal
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:
  1. Entre las reglas commissionRules del 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.
  2. Vence la regla de menor position entre las que encajaron.
  3. Si ninguna otra encaja, la DEFAULT (mayor position) es el porcentaje por defecto del afiliado.
La validación de targetId ocurre en el POST/PUT: para PRODUCT, CATEGORY y COUPON debe existir en la tienda. Las reglas cuyo target se eliminó después son ignoradas en la resolución, sin afectar la venta.

🔐 Autenticación

  • Ruta privada.
  • Requiere el header Authorization con 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 de page:
  1. Haz la primera llamada sin cursor.
  2. Si hasMore es true, la respuesta trae el campo nextCursor.
  3. Envía ese nextCursor en el parámetro cursor de la siguiente solicitud para buscar la página siguiente.
En modo cursor, la paginación se devuelve solo con nextCursor, hasMore y limit:
  • cursor y page no pueden usarse juntos (400 INVALID_PAGINATION).
  • nextCursor: null con hasMore: false indican el fin de la lista (la API responde 200 con array vacío).

✅ Ejemplo de solicitud — lista con filtros


✅ Ejemplo de solicitud — información completa de un afiliado


📦 Respuesta exitosa (200)

La primera llamada (sin cursor) ya devuelve nextCursor y hasMore en la paginación, permitiendo iniciar la paginación por cursor sin llamadas extra.

⚠️ Posibles errores

  • 400 INVALID_DATA → parámetros inválidos (id, name, email inválido o mayor de 120 caracteres, code, status, from, to o storeId)
  • 400 INVALID_PAGINATION_LIMIT → limit fuera del intervalo permitido (1 a 100)
  • 400 INVALID_PAGINATION_PAGE → page inválida
  • 400 INVALID_PAGINATION_CURSOR → cursor inválido o malformado
  • 400 INVALID_PAGINATION → page y cursor utilizados juntos
  • 401 API_KEY_NOT_PROVIDED → header Authorization no enviado
  • 401 INVALID_API_KEY → API key inválida
  • 401 UNAUTHENTICATED → usuario no autenticado
  • 403 USER_DISABLED → usuario deshabilitado
  • 403 NO_ACTIVE_SUBSCRIPTION → sin plan activo
  • 404 STORE_NOT_FOUND → tienda no encontrada
  • 404 AFFILIATE_NOT_FOUND → id informado no encontrado (aplica solo en modo offset, sin cursor)
  • 429 RATE_LIMIT_EXCEEDED → límite de solicitudes por minuto excedido
  • 500 INTERNAL_SERVER_ERROR → error interno
  • 503 SERVICE_UNAVAILABLE → servicio no disponible

Autorizaciones

Authorization
string
header
predeterminado:YOUR_API_KEY_HERE
requerido

Parámetros de ruta

storeId
string
requerido
Required string length: 1 - 50

Parámetros de consulta

id
string
Maximum string length: 50
name
string
Maximum string length: 56
email
string<email>
Maximum string length: 120
code
string
Maximum string length: 50
status
enum<string>
Opciones disponibles:
ativo,
inativo
from
string

Start date filter (RFC3339 or YYYY-MM-DD).

to
string

End date filter (RFC3339 or YYYY-MM-DD).

page
integer
predeterminado:1
Rango requerido: x >= 1
limit
integer
predeterminado:20
Rango requerido: 1 <= x <= 100
cursor
string

Opaque cursor from previous page (do not combine with page).

statistics
boolean

Respuesta

List affiliates.

code
string
requerido
Ejemplo:

"AFFILIATES_FETCHED"

affiliates
object[]
requerido
pagination
object
requerido