Skip to main content
POST
/
v1
/
events
Enviar Eventos
curl --request POST \
  --url https://api.affiliatus.io/v1/events \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "batch": true,
  "events": [
    {
      "event_type": "<string>",
      "campaign_id": "<string>",
      "affiliate_id": "<string>",
      "session_id": "<string>",
      "properties": {
        "order_id": "<string>",
        "order_value": 123,
        "url": "<string>",
        "product": "<string>",
        "customer_email": "<string>",
        "customer_name": "<string>",
        "timestamp": "<string>"
      },
      "device_info": {
        "user_agent": "<string>",
        "ip": "<string>",
        "language": "<string>",
        "screen_width": 123,
        "screen_height": 123
      }
    }
  ]
}
'
{
  "success": true
}

​
Endpoint

POST https://api.affiliatus.io/v1/events
Este endpoint permite enviar eventos de rastreamento (conversões, leads, page views) diretamente do seu backend.
Endpoint Flexível: Este endpoint requer apenas event_type, campaign_id e affiliate_id. Os campos session_id, properties e device_info são opcionais (exceto para conversões que precisam de order_id e order_value em properties).

​
Autenticação

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

​
Body Parameters

​
batch
boolean
default:"false"
Indica se está enviando múltiplos eventos em lote
​
events
array
required
Array de eventos a serem processados

​
Response

​
success
boolean
Indica se a operação foi bem-sucedida

​
Exemplos

​
Enviar uma Conversão (Mínimo)

curl -X POST https://api.affiliatus.io/v1/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sua_api_key_aqui" \
  -d '{
    "batch": true,
    "events": [{
      "event_type": "conversion",
      "campaign_id": "abc-123-def",
      "affiliate_id": "JOAO1",
      "properties": {
        "order_id": "ORDER-12345",
        "order_value": 99.90
      }
    }]
  }'
Campos Opcionais: Você pode adicionar campos extras como product, customer_email, url, etc. em properties conforme necessário. O endpoint é flexível e aceita qualquer campo adicional.

​
Resposta de Sucesso

{
  "success": true
}

​
Enviar Múltiplas Conversões (Batch)

curl -X POST https://api.affiliatus.io/v1/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sua_api_key_aqui" \
  -d '{
    "batch": true,
    "events": [
      {
        "event_type": "conversion",
        "campaign_id": "abc-123-def",
        "affiliate_id": "JOAO1",
        "properties": {
          "order_id": "ORDER-001",
          "order_value": 99.90
        }
      },
      {
        "event_type": "conversion",
        "campaign_id": "abc-123-def",
        "affiliate_id": "MARIA2",
        "properties": {
          "order_id": "ORDER-002",
          "order_value": 149.90
        }
      }
    ]
  }'

​
Erros

​
401 - API Key Inválida

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

​
400 - Dados Inválidos

{
  "statusCode": 400,
  "message": [
    "order_value must be a positive number"
  ],
  "error": "Bad Request"
}
Solução: Corrija os dados conforme a mensagem de erro.

​
403 - Limite Excedido

{
  "statusCode": 403,
  "message": "Conversion limit exceeded: Monthly conversion limit reached for starter plan. Current: 500/500",
  "error": "Forbidden"
}
Solução: Faça upgrade do plano ou aguarde o próximo ciclo.

​
429 - Rate Limit

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

​
Testando

​
Teste Rápido com cURL

curl -X POST https://api.affiliatus.io/v1/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_API_KEY" \
  -d '{
    "batch": true,
    "events": [{
      "event_type": "conversion",
      "campaign_id": "SEU_CAMPAIGN_ID",
      "affiliate_id": "TEST01",
      "properties": {
        "order_id": "TEST-'$(date +%s)'",
        "order_value": 1.00
      }
    }]
  }'

​
Testando Page View ou Lead (Sem Properties)

curl -X POST https://api.affiliatus.io/v1/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_API_KEY" \
  -d '{
    "batch": true,
    "events": [{
      "event_type": "page_view",
      "campaign_id": "SEU_CAMPAIGN_ID",
      "affiliate_id": "TEST01"
    }]
  }'

​
Verificar no Dashboard

Após enviar, verifique em Conversões no dashboard se a conversão apareceu com status Pendente.

​
Boas Práticas

Sempre envie um order_id único para cada conversão. O sistema ignora conversões duplicadas com mesmo order_id.
Para melhor performance, envie múltiplas conversões em uma única requisição usando batch: true.
Caso receba erro 429 ou 500, implemente retry com exponential backoff (1s, 2s, 4s…).
Verifique se order_value é positivo e se affiliate_id existe antes de enviar.
Mantenha logs de todas as requisições para facilitar troubleshooting.
O endpoint é flexível: envie apenas os campos que você tem disponível. Para conversões, apenas order_id e order_value são obrigatórios em properties.

​
Próximos Passos

Guia Completo

Veja exemplos em mais linguagens

Dashboard

Visualize suas conversões no dashboard

Criar API Key

Gere sua API key

Aprovar Conversões

Aprenda a gerenciar conversões