Pular para o conteúdo principal
GET
List affiliates

📌 Endpoint

GET /stores/{storeId}/affiliates Busca e filtra os afiliados da loja. Com statistics=true a resposta inclui as estatísticas (receita líquida — já descontadas as taxas da gateway —, vendas e cliques calculados na hora) e as métricas do período (from/to).

⚙️ Como a comissão é resolvida

Na hora da venda, a porcentagem é resolvida por item:
  1. Entre as regras commissionRules do afiliado, são consideradas as que casam com o item:
    • PRODUCT → o item é do produto (targetId);
    • CATEGORY → o item pertence à categoria (targetId);
    • COUPON → o cupom aplicado no pagamento é o (targetId);
    • DEFAULT → sempre casa com qualquer item.
  2. Vence a regra de menor position entre as que casaram.
  3. Se nenhuma outra casar, a DEFAULT (maior position) é o percentual padrão do afiliado.
A validação do targetId acontece no POST/PUT: para PRODUCT, CATEGORY e COUPON ele precisa existir na loja. Regras cujo target foi removido depois são ignoradas na resolução, sem afetar a venda.

🔐 Autenticação

  • Rota privada.
  • Requer header Authorization com sua API key e plano ativo.

🔎 Query params


🔄 Paginação por cursor

Para listas grandes (mais de ~100 itens), prefira paginação por cursor no lugar de page:
  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:
  • cursor e page não podem ser usados juntos (400 INVALID_PAGINATION).
  • nextCursor: null com hasMore: false indicam o fim da lista (a API responde 200 com array vazio).

✅ Exemplo de requisição — lista com filtros


✅ Exemplo de requisição — informações completas de um afiliado


📦 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 (id, name, email inválido ou maior que 120 caracteres, code, status, from, to ou storeId)
  • 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
  • 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
  • 403 NO_ACTIVE_SUBSCRIPTION → sem plano ativo
  • 404 STORE_NOT_FOUND → loja não encontrada
  • 404 AFFILIATE_NOT_FOUND → id informado não encontrado (aplica-se apenas ao modo offset, sem cursor)
  • 429 RATE_LIMIT_EXCEEDED → limite de requisições por minuto excedido
  • 500 INTERNAL_SERVER_ERROR → erro interno
  • 503 SERVICE_UNAVAILABLE → serviço 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

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>
Opções disponíveis:
ativo,
inativo
from
string

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

to
string

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

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).

statistics
boolean

Resposta

List affiliates.

code
string
obrigatório
Exemplo:

"AFFILIATES_FETCHED"

affiliates
object[]
obrigatório
pagination
object
obrigatório