Como Construir um Web App para Atribuição de Receita de Parceiros

O que a atribuição de receita de parceiros precisa fazer

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.

Defina “atribuição de receita de parceiros” para o seu negócio

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:

• “Atribuir receita de assinatura ao parceiro que gerou o primeiro clique elegível dentro de 30 dias.”
• “Atribuir o primeiro pedido pago ao link de referência do parceiro, excluindo conversões apenas por cupom.”

Essa definição vira a âncora para seus requisitos, seu modelo de dados e as disputas que você terá que resolver depois.

Esclareça quem conta como parceiro

“Parceiro” frequentemente inclui vários grupos com expectativas e fluxos de trabalho diferentes:

• Afiliados: alto volume, rastreamento por link, pagamentos frequentes.
• Agências: menos negócios, ciclos de vendas mais longos, termos às vezes negociados.
• Revendedores: podem “possuir” uma conta, muitas vezes precisam de faturamento em vez de pagamentos automáticos.
• Influenciadores/criadores: podem preferir códigos, links curtos e relatórios com foco móvel.

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).

Os resultados que você deve suportar

Um web app prático de atribuição de receita de parceiros deve entregar de forma confiável quatro resultados:

1. Rastreamento: capturar pontos de contato do parceiro (cliques, uso de códigos, referências) e conectá-los às conversões.
2. Relatórios: mostrar a parceiros e ao seu time o que aconteceu — cliques, conversões, receita e status (pendente/aprovado/pago).
3. Pagamentos: calcular comissões, lidar com retenções/reembolsos e produzir demonstrativos prontos para pagamento.
4. Disputas: explicar “por que essa conversão foi (ou não foi) creditada”, com detalhes suficientes para resolver conflitos.

Se qualquer um desses for fraco, os parceiros não confiarão nos números — mesmo que a matemática esteja correta.

Defina o objetivo deste guia (e da sua primeira versão)

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:

• Rastrear IDs de link/ clique e persistí-los até o cadastro/checkout
• Registrar conversões server-side quando possível
• Aplicar uma regra de atribuição clara (mesmo que simples)
• Produzir relatórios para parceiros e reconciliação interna

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.

Requisitos e perguntas-chave a responder

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.

Identifique seus usuários (e o que “sucesso” significa para cada um)

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:

• Parceiro (afiliado/indicador): quer ver conversões creditadas, receita e status de pagamento.
• Marketing/Crescimento: quer saber quais parceiros estão performando e onde investir.
• Finanças: precisa de cálculos de pagamento auditáveis e reconciliação contra a receita real.
• Suporte/gerentes de parceiros: precisa explicar por que uma conversão foi ou não creditada.
• Engenharia/Dados: precisa de eventos confiáveis, regras claras e operações de baixa manutenção.

As 5–8 perguntas centrais que seu app deve responder

Escreva isso como consultas em linguagem simples que sua UI e relatórios devem suportar:

1. Qual parceiro (se houver) gerou este pedido/assinatura?
2. Qual evidência liga a conversão a esse parceiro? (click ID, cupom, código de referência etc.)
3. Quando o clique/lead ocorreu em relação à conversão? (dentro da janela permitida?)
4. Esta conversão é elegível para comissão? (somente novo cliente, exclusões de produto, gasto mínimo)
5. Qual é o valor e a taxa da comissão, e qual regra o determinou?
6. A conversão mudou após o fato? (reembolso, chargeback, cancelamento, downgrade)
7. O que devemos a cada parceiro por um período dado, e o que foi pago?
8. Como as conversões geradas por parceiros se comparam a outros canais? (para relatórios de marketing)

Defina os eventos que precisa capturar

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.

Decida quais tipos de atribuição suportar primeiro

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.

Escolha um modelo de atribuição e regras

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.

Modelos comuns de atribuição (visão geral)

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 padrão e depois documente exceções

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:

• Códigos de cupom: decida se um cupom válido sobrescreve o histórico de cliques, compartilha crédito ou só vale se o parceiro também gerou um clique.
• Tráfego direto: esclareça se visitas diretas “quebram a cadeia” (resetam a atribuição) ou simplesmente não contam como toque.
• Renovações: decida se renovações recorrentes continuam pagando o parceiro original, pagam só por um tempo limitado ou requerem reengajamento.

Defina janelas de atribuição e regras de reengajamento

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)?

Lide com upgrades, downgrades, reembolsos e chargebacks

Decida o que você atribui: apenas compra inicial, ou receita líquida ao longo do tempo.

• Upgrades: normalmente comissionáveis; especifique se você paga pelo delta ou pelo valor total do novo plano.
• Downgrades: geralmente reduzem comissões futuras; defina se você faz clawback de pagamentos passados.
• Reembolsos/chargebacks: defina uma política de clawback (reversão total vs parcial) e o prazo (imediato vs próximo ciclo de pagamento).

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.

Projete o modelo de dados para atribuição

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.

Entidades centrais (e o que representam)

