Skip to main content

Bem-vindo à API do Affiliatus

A API do Affiliatus permite que você integre seu sistema de afiliados diretamente com seu backend, possibilitando enviar conversões, gerenciar afiliados e acessar métricas programaticamente.

Base URL

https://api.affiliatus.io
Ambiente de produção:
  • Base URL: https://api.affiliatus.io
  • Versão: v1 (atual)

Autenticação

Todas as requisições à API requerem autenticação via API Key.

Como Obter sua API Key

  1. Acesse o Dashboard do Affiliatus
  2. Vá em ConfiguraçõesAPI Keys
  3. Clique em “Nova API Key”
  4. Copie a chave (será exibida apenas uma vez!)

Enviando a API Key

Inclua sua API key no header X-API-Key de todas as requisições:
X-API-Key: sua_api_key_aqui
Segurança: Nunca exponha sua API key no frontend ou em repositórios públicos. Use variáveis de ambiente ou gerenciadores de secrets.

Rate Limiting

A API possui limites de requisições para garantir estabilidade:
EndpointLimitePeríodo
/v1/events70 requisiçõespor minuto
/v1/sdk/events70 requisiçõespor minuto
Outros endpoints100 requisiçõespor minuto
Headers de resposta:
X-RateLimit-Limit: 70
X-RateLimit-Remaining: 65
X-RateLimit-Reset: 1640000000
Resposta quando limite excedido (429):
{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests",
  "error": "Too Many Requests"
}
Implemente retry com exponential backoff para lidar com rate limits de forma elegante.

Formatos de Dados

Request

  • Content-Type: application/json
  • Encoding: UTF-8
  • Date Format: ISO 8601 (2024-01-15T10:30:00Z)

Response

Todas as respostas são em formato JSON:
{
  "success": true,
  "data": {},
  "message": "Optional success message"
}

Códigos de Status HTTP

CódigoDescriçãoUso
200OKRequisição bem-sucedida
201CreatedRecurso criado com sucesso
400Bad RequestDados inválidos ou faltando
401UnauthorizedAPI key inválida ou ausente
403ForbiddenAPI key revogada ou sem permissão
404Not FoundRecurso não encontrado
429Too Many RequestsRate limit excedido
500Internal Server ErrorErro no servidor

Erros

Estrutura de Erro

{
  "statusCode": 400,
  "message": "Validation error message",
  "error": "Bad Request"
}

Erros Comuns

401 - API Key Inválida

{
  "statusCode": 401,
  "message": "API Key is required",
  "error": "Unauthorized"
}
Solução: Verifique se o header X-API-Key está presente e correto.

403 - API Key Revogada

{
  "statusCode": 403,
  "message": "API Key is revoked or inactive",
  "error": "Forbidden"
}
Solução: Crie uma nova API key no dashboard.

400 - Dados Inválidos

{
  "statusCode": 400,
  "message": [
    "order_value must be a positive number",
    "affiliate_id is required"
  ],
  "error": "Bad Request"
}
Solução: Verifique se todos os campos obrigatórios estão presentes e válidos.

Endpoints Disponíveis

Enviar Eventos

Envie conversões e outros eventos de rastreamento via POST

Exemplo Rápido

Enviar uma Conversão

curl -X POST https://api.affiliatus.io/v1/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sua_api_key_aqui" \
  -d '{
    "events": [{
      "event_type": "conversion",
      "campaign_id": "abc-123-def",
      "affiliate_id": "JOAO1",
      "properties": {
        "order_id": "ORDER-12345",
        "order_value": 99.90
      }
    }]
  }'
Resposta (200 OK):
{
  "success": true
}

SDKs e Bibliotecas

Atualmente, a API suporta requisições HTTP diretas em qualquer linguagem. Exemplos disponíveis:
  • Node.js (Fetch, Axios)
  • PHP (cURL)
  • Python (Requests)
  • Ruby (Net::HTTP)
  • Go (net/http)
Veja exemplos completos na documentação de integração.

Versionamento

A API segue versionamento semântico. A versão atual é v1. Breaking changes serão comunicadas com antecedência e uma nova versão será disponibilizada.

Suporte

Precisa de ajuda?

Próximos Passos