Aprenda a projetar e construir um web app que rastreia cliques de parceiros, conversões e receita. Cobre modelo de dados, rastreamento, relatórios, pagamentos e privacidade.
A atribuição de receita de parceiros é o sistema que responde a uma pergunta simples: qual parceiro deve receber crédito (e quanto) por um evento de receita? Em um web app, isso significa que você não está apenas contando cliques — você está conectando a referência de um parceiro a uma conversão posterior, transformando isso em um número de receita claro e tornando-o auditável.
Comece escrevendo uma definição em uma frase que inclua (1) o que é atribuído, (2) a quem, e (3) sob quais regras. Por exemplo:
Essa definição vira a âncora para seus requisitos, seu modelo de dados e as disputas que você terá que resolver depois.
“Parceiro” frequentemente inclui vários grupos com expectativas e fluxos de trabalho diferentes:
Evite forçar todos eles em um único fluxo muito cedo. Você pode usar um sistema unificado (parceiros, programas, contratos) enquanto suporta múltiplos métodos de referência (links, códigos, acordos manuais).
Um web app prático de atribuição de receita de parceiros deve entregar de forma confiável quatro resultados:
Se qualquer um desses for fraco, os parceiros não confiarão nos números — mesmo que a matemática esteja correta.
Para um guia prático de construção, o objetivo não é debater filosofia de atribuição — é ajudar você a lançar um sistema funcionando. Uma primeira versão realista deve:
Você pode adicionar recursos avançados (atribuição multi-touch, stitch cross-device, scoring complexo de fraude) depois que o básico for confiável e testável.
Antes de escolher um modelo de atribuição ou projetar um banco, esclareça o que o app deve provar para o negócio. A atribuição de receita de parceiros é, no fim, um conjunto de respostas que as pessoas confiam o suficiente para pagar.
A maioria das equipes constrói para “parceiros” primeiro e descobre depois que finanças ou suporte não conseguem verificar nada. Liste seus usuários primários e as decisões que cada um toma:
Escreva isso como consultas em linguagem simples que sua UI e relatórios devem suportar:
No mínimo, planeje para: click, lead, início de trial, compra, renovação e reembolso/chargeback. Decida quais são “commissionáveis” e quais são evidência de suporte.
Comece com um conjunto de regras claro — comumente last-touch dentro de uma janela configurável — e só adicione multi-touch quando tiver necessidades fortes de relatório e dados limpos. Mantenha a primeira versão fácil de explicar e auditar.
Antes de escrever código, decida o que “recebe crédito” e quando esse crédito expira. Se você não definir regras desde o início, acabará debatendo casos de borda (e recebendo reclamações de parceiros) em cada pagamento.
Last click atribui 100% do crédito ao clique de parceiro mais recente antes da conversão. É simples e amplamente compreendido, mas pode super-recompensar tráfego com cupom no estágio final.
First click atribui 100% ao primeiro parceiro que apresentou o cliente. Favorece parceiros de descoberta, mas pode subvalorizar os que ajudam a fechar a venda.
Linear divide o crédito igualmente entre todos os toques qualificados na janela. Pode parecer “justo”, mas é mais difícil de explicar e pode diluir incentivos.
Time-decay atribui mais crédito aos toques próximos à conversão, reconhecendo toques anteriores. É um compromisso, mas requer mais matemática e relatórios claros.
Escolha um modelo padrão para a maioria das conversões (muitos apps começam com last click porque é mais fácil de explicar e reconciliar). Depois documente exceções explicitamente para que suporte e finanças apliquem de forma consistente:
Defina uma ou mais janelas como 7 / 30 / 90 dias. Uma abordagem prática é uma janela padrão (por exemplo, 30 dias) mais janelas mais curtas para parceiros de cupom se necessário.
Também defina regras de reengajamento: se um cliente clicar em um link de outro parceiro dentro da janela, você troca o crédito imediatamente (last click), divide o crédito, ou mantém o parceiro original a menos que o novo clique esteja dentro de uma “janela próxima” (por exemplo, 24 horas)?
Decida o que você atribui: apenas compra inicial, ou receita líquida ao longo do tempo.
Escreva essas regras em um curto documento “Política de Atribuição” e linke-o no portal do parceiro para que o comportamento do sistema coincida com as expectativas do parceiro.
Um modelo de dados limpo é a diferença entre “achamos que esse parceiro gerou a venda” e “podemos provar, reconciliar e pagar corretamente.” Comece com um pequeno conjunto de entidades principais e torne os relacionamentos explícitos por IDs imutáveis.
partner_id, status, termos de pagamento, moeda padrão.campaign_id, datas de início/fim.link_id, pertence a partner_id e opcionalmente campaign_id.click_id, referencia link_id e partner_id.visitor_id (frequentemente derivada de um cookie de primeira parte).conversion_id, referencia click_id (quando disponível) e visitor_id.order_id, referencia customer_id e está ligada a conversion_id.payout_id, referencia partner_id e agrega pedidos elegíveis.Seu caminho dourado é:
partner_id → link_id → click_id → visitor_id → conversion_id → order_id → payout_id
Mantenha customer_id junto de order_id para que compras repetidas possam seguir suas regras (por exemplo, “apenas primeira compra” vs “vida inteira”). Armazene tanto seus IDs internos quanto os externos (ex.: shopify_order_id) para reconciliação.
Pedidos mudam. Modele isso explicitamente:
gross_amount, tax_amount, shipping_amount, fee_amount, discount_amount.currency_code mais uma fx_rate_to_payout_currency (e o timestamp/fonte dessa taxa).order_id (ex.: order_adjustment_id, type = partial_refund). Isso preserva um histórico auditável e evita reescrever totales.Adicione campos de auditoria em todo lugar: created_at, updated_at, ingested_at, source (web, server-to-server, import) e identificadores imutáveis.
Para análise de fraude sem armazenar dados pessoais brutos, guarde campos hasheados como ip_hash e user_agent_hash. Por fim, mantenha um change log leve (entidade, entity_id, valores antigo/novo, ator) para que decisões de pagamento possam ser explicadas depois.
O rastreamento de cliques é a base da atribuição de receita de parceiros: todo link de parceiro deve criar um “registro de clique” durável que você possa conectar depois a uma conversão.
Use um único formato canônico de link que os parceiros possam copiar/colar. Na maioria dos sistemas, o link exibido ao parceiro não deve incluir um click_id — seu servidor gera isso.
Um padrão limpo é:
/r/{partner_id}?campaign_id=...&utm_source=...&utm_medium=partner&utm_campaign=...
Orientação prática de parâmetros:
Roteie todo o tráfego de parceiros por um endpoint de redirect (ex.: /r/{partner_id}):
Isso torna a criação do clique consistente, evita que parceiros forjem click IDs e centraliza a aplicação de regras.
A maioria das equipes usa cookie como primário, localStorage como fallback e sessões server-side apenas para fluxos de curta duração.
Para web móvel, cookies podem ser menos confiáveis, então use o endpoint de redirect e armazene click_id tanto em cookie quanto em localStorage.
Para app-to-web, suporte:
Documente as regras exatas de link no portal do parceiro (veja /blog/partner-links) para que parceiros não “fiquem criativos” com parâmetros.
O rastreamento de conversões é onde os sistemas de atribuição ganham confiança — ou a perdem silenciosamente. Seu objetivo é registrar um único evento canônico de “conversão” por compra real (ou cadastro), com contexto suficiente para conectá-lo de volta a um clique de parceiro.
A maioria dos produtos observa conversões de vários pontos:
Recomendação: trate o seu serviço de pedidos no backend como o registrador canônico de conversões, e opcionalmente use webhooks de pagamento como sinal de confirmação/atualização (ex.: mover um pedido de pending para paid). Eventos client-side podem ser usados para debugging ou analytics de funil, não para atribuição com grau de pagamento.
Para atribuir receita depois, o evento de conversão precisa de um identificador estável e uma forma de vincular a um clique.
Abordagem comum:
Sua junção primária deve ser conversion.click_id → click.id. Se o click_id estiver ausente, defina regras de fallback explícitas, como:
Torne esses fallbacks visíveis na ferramenta admin para que suporte possa explicar resultados sem adivinhar.
Webhooks e chamadas client vão retryar. Você deve ser capaz de receber a mesma conversão várias vezes sem contagem dupla.
Implemente chaves de idempotência usando um valor único estável, como:
order_id (melhor se for globalmente único)payment_provider_charge_idArmazene a chave no registro de conversão com uma restrição única. No retry, retorne sucesso e não crie uma segunda conversão. Essa escolha simples previne os bugs mais comuns de “receita fantasma” em pagamentos.
A atribuição de receita de parceiros é o conjunto de regras e dados que determinam qual parceiro recebe crédito por um evento de receita (e quanto), com base em evidências como IDs de clique, códigos de cupom e janelas de tempo.
Uma definição útil inclui:
Comece escrevendo uma política em uma frase e, em seguida, liste exceções.
Uma política V1 sólida costuma ser:
Depois documente exceções como precedência de cupom, renovações e se tráfego direto quebra a atribuição.
No mínimo, rastreie:
Mesmo que depois você adicione leads ou trials, esses três permitem conectar tráfego → receita → reversões de forma segura para pagamentos.
Use um endpoint de redirect (por exemplo, /r/{partner_id}) que:
Isso evita que parceiros forjem click_ids e torna o rastreamento consistente entre placements.
Prefira criação de pedidos server-side (seu backend) como a fonte canônica de conversões.
Na prática:
click_id (ou token de atribuição) ao pedido no momento da criaçãoIsso reduz double-fires e facilita a reconciliação financeira.
Use chaves de idempotência para que retries não criem conversões duplicadas.
Chaves comuns:
order_id (melhor se for globalmente único)payment_provider_charge_idImponha unicidade no banco (unique constraint). Em repetições, retorne sucesso sem criar uma segunda conversão ou item de comissão.
Aponte para uma cadeia que você possa provar fim-a-fim:
partner_id → link_id → click_id → visitor_id → conversion_id → order_id → payout_idArmazene IDs internas e externas (por exemplo, shopify_order_id) e mantenha timestamps (created_at, ingested_at) para traçar disputas e reconciliar com seu sistema de faturamento.
Modele dinheiro com auditabilidade e reversões em mente:
currency_codeComece com telas que reduzam tickets de suporte:
Faça cada conversão explicável com campos de evidência como horário do clique, order ID (mascarado) e regra aplicada.
Use salvaguardas leves e consistentes:
Para privacidade, armazene o mínimo necessário (IDs pseudonimizados), faça hash de sinais sensíveis (como IP) quando possível e evite logar dados pessoais/pagamento.
Isso preserva o histórico e permite criar itens negativos em ciclos de pagamento posteriores, se necessário.