## Visão geral

O **programa de afiliados** transforma quem indica vendas em uma entidade nativa com comissão própria. Um
afiliado pode ser **quatro coisas**, e o vínculo é de **identidade** (quem é o parceiro), nunca de
pagamento — o recebedor é sempre o cadastro do afiliado:

| O afiliado é | Quando usar |
|---|---|
| **Um agente** | Alguém da equipe que também indica vendas de outra carteira |
| **Um contato** | Um cliente que virou parceiro e passou a indicar outros |
| **Uma empresa** | Uma agência, revenda ou clínica parceira — os contatos dela podem herdar o vínculo |
| **Um parceiro externo** | Alguém que a conta não conhece: só e-mail/código (ex.: um afiliado do Hotmart) |

Cada afiliado recebe um **código de indicação** único (público, para compartilhar) e um **token de
relatório** separado (privado, rotacionável).

O ponto central é a **atribuição dupla**: um mesmo pedido pago credita o **vendedor (dono)** no extrato
do usuário **e** o **afiliado** — no mesmo ledger de comissão, sem colisão. Assim, o vendedor continua
recebendo seus pontos e comissão, e o afiliado recebe a comissão de indicação, sobre a mesma venda, sem
contagem dobrada.

## Pré-requisitos

- Módulo **Vendas & Gamificação** habilitado na conta.
- Recurso **`affiliate_program`** ativado na conta (dark-ship, padrão **desligado**).
- Recurso **`unified_revenue_ledger`** ativado — a comissão do afiliado é acumulada no momento em que o
  pedido é pago (o mesmo eixo do ledger unificado). Sem ele, não há acúmulo de comissão de afiliado.
- Permissão de **gestão de vendas** (`sales_manage`) — ou administrador — para gerenciar afiliados.

## Passo a passo

1. **Ative** `affiliate_program` (e `unified_revenue_ledger`) na conta.
2. **Crie um afiliado**: escolha em **"Este afiliado é"** se ele é um agente, um contato, uma empresa
   ou um parceiro externo; depois defina a **comissão** (percentual, valor fixo por venda ou plano).
3. **Compartilhe o código/link de indicação** com o afiliado.
4. **Atribua a indicação** por qualquer um destes caminhos: marque **"Indicado por"** na ficha do
   contato, use a ação de automação **"Definir afiliado do contato"**, envie `affiliate_id` no pedido,
   ligue a **herança pela empresa**, ou deixe o reconciliador casar o split da venda.
5. **A venda paga credita** o vendedor **e** o afiliado automaticamente.
6. **O afiliado acompanha** seu desempenho pelo portal (por token); o gestor lê o relatório no painel.

## Configurações & opções

### Campos do afiliado

| Campo | O que é |
|---|---|
| `name` | Nome do afiliado (obrigatório) |
| `user_id` / `contact_id` / `organization_id` | **Quem o afiliado é** — um agente, um contato ou uma empresa. São **mutuamente exclusivos**: preencher mais de um é recusado |
| `inherit_to_org_contacts` | Só para empresa: quando ligado, os contatos daquela empresa herdam o afiliado nos **novos** pedidos |
| `email` / `external_ref` | E-mail e/ou código externo (ucode do Hotmart). **Únicos por conta** — é por eles que o reconciliador identifica o parceiro |
| `referral_code` | Código de indicação — gerado automaticamente, único por conta, **público**, feito para compartilhar |
| `portal_token` | Credencial **privada** do relatório do afiliado. Separada do código e **rotacionável** |
| `commission_percent` | **Comissão (%)** — percentual de comissão (0–100); vazio quando um plano define |
| `commission_amount` | **Comissão fixa (R$)** — valor fixo pago por venda, no lugar do percentual. Opcional: deixe em branco para usar o percentual |
| `plan_id` | Plano de comissão que substitui o percentual e o valor fixo |
| `status` | `active`, `paused` ou `archived` — **apenas ativo acumula comissão** |
| `metadata` | Dados livres (ex.: a afiliação do Hotmart preservada) |

