Skip to main content
POST
/
v1
/
affiliates
Criar Afiliado
curl --request POST \
  --url https://api.affiliatus.io/v1/affiliates \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "email": "<string>",
  "password": "<string>",
  "name": "<string>",
  "phone": "<string>",
  "referralId": "<string>"
}
'
{
  "id": 123,
  "name": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "referralId": "<string>",
  "status": "<string>",
  "createdAt": "<string>",
  "totalConversions": 123,
  "totalCommissions": 123,
  "totalPaid": 123
}

​
Endpoint

POST https://api.affiliatus.io/v1/affiliates
Este endpoint permite criar um novo afiliado associado à campanha da sua API Key.
Auto-geração de Referral ID: Se você não fornecer um referralId, o sistema gerará automaticamente um código único de 8 caracteres alfanuméricos.

​
Autenticação

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

​
Body Parameters

​
email
string
required
E-mail do afiliado. Deve ser único dentro da campanha.
​
password
string
required
Senha para o afiliado acessar o portal. Mínimo de 6 caracteres.
​
name
string
Nome completo do afiliado
​
phone
string
Telefone de contato do afiliado
​
referralId
string
Código de referência único para rastreamento. Se não fornecido, será gerado automaticamente.Regras:
  • Deve ser único globalmente (não apenas na campanha)
  • Alfanumérico (A-Z, 0-9)
  • Recomendado: 4-12 caracteres

​
Response

​
id
number
ID único do afiliado criado
​
name
string
Nome do afiliado
​
email
string
E-mail do afiliado
​
phone
string
Telefone do afiliado
​
referralId
string
Código de referência único
​
status
string
Status do afiliado (pending, active ou inactive)
​
createdAt
string
Data de criação (ISO 8601)
​
totalConversions
number
Número total de conversões (sempre 0 para novos afiliados)
​
totalCommissions
number
Valor total de comissões em BRL
​
totalPaid
number
Valor total já pago ao afiliado em BRL

​
Exemplos

​
Criar Afiliado Completo

curl -X POST https://api.affiliatus.io/v1/affiliates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sua_api_key_aqui" \
  -d '{
    "name": "João Silva",
    "email": "joao@example.com",
    "phone": "+55 11 99999-9999",
    "referralId": "JOAO123",
    "password": "senha_segura_123"
  }'

​
Resposta de Sucesso (201 Created)

{
  "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": 0,
  "totalCommissions": 0,
  "totalPaid": 0
}

​
Criar Afiliado Mínimo (Auto-gerar Referral ID)

curl -X POST https://api.affiliatus.io/v1/affiliates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sua_api_key_aqui" \
  -d '{
    "email": "maria@example.com",
    "password": "senha123"
  }'

​
Resposta de Sucesso (Referral ID gerado)

{
  "id": 124,
  "email": "maria@example.com",
  "referralId": "A7K9M2X5",
  "status": "active",
  "createdAt": "2024-01-15T10:35:00.000Z",
  "totalConversions": 0,
  "totalCommissions": 0,
  "totalPaid": 0
}

​
Erros

​
400 - Dados Inválidos

{
  "statusCode": 400,
  "message": [
    "email must be a valid email",
    "password must be at least 6 characters long"
  ],
  "error": "Bad Request"
}
Solução: Corrija os dados conforme as mensagens de erro.

​
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 e se a chave está ativa.

​
403 - Limite Excedido

{
  "statusCode": 403,
  "message": "Affiliate limit exceeded: Affiliate limit reached for starter plan. Current: 50/50",
  "error": "Forbidden"
}
Solução: Faça upgrade do seu plano ou remova afiliados inativos.

​
409 - E-mail ou Referral ID Não Disponível

{
  "statusCode": 409,
  "message": "Email is not available",
  "error": "Conflict"
}
ou 
{
  "statusCode": 409,
  "message": "Referral ID is not available",
  "error": "Conflict"
}
Solução: Use um e-mail ou referralId diferente.
Segurança: As mensagens não revelam se o conflito é dentro da sua campanha ou em outra campanha.

​
429 - Rate Limit

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

​
Validações

  • Obrigatório
  • Deve ser um e-mail válido
  • Único por campanha
  • Obrigatória
  • Mínimo de 6 caracteres
  • Será armazenada com hash bcrypt (segura)
  • Opcional (auto-gerado se não fornecido)
  • Único globalmente
  • Alfanumérico (A-Z, 0-9)
  • Case-insensitive para validação
  • Opcionais
  • Podem ser atualizados posteriormente

​
Próximos Passos

Listar Afiliados

Consulte todos os afiliados criados

Enviar Conversões

Rastreie conversões dos afiliados

Atualizar Afiliado

Edite informações do afiliado

Dashboard

Visualize no dashboard