Conversões e receita

O rastreamento de conversões fecha o ciclo entre um clique e o dinheiro que ele gerou. O redirecionador emite um identificador assinado em cada redirecionamento; o seu servidor ou a sua página de agradecimento devolve esse identificador junto com um pedido; todo detalhamento que você já lê ganha uma coluna de receita.

As conversões são um recurso pago. Quando o plano não as inclui, o redirecionador para de emitir identificadores por completo, e as duas vias de entrada recusam conversões com uma restrição de plano.

O identificador de clique

Em cada redirecionamento o worker emite um token e:

• acrescenta o token ao endereço de destino sob um nome de parâmetro escolhido por você (lp_cid por padrão);
• grava o token em um cookie de origem própria no seu domínio de redirecionamento, válido por 90 dias.

É o cookie que faz a atribuição sobreviver em navegadores que não aceitam mais nada de terceiros: quem o define é o seu próprio domínio, não o nosso.

O token é assinado e amarrado ao tenant: os identificadores do espaço de trabalho e do parceiro fazem parte do payload assinado, então um token emitido no link de um cliente é recusado no espaço de trabalho de outro cliente exatamente como uma falsificação. Ele não carrega nenhum dado pessoal — o momento do clique, o link, a variante de split, o país, a classe do dispositivo, a origem do tráfego e uma marca para tráfego suspeito.

Tanto o nome do parâmetro quanto a chave de liga e desliga ficam em Conversões → Configurações. Mudar qualquer um dos dois reescreve na hora a configuração em cache de todos os links.

A janela de atribuição

Uma conversão que chega depois da janela é recusada com attribution_expired, um código distinto de invalid_click_id, para que uma integração consiga separar “tarde demais” de “identificador quebrado” sem adivinhação. A janela é uma configuração de cada espaço de trabalho.

Metas

Uma meta é um desfecho com nome: purchase, signup, trial. As metas podem carregar um valor padrão e uma moeda, usados quando uma conversão chega sem valor. Uma meta citada por uma conversão e que ainda não existe é criada no primeiro uso, então uma integração não precisa ser configurada em dois lugares.

Enviar conversões

Do seu servidor

curl -X POST https://api.linkprofit.com/v1/conversions \
  -H "Authorization: Bearer lp_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10241" \
  -d '{
    "click_id": "1.eyJ1aWQiOiJ...",
    "goal": "purchase",
    "order_id": "10241",
    "amount_cents": 4999,
    "currency": "usd"
  }'

A chave precisa do escopo conversions:write. Os valores são unidades mínimas inteiras — centavos, pence, copeques. Um valor de 49.99 é recusado com o campo apontado, em vez de arredondado em silêncio, porque uma regra de arredondamento inventada no meio de um caminho de pagamento é justamente como relatórios de receita param de bater com as faturas.

Do navegador

O worker serve um script pequeno a partir do seu próprio domínio de redirecionamento:

<script src="https://go.example.com/cv.js" defer></script>
<script>
  window.lpConversion({ goal: 'purchase', orderId: '10241', amountCents: 4999, currency: 'usd' });
</script>

O script lê o identificador da URL ou do cookie de origem própria. Não existe nenhum host de terceiros em ponto algum da cadeia, o que é ao mesmo tempo uma propriedade de privacidade e uma propriedade white-label: a página do seu cliente não carrega nada que mencione a plataforma.

Duplicatas

A deduplicação é uma única inserção atômica, não uma leitura seguida de uma escrita. Entregas repetidas do mesmo order_id criam uma conversão só e a devolvem marcada como duplicata — e é exatamente isso que torna seguro, e não perigoso, repetir um webhook que falhou.

Conversões suspeitas

O veredito do classificador viaja dentro do token, então uma conversão atribuída a um datacenter ou a um proxy é marcada como suspeita no momento em que é registrada. Nos relatórios ela aparece como um segmento próprio, em vez de ser excluída ou misturada em silêncio. “Duzentas conversões” e “duzentas conversões, quarenta delas vindas de uma única faixa de hospedagem em uma hora” são fatos diferentes.

Para onde as conversões vão depois

• Um evento de webhook assinado conversion.created é emitido pela maquinaria normal de webhooks: fila, assinatura, cronograma de novas tentativas, cron de recuperação.
• As integrações de publicidade configuradas recebem a conversão por uma fila de entrega com um contador de tentativas incrementado antes da chamada de saída, um backoff documentado e uma marca de desistência no lugar de tentativas infinitas.

Cota mensal

Um plano pode limitar o número de conversões aceitas por mês do calendário, contadas em UTC. Passado o teto, a entrada responde quota_exceeded — um código distinto de uma restrição de plano, para que a diferença entre “não está no seu plano” e “acabou este mês” fique visível sem abrir um chamado no suporte.