Sistema de Afiliados

Visão geral

O Sistema de Afiliados da Alpa permite que vendedores criem programas de comissão para seus produtos e que outros usuários promovam esses produtos em troca de uma comissão automática por cada venda realizada. O fluxo funciona em dois papéis distintos:

Anunciante (Merchant): cria um programa de afiliados para um produto, define a comissão e gerencia os afiliados inscritos.
Afiliado: navega no marketplace, solicita afiliação a programas e compartilha um link rastreável único.

Quando uma venda é realizada via link do afiliado, a comissão é creditada automaticamente na carteira do afiliado após a confirmação do pagamento.

Pré-requisitos

Uma conta ativa na Alpa com KYC aprovado
Sua API Key configurada (veja Autenticação)
Para criar um programa: ao menos um produto ativo com link de pagamento

Como funciona o rastreamento

Ao se afiliar a um programa, o afiliado recebe um código único (ex: NOME-AB12CD). Esse código é adicionado como parâmetro aff na URL do checkout do produto:

https://checkout.usealpa.com/pay/{slug}?aff=NOME-AB12CD

Quando um comprador acessa esse link e realiza uma compra, a transação é vinculada ao link do afiliado e a comissão é calculada e creditada automaticamente.

Tipos de comissão

Tipo	Descrição	Exemplo
`PERCENTAGE`	Percentual do valor pago	`1000` = 10% (valor × 100)
`FIXED`	Valor fixo em centavos	`2990` = R$ 29,90

Para comissão percentual, o valor é armazenado multiplicado por 100 para preservar casas decimais. Exemplo: 10,5% → 1050.

Criando um programa de afiliados

Somente o dono do produto pode criar um programa de afiliados para ele. Cada produto pode ter no máximo um programa ativo.

curl -X POST "https://alpa-sistema-api.onrender.com/api/affiliate/programs" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "550e8400-e29b-41d4-a716-446655440000",
    "commissionType": "PERCENTAGE",
    "commissionValue": 1000,
    "cookieDays": 30,
    "description": "Promova nosso curso e ganhe 10% por cada aluno indicado.",
    "rules": "Proibido tráfego pago em nome da marca. Apenas divulgação orgânica.",
    "affiliatePage": "https://seusite.com/afiliados",
    "salesPage": "https://seusite.com/vendas"
  }'

Resposta

{
  "message": "Programa criado com sucesso.",
  "data": {
    "id": "aff-prog-uuid",
    "productId": "550e8400-e29b-41d4-a716-446655440000",
    "commissionType": "PERCENTAGE",
    "commissionValue": 1000,
    "cookieDays": 30,
    "isActive": true,
    "description": "Promova nosso curso e ganhe 10% por cada aluno indicado.",
    "rules": "Proibido tráfego pago em nome da marca.",
    "affiliatePage": "https://seusite.com/afiliados",
    "salesPage": "https://seusite.com/vendas",
    "createdAt": "2026-04-13T00:00:00.000Z"
  }
}

Navegando no marketplace

Qualquer usuário autenticado pode listar todos os programas ativos disponíveis para afiliação:

curl -X GET "https://alpa-sistema-api.onrender.com/api/affiliate/marketplace" \
  -H "Authorization: Bearer SUA_API_KEY"

Resposta

{
  "data": [
    {
      "id": "aff-prog-uuid",
      "commissionType": "PERCENTAGE",
      "commissionValue": 1000,
      "cookieDays": 30,
      "description": "Promova nosso curso e ganhe 10% por cada aluno.",
      "rules": null,
      "affiliatePage": "https://seusite.com/afiliados",
      "salesPage": "https://seusite.com/vendas",
      "extendedCommission": false,
      "product": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Curso de JavaScript Avançado",
        "price": 19990,
        "imageUrl": "https://cdn.exemplo.com/curso-js.jpg",
        "paymentLinks": [
          { "paymentLink": { "slug": "curso-js" } }
        ]
      },
      "user": { "name": "João da Silva" },
      "_count": { "links": 42 },
      "links": []
    }
  ]
}

Solicitando afiliação

curl -X POST "https://alpa-sistema-api.onrender.com/api/affiliate/join/aff-prog-uuid" \
  -H "Authorization: Bearer SUA_API_KEY"

Resposta

{
  "message": "Afiliação realizada com sucesso.",
  "data": {
    "id": "link-uuid",
    "code": "JOAO-AB12CD",
    "programId": "aff-prog-uuid",
    "status": "ACTIVE",
    "clicks": 0,
    "conversions": 0,
    "totalEarnedCents": 0,
    "createdAt": "2026-04-13T00:00:00.000Z"
  }
}

O link de divulgação para este produto será:

https://checkout.usealpa.com/pay/curso-js?aff=JOAO-AB12CD

Consultando meus links e comissões

Listar links ativos

curl -X GET "https://alpa-sistema-api.onrender.com/api/affiliate/links" \
  -H "Authorization: Bearer SUA_API_KEY"

Listar comissões

curl -X GET "https://alpa-sistema-api.onrender.com/api/affiliate/commissions?page=1&limit=20" \
  -H "Authorization: Bearer SUA_API_KEY"

Estatísticas consolidadas

curl -X GET "https://alpa-sistema-api.onrender.com/api/affiliate/stats" \
  -H "Authorization: Bearer SUA_API_KEY"

{
  "data": {
    "totalLinks": 3,
    "activeLinks": 3,
    "totalClicks": 148,
    "totalConversions": 12,
    "totalEarnedCents": 23880,
    "pendingCents": 0
  }
}

Status das comissões

Status	Descrição
`PENDING`	Aguardando processamento
`PAID`	Creditada na carteira do afiliado
`CANCELLED`	Cancelada (ex: chargeback)

Boas práticas

Defina regras claras: Use o campo rules para informar políticas de divulgação (tráfego pago, menção à marca, etc.)
Página de afiliados: Crie uma landing page com materiais de divulgação e preencha affiliatePage
Comissão competitiva: Comissões entre 10–30% tendem a atrair mais afiliados
Cookie de rastreamento: cookieDays de 30 dias é o padrão; aumente para produtos de decisão longa
Acompanhe conversões: Use GET /api/affiliate/programs/:id/links para monitorar o desempenho de cada afiliado

Visão geral

Pré-requisitos

Como funciona o rastreamento

Tipos de comissão

Criando um programa de afiliados

Resposta

Navegando no marketplace

Resposta

Solicitando afiliação

Resposta

Consultando meus links e comissões

Listar links ativos

Listar comissões

Estatísticas consolidadas

Status das comissões

Boas práticas

Próximos passos

Referência da API

Produtos

​Visão geral

​Pré-requisitos

​Como funciona o rastreamento

​Tipos de comissão

​Criando um programa de afiliados

​Resposta

​Navegando no marketplace

​Resposta

​Solicitando afiliação

​Resposta

​Consultando meus links e comissões

​Listar links ativos

​Listar comissões

​Estatísticas consolidadas

​Status das comissões

​Boas práticas

​Próximos passos

Referência da API

Produtos

Visão geral

Pré-requisitos

Como funciona o rastreamento

Tipos de comissão

Criando um programa de afiliados

Resposta

Navegando no marketplace

Resposta

Solicitando afiliação

Resposta

Consultando meus links e comissões

Listar links ativos

Listar comissões

Estatísticas consolidadas

Status das comissões

Boas práticas

Próximos passos