• Partner: quem você paga (publisher, influencer, agência). Armazene partner_id, status, termos de pagamento, moeda padrão.
• Campaign: agrupamento para relatórios e regras (promoção sazonal, linha de produto). Chave: campaign_id, datas de início/fim.
• Link: uma URL rastreável emitida ao parceiro. Chave: link_id, pertence a partner_id e opcionalmente campaign_id.
• Click: uma interação rastreada única. Chave: click_id, referencia link_id e partner_id.
• Visitor: uma identidade que você pode reconhecer entre sessões. Chave: visitor_id (frequentemente derivada de um cookie de primeira parte).
• Conversion: o evento atribuído (lead, signup, compra). Chave: conversion_id, referencia click_id (quando disponível) e visitor_id.
• Order: o registro comercial usado para dinheiro. Chave: order_id, referencia customer_id e está ligada a conversion_id.
• Payout: o que você deve e quando. Chave: payout_id, referencia partner_id e agrega pedidos elegíveis.

Como os IDs se conectam (a “cadeia de custódia”)

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.

Campos monetários e ajustes

Pedidos mudam. Modele isso explicitamente:

• Armazene valores como inteiros em unidades menores (ex.: centavos): gross_amount, tax_amount, shipping_amount, fee_amount, discount_amount.
• Adicione currency_code mais uma fx_rate_to_payout_currency (e o timestamp/fonte dessa taxa).
• Represente reembolsos/chargebacks como linhas de ajuste ligadas a order_id (ex.: order_adjustment_id, type = partial_refund). Isso preserva um histórico auditável e evita reescrever totales.

Auditabilidade e qualidade de dados

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.

Implemente o rastreamento de cliques e links de parceiro

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.

Defina uma estrutura de link clara (e previsível)

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:

• partner_id: obrigatório; o proprietário primário do clique.
• campaign_id: opcional, mas recomendada; separa ofertas, placements ou promoções.
• utm_*: mantenha para ferramentas de analytics e relatórios de marketing. Trate-os como metadados, não como fonte da verdade.

Prefira rastreamento server-side via endpoint de redirect

Roteie todo o tráfego de parceiros por um endpoint de redirect (ex.: /r/{partner_id}):

1. Receba a requisição e leia parâmetros.
2. Gere um click_id único (UUID/ULID) e persista uma linha de click server-side (partner_id, campaign_id, user agent, ip_hash, timestamp, landing URL).
3. Defina um cookie de primeira parte (e opcionalmente localStorage) contendo o click_id.
4. 302 redirect para a página de destino final.

Isso torna a criação do clique consistente, evita que parceiros forjem click IDs e centraliza a aplicação de regras.

Cookie vs localStorage vs sessões server-side

• Cookies: enviados em toda requisição; melhores para matching server-side de conversões. Podem ser bloqueados/limitados por navegadores e regras de consentimento.
• localStorage: fácil de persistir na página, mas não é enviado automaticamente ao servidor; você precisa lê-lo client-side.
• Armazenamento de sessão server-side: funciona quando o browser mantém um identificador de sessão; bom para janelas curtas, fraco para janelas longas de atribuição.

A maioria das equipes usa cookie como primário, localStorage como fallback e sessões server-side apenas para fluxos de curta duração.

Considerações para mobile e app-to-web

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:

• Deep links (abrem o app com contexto de parceiro).
• Atribuição diferida (deferred attribution): se o app não estiver instalado, roteie para web/loja de apps e passe um token de curta duração para que o primeiro launch do app possa trocá-lo pelo click_id original.

Documente as regras exatas de link no portal do parceiro (veja /blog/partner-links) para que parceiros não “fiquem criativos” com parâmetros.

Capture conversões de forma confiável

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.

Escolha suas fontes de conversão (e prefira uma canônica)

A maioria dos produtos observa conversões de vários pontos:

• Página de agradecimento do checkout (client-side): fácil de implementar, mas pode ser bloqueada, perdida ou disparada duas vezes.
• Serviço de pedidos no backend (server-side): a fonte mais confiável porque reflete o sistema de registro.
• Webhooks do provedor de pagamento (server-side): úteis quando a confirmação de pagamento é assíncrona (ex.: 3DS, transferências bancárias), mas você deve lidar com retries.

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.

Grave conversões server-side (e persista o contexto de atribuição)

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:

1. Quando alguém chega via link de parceiro, gere/guarde um click_id.
2. Persista-o em um cookie de primeira parte e/ou em seu banco de dados ligado à sessão/usuário.
3. No momento da compra, faça o backend anexar o click_id ao pedido (ex.: a partir do estado da sessão, registro do cliente, ou um token assinado enviado pelo cliente).

Faça o mapeamento conversão → clique (com regras de fallback claras)

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:

• Se o usuário estiver logado: use o clique elegível mais recente para esse usuário dentro da janela de atribuição.
• Caso contrário: use o clique elegível mais recente para a sessão.
• Se existirem múltiplos cliques: decida antecipadamente se “last touch vence” ou se permite multi-touch.

Torne esses fallbacks visíveis na ferramenta admin para que suporte possa explicar resultados sem adivinhar.

Trate retries e duplicatas com idempotência

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)
• ou payment_provider_charge_id

Armazene 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.