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
      }
    }
  ]
}
'

import requests

url = "https://api.affiliatus.io/v1/events"

payload = {
    "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
            }
        }
    ]
}
headers = {
    "X-API-Key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
        }
      }
    ]
  })
};

fetch('https://api.affiliatus.io/v1/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.affiliatus.io/v1/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.affiliatus.io/v1/events"

	payload := strings.NewReader("{\n  \"batch\": true,\n  \"events\": [\n    {\n      \"event_type\": \"<string>\",\n      \"campaign_id\": \"<string>\",\n      \"affiliate_id\": \"<string>\",\n      \"session_id\": \"<string>\",\n      \"properties\": {\n        \"order_id\": \"<string>\",\n        \"order_value\": 123,\n        \"url\": \"<string>\",\n        \"product\": \"<string>\",\n        \"customer_email\": \"<string>\",\n        \"customer_name\": \"<string>\",\n        \"timestamp\": \"<string>\"\n      },\n      \"device_info\": {\n        \"user_agent\": \"<string>\",\n        \"ip\": \"<string>\",\n        \"language\": \"<string>\",\n        \"screen_width\": 123,\n        \"screen_height\": 123\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.affiliatus.io/v1/events")
  .header("X-API-Key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"batch\": true,\n  \"events\": [\n    {\n      \"event_type\": \"<string>\",\n      \"campaign_id\": \"<string>\",\n      \"affiliate_id\": \"<string>\",\n      \"session_id\": \"<string>\",\n      \"properties\": {\n        \"order_id\": \"<string>\",\n        \"order_value\": 123,\n        \"url\": \"<string>\",\n        \"product\": \"<string>\",\n        \"customer_email\": \"<string>\",\n        \"customer_name\": \"<string>\",\n        \"timestamp\": \"<string>\"\n      },\n      \"device_info\": {\n        \"user_agent\": \"<string>\",\n        \"ip\": \"<string>\",\n        \"language\": \"<string>\",\n        \"screen_width\": 123,\n        \"screen_height\": 123\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.affiliatus.io/v1/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"batch\": true,\n  \"events\": [\n    {\n      \"event_type\": \"<string>\",\n      \"campaign_id\": \"<string>\",\n      \"affiliate_id\": \"<string>\",\n      \"session_id\": \"<string>\",\n      \"properties\": {\n        \"order_id\": \"<string>\",\n        \"order_value\": 123,\n        \"url\": \"<string>\",\n        \"product\": \"<string>\",\n        \"customer_email\": \"<string>\",\n        \"customer_name\": \"<string>\",\n        \"timestamp\": \"<string>\"\n      },\n      \"device_info\": {\n        \"user_agent\": \"<string>\",\n        \"ip\": \"<string>\",\n        \"language\": \"<string>\",\n        \"screen_width\": 123,\n        \"screen_height\": 123\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true
}

POST

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
      }
    }
  ]
}
'

import requests

url = "https://api.affiliatus.io/v1/events"

payload = {
    "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
            }
        }
    ]
}
headers = {
    "X-API-Key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
        }
      }
    ]
  })
};

fetch('https://api.affiliatus.io/v1/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.affiliatus.io/v1/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.affiliatus.io/v1/events"

	payload := strings.NewReader("{\n  \"batch\": true,\n  \"events\": [\n    {\n      \"event_type\": \"<string>\",\n      \"campaign_id\": \"<string>\",\n      \"affiliate_id\": \"<string>\",\n      \"session_id\": \"<string>\",\n      \"properties\": {\n        \"order_id\": \"<string>\",\n        \"order_value\": 123,\n        \"url\": \"<string>\",\n        \"product\": \"<string>\",\n        \"customer_email\": \"<string>\",\n        \"customer_name\": \"<string>\",\n        \"timestamp\": \"<string>\"\n      },\n      \"device_info\": {\n        \"user_agent\": \"<string>\",\n        \"ip\": \"<string>\",\n        \"language\": \"<string>\",\n        \"screen_width\": 123,\n        \"screen_height\": 123\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.affiliatus.io/v1/events")
  .header("X-API-Key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"batch\": true,\n  \"events\": [\n    {\n      \"event_type\": \"<string>\",\n      \"campaign_id\": \"<string>\",\n      \"affiliate_id\": \"<string>\",\n      \"session_id\": \"<string>\",\n      \"properties\": {\n        \"order_id\": \"<string>\",\n        \"order_value\": 123,\n        \"url\": \"<string>\",\n        \"product\": \"<string>\",\n        \"customer_email\": \"<string>\",\n        \"customer_name\": \"<string>\",\n        \"timestamp\": \"<string>\"\n      },\n      \"device_info\": {\n        \"user_agent\": \"<string>\",\n        \"ip\": \"<string>\",\n        \"language\": \"<string>\",\n        \"screen_width\": 123,\n        \"screen_height\": 123\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.affiliatus.io/v1/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"batch\": true,\n  \"events\": [\n    {\n      \"event_type\": \"<string>\",\n      \"campaign_id\": \"<string>\",\n      \"affiliate_id\": \"<string>\",\n      \"session_id\": \"<string>\",\n      \"properties\": {\n        \"order_id\": \"<string>\",\n        \"order_value\": 123,\n        \"url\": \"<string>\",\n        \"product\": \"<string>\",\n        \"customer_email\": \"<string>\",\n        \"customer_name\": \"<string>\",\n        \"timestamp\": \"<string>\"\n      },\n      \"device_info\": {\n        \"user_agent\": \"<string>\",\n        \"ip\": \"<string>\",\n        \"language\": \"<string>\",\n        \"screen_width\": 123,\n        \"screen_height\": 123\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "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

string

required

Sua API key obtida no dashboard em Configurações → API Keys

Body Parameters

boolean

default:"false"

Indica se está enviando múltiplos eventos em lote

array

required

Array de eventos a serem processados

Show Event Object

string

required

Tipo do evento. Valores possíveis:

conversion - Venda realizada
lead - Lead capturado
page_view - Visualização de página

string

required

ID público da campanha (ex: abc-123-def)

string

required

Código do afiliado (referralId, ex: JOAO1)

string

ID único da sessão do usuário (opcional)

object

Propriedades específicas do evento. Obrigatório apenas para conversões (com order_id e order_value)

Show Conversion Properties

string

required

ID único do pedido

number

required

Valor da venda em reais (ex: 99.90)

string

URL da página onde ocorreu a conversão

string

Nome do produto ou plano vendido

string

E-mail do cliente

string

Nome do cliente

string

Timestamp ISO 8601 (ex: 2024-01-15T10:30:00Z)

object

Informações do dispositivo (totalmente opcional para integrações backend)

Show Device Info Fields

string

User agent do navegador

string

Endereço IP do cliente

string

Idioma do navegador (ex: pt-BR)

number

Largura da tela em pixels

number

Altura da tela em pixels

Response

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
      }
    }]
  }'