> **Formato do valor:** os campos de comissão aceitam vírgula **ou** ponto como separador decimal —
> `25,00` e `25.00` valem o mesmo, e o separador de milhar é opcional (`1.250,50`). Um valor fora da
> faixa (percentual acima de 100, valor negativo) é recusado na hora, com o motivo ao lado do campo.

### Como a venda é atribuída ao afiliado

Em cascata, do mais explícito para o mais genérico. O primeiro degrau que responder vence, e um afiliado
já gravado no pedido nunca é sobrescrito:

1. **`affiliate_id` enviado no pedido** — aceito pela API do CRM, pelo ingest público e pelas automações.
   O id é sempre conferido contra os afiliados **ativos desta conta**: um id de outra conta é descartado.
2. **"Indicado por" no contato** — a indicação durável da pessoa.
3. **Afiliado da empresa principal do contato** — só quando aquele afiliado ligou
   `inherit_to_org_contacts`. Vale apenas para a empresa **principal** e apenas daí para frente:
   ligar a opção não recredita pedidos antigos.
4. **Split externo reconciliado** — casa o `ucode`/e-mail do split (Hotmart/Kiwify) com um afiliado
   existente, inclusive pelo e-mail do **contato ou da empresa** vinculada.
5. **Sem correspondência → o split vai para a fila de reconciliação**, e não some.

### Splits sem cadastro

Quando o gateway informa uma comissão para alguém que a conta **não tem cadastrado**, esse split é
registrado numa fila visível — com nome, e-mail/ucode, valor informado e o pedido de origem. Antes, esse
caso simplesmente desaparecia dentro da metadata: o único sintoma era uma comissão que nunca aparecia.

Abra **"Splits sem cadastro"** na tela de Afiliados e decida: **Cadastrar** (abre o formulário
já preenchido com os dados do split) ou **Ignorar**. A fila **nunca cria um afiliado sozinha** — pagar
alguém a partir de um nome não verificado que veio de um webhook é exatamente o risco que essa
confirmação existe para evitar.

### Atribuição dupla sem colisão

O ledger de comissão distingue o **tipo de recebedor** (vendedor vs. afiliado). Um pedido pago gera duas
linhas — a do vendedor e a do afiliado — sem se misturar. O extrato de um vendedor **nunca** soma as
linhas do afiliado.

### Comissão do afiliado

A comissão é resolvida **por venda**, nesta ordem de precedência — do mais preciso para o mais genérico:

1. **Valor reportado pela fonte** — quando a venda veio do **Hotmart** ou da **Kiwify**, a própria
   plataforma informa quanto de fato pagou **àquele** afiliado. Esse valor é autoritativo e entra no
   ledger exatamente como veio, para que o extrato nunca divirja do que o afiliado realmente recebeu.
2. **Plano de comissão** — quando o afiliado tem um plano.
3. **Comissão fixa (R$)** — o valor fixo definido no afiliado.
4. **Comissão (%)** — o percentual sobre o valor pago do pedido.

Por que a fonte vem primeiro: em um programa de afiliados externo, a plataforma **já calculou e pagou** o
split — aplicar o nosso percentual por cima produziria um número que não bate com a realidade.

Afiliado **externo** recebe comissão e portal, mas **não** ganha pontos de gamificação (pontos exigem um
usuário).

### Extrato do afiliado

O afiliado tem **extrato próprio**, com o mesmo ciclo do extrato do vendedor: **acumulado → aprovado →
pago**. Ele é fechado por período **e por moeda** — um extrato é um documento a pagar, e você paga em uma
moeda só, então lançamentos em BRL e em USD viram extratos separados em vez de um total que não existe.

Extrato de afiliado e extrato de vendedor são **registros independentes**, mesmo quando o número de
identificação coincide. Na lista de extratos, o filtro de tipo de recebedor separa os dois ledgers.

### Portal do afiliado

Página **pública** e somente-leitura, aberta pelo **token de relatório** — sem sessão e sem `account_id`.
Mostra apenas o próprio desempenho: pedidos atribuídos (paginados, com filtro de período), receita e
comissão **agrupadas por moeda**, e os extratos fechados — **sem PII de contatos**. Token inválido,
rotacionado ou conta com o recurso desligado retornam 404.

