Programa de afiliados: atribuição dupla, códigos de indicação, comissão e portal

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:

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

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
• Painéis e relatórios de vendas
• Visão geral de Vendas e Gamificação