Guia de integração

Do zero à primeira venda atribuída em 4 passos. Dentro do produto, o wizard gera o snippet exato do seu domínio e valida a integração ao vivo — este guia é a versão aberta, para você avaliar o esforço antes de criar a conta (spoiler: é pouco).

1 · Conecte sua conta Stripe

Um clique de autorização via Stripe Connect. É assim que lemos vendas, renovações e estornos para atribuir comissões — sem nenhum acesso aos seus fundos, e revogável a qualquer momento no dashboard do Stripe.

2 · Crie o programa

Comissão (percentual ou fixa), recorrência (vitalícia, N meses ou primeiro pagamento), janela de atribuição do cookie, dias até a aprovação automática e payout mínimo. O programa ganha uma página pública — é ela que você divulga para atrair afiliados, com candidatura aberta ou por aprovação.

3 · Instale o snippet

Cole no <head> da sua landing (900 bytes, carrega async — não pesa nada). Ele captura o ?ref= do link do afiliado e grava o token de atribuição em um cookie do domínio raiz e em window.klikio_referral:

<script src="https://app.klikio.com.br/t.js"
        data-endpoint="https://api.klikio.com.br/t/click"
        data-cookie-domain=".SEU-SITE.com.br"
        async></script>

Depois, envie o token ao Stripe na criação da Checkout Session — esse é o único elo que liga a venda ao afiliado. Escolha o padrão do seu stack:

A · Deixe a IA integrar — usa Claude, Cursor ou outro assistente de código? O wizard tem um prompt pronto que encontra onde seu checkout é criado e faz a integração sozinho.

B · Seu backend enxerga os cookies do site

// Padrão B — backend que ENXERGA os cookies do site
// (Express, Next.js API/route handler, Rails, Laravel...)
const affRef = req.cookies?.['_aff_ref']

const session = await stripe.checkout.sessions.create({
  // ...sua configuração atual...
  client_reference_id: affRef || undefined,
})

C · Backend sem cookies (Firebase callable, API separada)

// Padrão C — backend SEM acesso aos cookies
// (Firebase callable, API em outro domínio, GraphQL...)

// 1) FRONTEND: leia o token e envie junto do pedido de checkout
const referral = window.klikio_referral // o snippet expõe isso
const { url } = await createCheckoutSession({ plano, referral })

// 2) BACKEND (ex.: Firebase Cloud Function callable):
export const createCheckoutSession = onCall(async (request) => {
  const referral = request.data.referral // veio do frontend

  const session = await stripe.checkout.sessions.create({
    // ...sua configuração atual...
    client_reference_id: referral || undefined,
  })
  return { url: session.url }
})

Alternativas aceitas: metadata.aff_ref ou metadata.klikio_referral no lugar do client_reference_id. O valor pode ser undefined (visitante sem afiliado) — nunca quebre o checkout por isso.

4 · Valide com um checkout de teste

O wizard gera um link de teste (?ref=código), verifica o clique chegando e confirma o token no seu checkout — sem compra real. Quando o evento validar, está no ar: cada venda e cada renovação atribuem sozinhas dali em diante.

Como funciona a atribuição

Clique → cookie: o link do afiliado carrega ?ref=; o snippet grava o token pelo prazo da janela do programa. Último clique vence.

Venda → vínculo: o checkout carrega o token; a primeira compra cria o vínculo permanente cliente→afiliado.

Renovações: atribuem pelo cliente, não por cookie — a recorrência não depende do navegador do comprador.

Cupons: vendas com um cupom vinculado a um afiliado contam para ele mesmo sem clique (link explícito sempre vence) — ideal para influencers.

Estornos: reversão proporcional e automática no ledger, antes do dinheiro sair.

Pronto para testar? O modo teste é grátis e ilimitado.

Criar conta