Afiliados
Buscar Afiliados
Aprenda a buscar afiliados e exibir as informações completas usando GET /stores//affiliates.
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:- Entre as regras
commissionRulesdo 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.
- Vence a regra de menor
positionentre as que casaram. - Se nenhuma outra casar, a
DEFAULT(maiorposition) é o percentual padrão do afiliado.
A validação dotargetIdacontece no POST/PUT: paraPRODUCT,CATEGORYeCOUPONele precisa existir na loja. Regras cujotargetfoi removido depois são ignoradas na resolução, sem afetar a venda.
🔐 Autenticação
- Rota privada.
- Requer header
Authorizationcom 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 depage:
- 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:
cursorepagenão podem ser usados juntos (400 INVALID_PAGINATION).nextCursor: nullcomhasMore: falseindicam o fim da lista (a API responde200com 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 (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 (id,name,emailinválido ou maior que 120 caracteres,code,status,from,tooustoreId)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 juntos401 API_KEY_NOT_PROVIDED→ headerAuthorizationnão enviado401 INVALID_API_KEY→ API key inválida401 UNAUTHENTICATED→ usuário não autenticado403 USER_DISABLED→ usuário desativado403 NO_ACTIVE_SUBSCRIPTION→ sem plano ativo404 STORE_NOT_FOUND→ loja não encontrada404 AFFILIATE_NOT_FOUND→idinformado não encontrado (aplica-se apenas ao modo offset, semcursor)429 RATE_LIMIT_EXCEEDED→ limite de requisições por minuto excedido500 INTERNAL_SERVER_ERROR→ erro interno503 SERVICE_UNAVAILABLE→ serviço indisponível