App Programa de Afiliados - Como Funciona

Integrações & Apps Marketing
#1

Programa de Afiliados — Como Funciona

Visão Geral

Transforme seus clientes em promotores da loja. O app de Programa de Afiliados permite que qualquer cliente compartilhe um link personalizado e seja recompensado automaticamente quando suas indicações resultarem em vendas.

O fluxo é simples: o cliente indicado acessa o link, se cadastra e realiza uma compra — o afiliado recebe pontos automaticamente assim que o pedido é pago. Esses pontos funcionam como cashback e podem ser usados como desconto nas próximas compras, criando um ciclo de engajamento e retenção.

Opcionalmente, o cliente indicado também pode receber pontos de boas-vindas no cadastro, incentivando a conversão logo na primeira visita.

O app gerencia a geração e o crédito dos pontos. Para que os pontos sejam utilizáveis no checkout como forma de pagamento, a loja precisa ter o app de Pontos de Fidelidade (app_id 124890) instalado e configurado em conjunto.

IDs de Programa Criados pelo App

O app cria entradas de pontos com dois program_id fixos, hardcoded no código:

| program_id | Nome padrão | Quando é criado |

| affiliates0 | Afiliado | Quando um pedido indicado é pago |

| referreds0 | Convite | Quando o cliente indicado se cadastra pelo link |

Esses IDs são fixos — não mudam independente de configuração.

Fluxo Completo

1. Afiliado compartilha o link

O link de indicação deve ter o parâmetro referral com o _id do cliente afiliado:


https://www.sujaloja.com.br/?referral=6564ed562cd6b65959bf71f6

Atenção: o parâmetro deve ser exatamente referral=. Parâmetros como ref= não funcionam — o storefront só lê referral.

O cupom pode ser incluído no mesmo link:


https://www.sujaloja.com.br/?coupon=CUPOM&referral=6564ed562cd6b65959bf71f6

2. Novo cliente acessa o link e se cadastra

O storefront captura o valor de referral da URL e salva em sessionStorage como ecomReferral. Na criação do cliente, esse valor é gravado no campo referral do cadastro.

O campo referral só é gravado no momento do cadastro. Clientes que já existiam antes de acessar o link não recebem o campo retroativamente.

3. Pedido é pago

O webhook do app é acionado quando o financial_status do pedido muda para paid. O app então:

  1. Busca o comprador do pedido

  2. Verifica se o comprador tem o campo referral no cadastro

  3. Se sim, cria uma entrada loyalty_points_entries no cadastro do afiliado com program_id: 'affiliates0'

  4. Se configurado points_on_signup, também cria uma entrada no cadastro do indicado com program_id: 'referreds0' (apenas no primeiro pedido)

Se o comprador não tiver referral, o webhook retorna 204 sem creditar nada.

4. Afiliado usa os pontos no checkout

Os pontos existem no cadastro mas só aparecem no checkout se o app de Pontos de Fidelidade estiver configurado para reconhecer os IDs affiliates0 e/ou referreds0. Veja a seção de integração abaixo.

Configurações do App de Afiliados

Acessíveis no painel da loja em Aplicativos → Programa de afiliados.

| Campo | Descrição | Padrão |

| Pontos no cadastro | Pontos creditados ao novo cliente indicado no ato do cadastro (referreds0) | 1 |

| Pontos no pedido → Tipo de bonificação | percentage (% do subtotal) ou fixed (valor fixo) | fixed |

| Pontos no pedido → Valor dos pontos | Valor percentual ou fixo a ser creditado ao afiliado | 1 |

| Recompensar todos os pedidos | Se ativo, o afiliado é pontuado a cada pedido do indicado. Se inativo, apenas no primeiro | false |

| Valor mínimo do pedido | Subtotal mínimo para o afiliado receber pontos | — |

Integração com o App de Pontos de Fidelidade

Por que é necessária

O app de afiliados apenas cria as entradas de pontos. Quem expõe esses pontos como forma de pagamento no checkout é o app de Pontos de Fidelidade (app_id 124890). Se os IDs affiliates0/referreds0 não estiverem cadastrados nas regras desse app, os pontos existem no cadastro do cliente mas não aparecem no checkout.

Como configurar

No app de Pontos de Fidelidade, em Regras para recebimento e utilização de pontos, adicione uma entrada com os seguintes campos:

| Campo | Valor recomendado | Observação |

| Nome do programa | Afiliado (ou o nome que preferir) | Aparece no checkout para o cliente |

| Proporção em moeda | 1 | 1 ponto = R$1,00. Ajuste conforme necessário |

| ID do programa | affiliates0 | Obrigatório. Deve ser exatamente esse valor |

| Utilizar apenas para forma de pagamento de crédito | Ativado | Impede que compras normais gerem pontos nesse programa |

Se quiser que os pontos de boas-vindas (referreds0) também sejam usáveis no checkout, crie uma segunda entrada com ID do programa = referreds0.

Por que ativar “Utilizar apenas para forma de pagamento de crédito”

Sem essa opção ativada, o app de Pontos de Fidelidade creditará pontos do programa affiliates0 a qualquer compra normal acima do valor mínimo configurado. O campo Percentual de recebimento vazio usa 1% como padrão — clientes comuns passariam a acumular pontos de afiliado em toda compra. A opção garante que esse saldo só seja gerado pelo app de afiliados.

Nuances Importantes

O program_id das entradas deve bater com o ID da regra

O app de Pontos de Fidelidade identifica o saldo disponível cruzando o program_id das loyalty_points_entries do cliente com os IDs gerados pelas regras configuradas. Se não houver correspondência exata, o toggle não aparece no checkout.

Ao adicionar pontos manualmente no cadastro de um cliente, o program_id informado deve ser exatamente o mesmo que o campo ID do programa da regra correspondente.

Regras sem “ID do programa” preenchido geram o ID automaticamente a partir do nome (ex: “DesiCash” → p0_desicash). Para evitar ambiguidade, sempre preencha o ID do programa explicitamente.

O campo referral só é capturado no cadastro

Se o cliente já tinha conta antes de acessar o link de indicação, o campo referral não será adicionado ao cadastro e nenhum ponto será creditado ao afiliado. O fluxo só funciona para clientes novos que se cadastram a partir do link.

Cadastro via OAuth (Google, Facebook)

No cadastro via OAuth, o storefront pode não passar o referral do sessionStorage para o cadastro do cliente, dependendo da implementação. Nesses casos, o campo referral não é gravado e o afiliado não é creditado.

Apenas o primeiro pedido por padrão

Com Recompensar todos os pedidos desativado (padrão), o afiliado só recebe pontos no primeiro pedido pago do indicado. Pedidos seguintes do mesmo cliente são ignorados.

Pontos expirados continuam visíveis no painel

O sistema não zera active_points automaticamente quando a validade expira. O cliente pode ver saldo disponível no painel mesmo após a expiração, mas esses pontos são ignorados no checkout (o app verifica a data de validade na aplicação).