> ## Documentation Index
> Fetch the complete documentation index at: https://docs.affiliatus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar Afiliado

> Crie um novo afiliado para sua campanha

## Endpoint

```
POST https://api.affiliatus.io/v1/affiliates
```

Este endpoint permite criar um novo afiliado associado à campanha da sua API Key.

<Info>
  **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.
</Info>

***

## Autenticação

<ParamField header="X-API-Key" type="string" required>
  Sua API key obtida no dashboard em Configurações → API Keys
</ParamField>

***

## Body Parameters

<ParamField body="email" type="string" required>
  E-mail do afiliado. Deve ser único dentro da campanha.
</ParamField>

<ParamField body="password" type="string" required>
  Senha para o afiliado acessar o portal. Mínimo de 6 caracteres.
</ParamField>

<ParamField body="name" type="string">
  Nome completo do afiliado
</ParamField>

<ParamField body="phone" type="string">
  Telefone de contato do afiliado
</ParamField>

<ParamField body="referralId" type="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
</ParamField>

***

## Response

<ResponseField name="id" type="number">
  ID único do afiliado criado
</ResponseField>

<ResponseField name="name" type="string">
  Nome do afiliado
</ResponseField>

<ResponseField name="email" type="string">
  E-mail do afiliado
</ResponseField>

<ResponseField name="phone" type="string">
  Telefone do afiliado
</ResponseField>

<ResponseField name="referralId" type="string">
  Código de referência único
</ResponseField>

<ResponseField name="status" type="string">
  Status do afiliado (`pending`, `active` ou `inactive`)
</ResponseField>

<ResponseField name="createdAt" type="string">
  Data de criação (ISO 8601)
</ResponseField>

<ResponseField name="totalConversions" type="number">
  Número total de conversões (sempre 0 para novos afiliados)
</ResponseField>

<ResponseField name="totalCommissions" type="number">
  Valor total de comissões em BRL
</ResponseField>

<ResponseField name="totalPaid" type="number">
  Valor total já pago ao afiliado em BRL
</ResponseField>

***

## Exemplos

### Criar Afiliado Completo

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.affiliatus.io/v1/affiliates', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.AFFILIATUS_API_KEY,
    },
    body: JSON.stringify({
      name: 'João Silva',
      email: 'joao@example.com',
      phone: '+55 11 99999-9999',
      referralId: 'JOAO123',
      password: 'senha_segura_123'
    })
  });

  const affiliate = await response.json();
  console.log(affiliate);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.affiliatus.io/v1/affiliates',
      headers={
          'Content-Type': 'application/json',
          'X-API-Key': 'sua_api_key_aqui',
      },
      json={
          'name': 'João Silva',
          'email': 'joao@example.com',
          'phone': '+55 11 99999-9999',
          'referralId': 'JOAO123',
          'password': 'senha_segura_123'
      }
  )

  affiliate = response.json()
  print(affiliate)
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.affiliatus.io/v1/affiliates');

  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Content-Type: application/json',
      'X-API-Key: sua_api_key_aqui'
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      'name' => 'João Silva',
      'email' => 'joao@example.com',
      'phone' => '+55 11 99999-9999',
      'referralId' => 'JOAO123',
      'password' => 'senha_segura_123'
  ]));

  $response = curl_exec($ch);
  curl_close($ch);

  $affiliate = json_decode($response, true);
  print_r($affiliate);
  ```
</CodeGroup>

### Resposta de Sucesso (201 Created)

```json theme={null}
{
  "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)

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.affiliatus.io/v1/affiliates', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.AFFILIATUS_API_KEY,
    },
    body: JSON.stringify({
      email: 'maria@example.com',
      password: 'senha123'
    })
  });

  const affiliate = await response.json();
  console.log('Referral ID gerado:', affiliate.referralId);
  ```
</CodeGroup>

### Resposta de Sucesso (Referral ID gerado)

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "statusCode": 409,
  "message": "Email is not available",
  "error": "Conflict"
}
```

ou

```json theme={null}
{
  "statusCode": 409,
  "message": "Referral ID is not available",
  "error": "Conflict"
}
```

**Solução:** Use um e-mail ou referralId diferente.

<Note>
  **Segurança:** As mensagens não revelam se o conflito é dentro da sua campanha ou em outra campanha.
</Note>

***

### 429 - Rate Limit

```json theme={null}
{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests",
  "error": "Too Many Requests"
}
```

**Solução:** Aguarde 60 segundos antes de tentar novamente.

***

## Validações

<AccordionGroup>
  <Accordion title="E-mail">
    * **Obrigatório**
    * Deve ser um e-mail válido
    * Único por campanha
  </Accordion>

  <Accordion title="Senha">
    * **Obrigatória**
    * Mínimo de 6 caracteres
    * Será armazenada com hash bcrypt (segura)
  </Accordion>

  <Accordion title="Referral ID">
    * Opcional (auto-gerado se não fornecido)
    * Único globalmente
    * Alfanumérico (A-Z, 0-9)
    * Case-insensitive para validação
  </Accordion>

  <Accordion title="Nome e Telefone">
    * Opcionais
    * Podem ser atualizados posteriormente
  </Accordion>
</AccordionGroup>

***

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Listar Afiliados" icon="list" href="/api-reference/affiliates/list-affiliates">
    Consulte todos os afiliados criados
  </Card>

  <Card title="Enviar Conversões" icon="bolt" href="/api-reference/events/send-events">
    Rastreie conversões dos afiliados
  </Card>

  <Card title="Atualizar Afiliado" icon="edit" href="/api-reference/affiliates/update-affiliate">
    Edite informações do afiliado
  </Card>

  <Card title="Dashboard" icon="chart-line" href="https://app.affiliatus.io">
    Visualize no dashboard
  </Card>
</CardGroup>