const response = await fetch('https://api.affiliatus.io/v1/events', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.AFFILIATUS_API_KEY,
  },
  body: JSON.stringify({
    batch: true,
    events: [{
      event_type: 'conversion',
      campaign_id: 'abc-123-def',
      affiliate_id: 'JOAO1',
      properties: {
        order_id: 'ORDER-12345',
        order_value: 99.90
      }
    }]
  })
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    'https://api.affiliatus.io/v1/events',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'sua_api_key_aqui',
    },
    json={
        'batch': True,
        'events': [{
            'event_type': 'conversion',
            'campaign_id': 'abc-123-def',
            'affiliate_id': 'JOAO1',
            'properties': {
                'order_id': 'ORDER-12345',
                'order_value': 99.90
            }
        }]
    }
)

print(response.json())

<?php
$ch = curl_init('https://api.affiliatus.io/v1/events');

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([
    'batch' => true,
    'events' => [[
        'event_type' => 'conversion',
        'campaign_id' => 'abc-123-def',
        'affiliate_id' => 'JOAO1',
        'properties' => [
            'order_id' => 'ORDER-12345',
            'order_value' => 99.90
        ]
    ]]
]));

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

echo $response;

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
        }
      }
    ]
  }'

const 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
    }
  }
];

const response = await fetch('https://api.affiliatus.io/v1/events', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.AFFILIATUS_API_KEY,
  },
  body: JSON.stringify({ batch: true, events })
});

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

Use order_id único

Sempre envie um order_id único para cada conversão. O sistema ignora conversões duplicadas com mesmo order_id.

Envie em lote quando possível

Para melhor performance, envie múltiplas conversões em uma única requisição usando batch: true.

Implemente retry com backoff

Caso receba erro 429 ou 500, implemente retry com exponential backoff (1s, 2s, 4s…).

Valide dados antes de enviar

Verifique se order_value é positivo e se affiliate_id existe antes de enviar.

Logue erros para debug

Mantenha logs de todas as requisições para facilitar troubleshooting.

Use apenas campos necessários

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

API Reference Gerenciamento de Afiliados

​Endpoint

​Autenticação

​Body Parameters

​Response

​Exemplos

​Enviar uma Conversão (Mínimo)

​Resposta de Sucesso

​Enviar Múltiplas Conversões (Batch)

​Erros

​401 - API Key Inválida

​400 - Dados Inválidos

​403 - Limite Excedido

​429 - Rate Limit

​Testando

​Teste Rápido com cURL

​Testando Page View ou Lead (Sem Properties)

​Verificar no Dashboard

​Boas Práticas

​Próximos Passos

Guia Completo

Dashboard

Criar API Key

Aprovar Conversões

Endpoint

Autenticação

Body Parameters

Response

Exemplos

Enviar uma Conversão (Mínimo)

Resposta de Sucesso

Enviar Múltiplas Conversões (Batch)

Erros

401 - API Key Inválida

400 - Dados Inválidos

403 - Limite Excedido

429 - Rate Limit

Testando

Teste Rápido com cURL

Testando Page View ou Lead (Sem Properties)

Verificar no Dashboard

Boas Práticas

Próximos Passos