Skip to main content
O programa de afiliação permite que produtores adicionem usuários como afiliados de seus produtos. Afiliados recebem comissões sobre vendas realizadas por meio de seus links de divulgação.

​
Endpoints

Todos os endpoints abaixo estão sob o prefixo /api/v1/products/{product_hash}/affiliates. Exigem autenticação via X-Api-Client-Token + Authorization: Bearer <user_token>, e o produto deve pertencer ao client autenticado.

​
Adicionar afiliado individual

Rota: POST /api/v1/products/{product_hash}/affiliates
​
string
required
Código (hash) do usuário a ser afiliado. Deve existir na base e pertencer ao mesmo client da API.
​
number
Percentual de comissão individual. Min: 1, Max: 80. Se não informado, usa o padrão do produto.
Os campos status, is_active e origin são preenchidos automaticamente pelo sistema. Toda afiliação criada via Nexus recebe status = "approved", is_active = true e origin = "nexus".

​
Response (200)

​
string
Hash identificador do afiliado (PID).
​
number
Percentual de comissão configurado.
​
string
Status da afiliação.
​
string
Data de criação (YYYY-MM-DD HH:mm:ss).

​
Atualizar afiliação

Rota: PUT /api/v1/products/{product_hash}/affiliates/{affiliation_code} Somente o dono do produto pode atualizar afiliações. O campo user_id é preenchido automaticamente a partir da afiliação na rota — não é necessário enviá-lo no body.
​
number
Novo percentual de comissão. Min: 1, Max: 80.

​
Adicionar em lote

Rota: POST /api/v1/products/{product_hash}/affiliates/batch Operação assíncrona — retorna 202 com o UUID da operação.
​
array
required
Lista de afiliados. Min: 1, Max: 5.000 itens.
​
string
required
Código (hash) do usuário a ser afiliado.
​
number
Percentual de comissão. Min: 1, Max: 80.
Consulte o progresso via GET /affiliates/batch/{batchId} usando o UUID retornado.

​
Remover em lote

Rota: POST /api/v1/products/{product_hash}/affiliates/batch-delete
​
array
required
Lista de códigos (hashes) de usuários a remover. Min: 1, Max: 5.000.

​
Atualizar comissão em lote

Rota: PATCH /api/v1/products/{product_hash}/affiliates/batch
​
array
required
Lista de afiliados. Min: 1, Max: 5.000 itens.
​
string
required
Código (hash) do usuário afiliado.
​
number
required
Novo percentual de comissão. Min: 1, Max: 80.

​
Atualizar comissão de todos

Rota: PATCH /api/v1/products/{product_hash}/affiliates/commission
​
number
required
Novo percentual aplicado a todos os afiliados. Min: 1, Max: 80.

​
Desativar todos

Rota: POST /api/v1/products/{product_hash}/affiliates/deactivate-all Não recebe campos no body. Desativa todos os afiliados do produto.

​
Consultar status de operação em lote

Rota: GET /api/v1/products/{product_hash}/affiliates/batch/{batchId} Retorna o status da operação em lote identificada pelo batchId (UUID retornado nas operações batch). Inclui contadores de itens processados, com sucesso e com falha.

​
Regras de validação

​
Criação individual (POST /affiliates)

1

Produto permite afiliação

O campo allow_affiliation do produto deve ser true.
2

Produtor não pode ser afiliado

O user_id informado não pode ser o dono do produto.
3

Usuário pertence ao client

O código informado em user_id deve corresponder a um usuário vinculado ao mesmo client API autenticado.
4

Comissão entre 1% e 80%

Se commission_percentage for informado, deve estar nesse intervalo.
5

Status automático

O sistema define status = "approved", is_active = true e origin = "nexus". O client não controla esses campos.

​
Operações em lote

As operações batch são processadas de forma assíncrona. Além da validação de formato (array de 1 a 5.000 itens), o processamento aplica regras adicionais por item:
  • Produtor não pode ser adicionado como afiliado do próprio produto
  • Usuário deve existir no sistema e não pode estar excluído
  • Não pode haver afiliação ativa existente para o mesmo usuário naquele produto
  • Coprodutores do produto são bloqueados
  • Se houver afiliação pendente anterior para o mesmo usuário, ela é removida antes de criar a nova
  • A afiliação é criada com status approved e origin nexus