**O token não é o código de indicação.** O código é público — vai em links e material — e continua
válido para sempre; o token é a credencial privada do relatório financeiro. Use **Girar** no cadastro do
afiliado para invalidar imediatamente todo link de relatório já compartilhado: nenhuma indicação deixa de
funcionar, porque o código não muda.

> **Afiliados criados antes desta versão** começam com o token **igual ao código de indicação público** —
> foi assim que nenhum link já entregue quebrou na migração. Enquanto isso for verdade, quem conhece o
> código consegue abrir o relatório, e o cadastro mostra o aviso *"este link ainda é o código público"*.
> **Gire o token** desses afiliados para emitir um link realmente privado.

### Arquivar, restaurar e excluir definitivamente

A lista padrão mostra afiliados atuais; use o **filtro de status** para revisar ativos, pausados e
arquivados. **Arquivar** interrompe novas atribuições e comissões, mas mantém indicações, pedidos e
demonstrativos existentes; **Restaurar** torna o parceiro ativo novamente. **Excluir definitivamente**
só aparece no afiliado arquivado e só funciona quando não existe histórico de indicação, pedido,
reconciliação ou financeiro; a confirmação é explícita e a ação não pode ser desfeita.

## Casos de uso

- Materializar um **afiliado do Hotmart** a partir do split preservado na venda (reconciliação por
  ucode/e-mail).
- Registrar um **agente interno** como afiliado que indica vendas de outra carteira.
- Compartilhar um **link de indicação** para captar indicações rastreáveis.
- O afiliado abre o **portal** e acompanha sua comissão acumulada em tempo quase real.

## Dicas, limites e boas práticas

- Afiliado **externo** não recebe pontos de gamificação — só comissão + portal.
- **Apenas afiliados ativos** acumulam; um afiliado pausado/arquivado não acumula nada.
- O **pagamento** ao afiliado (Pix/transferência) está fora do escopo v1 — o módulo faz acúmulo +
  relatório + portal.
- O `referral_code` é **público** — compartilhe à vontade. Quem abre o relatório financeiro é o
  **token de relatório**, que é privado e pode ser girado a qualquer momento.
- A **herança pela empresa** é opt-in por afiliado e só vale daqui para frente — ligar a opção não
  recredita nada do passado.
- Ao **mesclar contatos**, a indicação do contato absorvido é adotada pelo principal quando ele ainda não
  tem uma; um contato que já tinha indicação mantém a dele.
- Um estorno também **reverte** a comissão do afiliado, na origem do pedido.

## Solução de problemas

- **Afiliado não creditado**: o `unified_revenue_ledger` pode estar desligado, o pedido pode não ter
  afiliado atribuído, ou o afiliado não está **ativo**. Verifique os três.
- **Portal retorna 404**: token errado/antigo ou o recurso `affiliate_program` está desligado na conta.
- **Afiliado do Hotmart não casou**: o split entrou em **"Splits sem cadastro"**. Abra a fila e use
  **Cadastrar** — o formulário já vem preenchido com o e-mail/ucode exatos que vieram do gateway.
- **Comissão aparece com "sem moeda"**: são lançamentos anteriores à separação por moeda. A moeda real
  deles é desconhecida e não é inventada; novos lançamentos já saem com a moeda do pedido.
- **A exclusão definitiva foi recusada**: ainda existe histórico de indicação, pedido, reconciliação ou
  financeiro. Mantenha o afiliado arquivado; preservar esse histórico é intencional.

## Veja também

- [Ledger unificado de receita: contagem única de vendas](/hc/ajuda/articles/sales-gamification-unified-revenue-ledger-pt-br)
- [Painéis e relatórios de vendas](/hc/ajuda/articles/sales-gamification-paineis-e-relatorios-de-vendas-pt-br)
- [Visão geral de Vendas e Gamificação](/hc/ajuda/articles/sales-gamification-overview-pt-br)