Como construímos o programa de afiliados da Chiarelli Labs

Na nossa experiência, indicação é um dos canais de aquisição mais baratos que existem, mas só funciona se for fácil de rastrear e justo de pagar. Em vez de assinar um SaaS de afiliados de terceiros e integrar via webhook, decidimos construir o programa por dentro do pipeline de leads que já existia. Este post documenta as decisões técnicas por trás do programa de afiliados público da Chiarelli Labs.

Por que um programa próprio, e não um SaaS de afiliados

Um SaaS de terceiros resolve rastreamento de clique e pagamento, mas fica fora do sistema que já sabe em que estágio do funil cada lead está. Nosso pipeline (formulário de contato, classificação, discovery, proposta, execução, milestones de pagamento) já existia antes do programa. Construir por dentro dele significa que o mesmo evento que marca um milestone como pago é o mesmo evento que credita a comissão.

Cadastro, link e atribuição first-touch

O cadastro é aberto em /afiliados: um onboarding de 6 passos que termina com o aceite dos termos, e aceitar ativa o link de indicação no formato chiarelli.dev/r/[code]. Visitar esse link seta um cookie cl_ref: httpOnly, validade de 60 dias, modelo first-touch (a primeira indicação que tocar o lead vale, não a última). Quando esse lead preenche o formulário de contato, o mesmo endpoint que recebe o formulário lê o cookie, cria o registro de indicação (affiliate_referrals) e bloqueia auto-indicação: se o email do lead é o mesmo do afiliado, o registro não é criado.

Comissão automática, pagamento manual

A comissão é um percentual configurável por track de serviço (não publicamos o valor exato). Ela é creditada automaticamente no momento em que um milestone de pagamento do projeto é marcado como pago, de forma pro-rata (proporcional ao valor daquele milestone específico) e idempotente: marcar o mesmo milestone como pago duas vezes não duplica a comissão. O pagamento em si é manual, via PIX, rastreado num painel administrativo dedicado.

O painel protege o lead, não só o afiliado

A autenticação do afiliado é isolada da autenticação do resto do site: login por magic link, sem senha, com tabelas de banco e cookie de sessão próprios. O detalhe mais importante do painel, porém, é o que ele não mostra: o afiliado vê um pseudônimo pro lead que indicou, o estágio dele no funil e a comissão já ganha com ele, nunca o valor do contrato fechado. É uma decisão de produto: o afiliado precisa saber que a indicação está progredindo e quanto vai receber, não precisa ver o que o cliente final pagou.

Construído em etapas, com dois bugfixes no caminho

O programa saiu em quatro etapas: fundação (schema de banco e configuração de comissão por track), ativação (compartilhamento do link, contagem de cliques, card de indicação com um gerador via IA), conversão (email automático de progresso pro afiliado, mini-cases de sucesso, um jeito do afiliado pedir ajuda) e recrutamento (landing page própria, convite, kit público de divulgação). Depois de no ar, dois bugs apareceram e foram corrigidos: o download do card de indicação, que às vezes gerava erro 500, foi trocado por um link nativo (<a download>); e as variantes do gerador de card via IA foram revisadas e sanitizadas.

O programa está ativo em /pt/afiliados: cadastro aberto, onboarding de 6 passos, ativação do link após aceitar os termos. Quem já indica clientes informalmente pode formalizar a indicação lá e acompanhar o retorno num painel próprio.