Skip to main content
GET
/
v1
/
affiliates
Listar Afiliados
curl --request GET \
  --url https://api.affiliatus.io/v1/affiliates \
  --header 'X-API-Key: <x-api-key>'
{
  "affiliates": [
    {
      "id": 123,
      "name": "<string>",
      "email": "<string>",
      "phone": "<string>",
      "referralId": "<string>",
      "status": "<string>",
      "createdAt": "<string>",
      "totalConversions": 123,
      "totalCommissions": 123,
      "totalPaid": 123
    }
  ],
  "total": 123,
  "page": 123,
  "limit": 123,
  "totalPages": 123
}

​
Endpoint

GET https://api.affiliatus.io/v1/affiliates
Este endpoint retorna uma lista paginada de todos os afiliados associados à campanha da sua API Key.
Performance: A API retorna até 100 afiliados por requisição. Use paginação para grandes listas.

​
Autenticação

​
X-API-Key
string
required
Sua API key obtida no dashboard em Configurações → API Keys

​
Query Parameters

​
status
string
Filtrar por status do afiliadoValores possíveis:
  • pending - Apenas afiliados aguardando aprovação
  • active - Apenas afiliados ativos
  • inactive - Apenas afiliados inativos
Se não fornecido, retorna todos os status.
​
search
string
Buscar por nome, e-mail ou referralIdA busca é case-insensitive e busca correspondências parciais.Exemplo: search=joao encontra “João Silva”, “joao@example.com”, “JOAO123”
​
page
number
default:"1"
Número da página para paginação (começa em 1)
​
limit
number
default:"50"
Número de afiliados por páginaLimites:
  • Mínimo: 1
  • Máximo: 100
  • Padrão: 50

​
Response

​
affiliates
array
Array de objetos de afiliados
​
total
number
Número total de afiliados (sem paginação)
​
page
number
Página atual
​
limit
number
Limite por página
​
totalPages
number
Número total de páginas

​
Exemplos

​
Listar Todos os Afiliados

curl -X GET "https://api.affiliatus.io/v1/affiliates" \
  -H "X-API-Key: sua_api_key_aqui"

​
Resposta de Sucesso (200 OK)

{
  "affiliates": [
    {
      "id": 123,
      "name": "João Silva",
      "email": "joao@example.com",
      "phone": "+55 11 99999-9999",
      "referralId": "JOAO123",
      "status": "active",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "totalConversions": 45,
      "totalCommissions": 2500.00,
      "totalPaid": 1200.00
    },
    {
      "id": 124,
      "name": "Maria Santos",
      "email": "maria@example.com",
      "phone": "+55 21 98888-8888",
      "referralId": "MARIA456",
      "status": "active",
      "createdAt": "2024-01-16T14:20:00.000Z",
      "totalConversions": 32,
      "totalCommissions": 1800.00,
      "totalPaid": 800.00
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 50,
  "totalPages": 1
}

​
Filtrar por Status

curl -X GET "https://api.affiliatus.io/v1/affiliates?status=active" \
  -H "X-API-Key: sua_api_key_aqui"

​
Buscar por Nome ou E-mail

curl -X GET "https://api.affiliatus.io/v1/affiliates?search=joao" \
  -H "X-API-Key: sua_api_key_aqui"

​
Paginação

# Página 2, 20 afiliados por página
curl -X GET "https://api.affiliatus.io/v1/affiliates?page=2&limit=20" \
  -H "X-API-Key: sua_api_key_aqui"

​
Combinar Filtros

# Afiliados ativos que contenham "silva" no nome, página 1, 10 por página
curl -X GET "https://api.affiliatus.io/v1/affiliates?status=active&search=silva&page=1&limit=10" \
  -H "X-API-Key: sua_api_key_aqui"

​
Erros

​
401 - API Key Inválida

{
  "statusCode": 401,
  "message": "Invalid or inactive API Key",
  "error": "Unauthorized"
}
Solução: Verifique se o header X-API-Key está correto.

​
400 - Parâmetros Inválidos

{
  "statusCode": 400,
  "message": [
    "limit must not be greater than 100"
  ],
  "error": "Bad Request"
}
Solução: Ajuste os parâmetros de acordo com os limites.

​
429 - Rate Limit

{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests",
  "error": "Too Many Requests"
}
Solução: Aguarde 60 segundos.

​
Dicas de Uso

Para grandes listas, use limit=100 e navegue pelas páginas. Isso otimiza a performance e reduz o tempo de resposta.
O parâmetro search busca em nome, e-mail e referralId simultaneamente. Use-o para encontrar afiliados rapidamente.
Use status=pending para revisar cadastros aguardando aprovação, status=active para listar afiliados que podem gerar conversões, ou status=inactive para revisar afiliados pausados.
Você pode combinar status, search, page e limit para buscas muito específicas.
Se sua aplicação lista afiliados frequentemente, considere cachear os resultados por alguns minutos para reduzir chamadas à API.

​
Próximos Passos

Consultar Afiliado

Veja detalhes de um afiliado específico

Criar Afiliado

Adicione um novo afiliado

Atualizar Afiliado

Edite informações de um afiliado

Dashboard

Visualize no dashboard