​
Status possíveis

​
Configurações do produto

Os campos abaixo são gerenciados via POST/PUT /api/v1/products/{product_hash} e afetam o comportamento da afiliação.
​
boolean
Liga/desliga o programa de afiliados. Quando false, os campos affiliate_percentage, affiliation_description, affiliation_terms, first_click_percentage e last_click_percentage são zerados automaticamente.
​
boolean
Se ativo, solicitações de afiliação são aprovadas automaticamente (sem fila de pendentes).
​
string
Tipo de atribuição de comissão: first (primeiro clique), last (último clique) ou multi (dividido entre primeiro e último). Default no Nexus: multi.
​
number
Percentual padrão de comissão. Obrigatório quando allow_affiliation = true. Min: 1, Max: 80.
​
number
Percentual atribuído ao primeiro clique no modo multi. A soma com last_click_percentage deve ser 100%. Se apenas um for informado, o outro é calculado automaticamente.
​
number
Percentual atribuído ao último clique no modo multi.
​
string
Descrição do programa de afiliação. Obrigatória quando allow_affiliation = true. Min: 50, Max: 1.000 caracteres.
​
string
Termos de afiliação exibidos ao afiliado. Obrigatório quando allow_affiliation = true. Min: 50, Max: 1.000 caracteres.

​
Configurações da oferta

Os campos abaixo são gerenciados via POST/PUT /api/v1/products/{product_hash}/offers/{offer_code}.
​
boolean
Permite ou bloqueia afiliados naquela oferta específica.
​
number
Percentual de comissão específico da oferta. Sobrescreve o affiliate_percentage do produto. Obrigatório quando allow_affiliates = true. Min: 1, Max: 80.
​
boolean
Auto-afiliação na oferta.
​
number
Percentual de comissão para renovações de assinatura (apenas ofertas recorrentes). Min: 1, Max: 80.
​
boolean
Habilita comissão diferenciada para renovações. Quando true, affiliates_subscription_percentage passa a ser obrigatório.
​
boolean
Se ativo, a comissão é paga somente na primeira parcela (apenas ofertas recorrentes).

​
Fluxos

​
Adicionar afiliado individual

​
Adicionar em lote

​
Atualizar afiliação

O client envia PUT /affiliates/{affiliation_code}. Exige que o usuário autenticado seja o dono do produto (gate update-affiliate). Permite alterar commission_percentage e outros campos. O backend gera log de auditoria com o estado antes e depois da alteração.

​
Remover afiliação

O client envia DELETE /affiliates/{affiliation_code}. A afiliação é removida via soft delete. O backend gera log de auditoria registrando a remoção.

​
Operações em massa

PATCH /affiliates/batch atualiza commission_percentage para uma lista de afiliados. PATCH /affiliates/commission aplica um único percentual a todos. POST /affiliates/deactivate-all desativa todos os afiliados do produto. POST /affiliates/batch-delete remove uma lista por user_ids. Todas as operações batch retornam 202 e são processadas em fila.

​
Autorização

O endpoint PUT /affiliates/{affiliation_code} exige que o usuário autenticado seja o dono do produto (product.user_id === user.id). Qualquer outro usuário receberá 403 Forbidden.
Todos os endpoints de afiliação exigem que o produto pertença ao client autenticado (middleware de propriedade).

​
Restrições resumidas

  • allow_affiliation do produto deve ser true
  • Produtor nunca pode ser afiliado do próprio produto
  • user_id deve ser o código (hash) do usuário, não o ID interno
  • Comissão sempre entre 1% e 80%
  • Operações batch: máximo 5.000 itens por chamada
  • Toda afiliação via Nexus recebe status = approved e origin = nexus
  • Quando allow_affiliation é desligado no produto, os campos de afiliação são zerados
  • No modo multi, se apenas first_click_percentage ou last_click_percentage for informado, o outro é calculado automaticamente para somar 100%
  • Coprodutores e afiliações duplicadas são bloqueados por item
  • Afiliações pendentes anteriores são removidas antes de criar a nova
  • Operações batch retornam 202 e são processadas em fila