logo
Conversões•

Enviar eventos de lead e venda pelo seu servidor

Registre um cadastro e uma compra no clique que os gerou — corpos das requisições, o ID do clique, valores em centavos e idempotência.

Avatar for undefined
CodeQR Team
Equipe de Conteúdo

Duas requisições fazem o serviço inteiro: uma quando a pessoa se identifica, outra quando ela paga. As duas rodam no seu servidor, com uma chave de API secreta, e as duas citam o ID do clique que trouxe a pessoa.

Disponibilidade

  • Plano: Pro ou superior, ou o teste de 14 dias.
  • Onde: no seu backend. Crie a chave em Configurações → Chaves de API.

Antes de começar

  • O monitoramento de conversão precisa estar ligado no link ou QR code — Configurar o rastreamento de conversão no seu site.
  • Tenha o ID do clique em mãos. Ele chega como ?cq_id=… na sua URL de destino e fica no cookie cq_id.
  • Escolha um identificador estável para cada cliente no seu sistema. É ele que liga a venda ao lead depois.

Registrar um lead

Chame quando o visitante se torna identificável — cadastro, formulário, início de teste.

curl -X POST https://api.codeqr.io/track/lead \
  -H "Authorization: Bearer codeqr_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "clickId": "qcdyQHsX1oajEock",
    "eventName": "Sign up",
    "customerExternalId": "user_123",
    "customerName": "Ada Lovelace",
    "customerEmail": "ada@example.com"
  }'

A resposta confirma o clique e devolve o cliente que a CodeQR passou a conhecer:

{
  "click": { "id": "qcdyQHsX1oajEock" },
  "customer": {
    "id": "cmszcuwyr0003fdlpmoy3814u",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "externalId": "user_123",
    "country": "BR"
  }
}
  • clickId — leia do cookie cq_id ou do parâmetro na URL. Vazio é aceito: a CodeQR procura um cliente com o mesmo customerExternalId e reaproveita o clique dele.
  • eventName — texto livre, até 255 caracteres. Também é o apelido que uma venda posterior pode apontar.
  • customerExternalId — obrigatório, o seu próprio ID. Tudo que o cliente fizer depois se prende a ele.

Registrar uma venda

curl -X POST https://api.codeqr.io/track/sale \
  -H "Authorization: Bearer codeqr_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customerExternalId": "user_123",
    "amount": 4990,
    "currency": "usd",
    "eventName": "Purchase",
    "paymentProcessor": "stripe",
    "invoiceId": "INV-001"
  }'
{
  "eventName": "Purchase",
  "customerId": "user_123",
  "amount": 4990,
  "paymentProcessor": "stripe",
  "invoiceId": "INV-001",
  "currency": "usd",
  "metadata": null
}
  • amount vai na menor unidade da moeda — 4990 é US$ 49,90. É o erro mais comum e ele é silencioso: uma venda enviada como 49.90 registra 49 centavos.
  • paymentProcessor aceita stripe, shopify, polar, paddle, revenuecat, custom e manual.
  • invoiceId torna a chamada idempotente. Enviar a mesma fatura duas vezes devolve a mesma resposta e não conta em dobro — o que importa, porque webhook de pagamento repete.
  • leadEventName prende a venda a um lead específico, em vez do mais recente.

Vendas que chegam antes do lead

Não é preciso enviar em ordem. Uma venda de um cliente que a CodeQR nunca viu cria o lead implicitamente, desde que ela traga como achar o clique — o customerExternalId já usado antes, ou um clickId.

Verifique se funcionou

Pergunte os contadores ao link alguns segundos depois:

curl -sS "https://api.codeqr.io/links/info?domain=go.example.com&key=verao" \
  -H "Authorization: Bearer codeqr_xxxxxxxxxxxxxxxxxxxxxxxx"
{ "key": "verao", "clicks": 1, "leads": 1, "sales": 1, "saleAmount": 4990 }

Depois abra Clientes e selecione a pessoa: o painel mostra o clique, o lead e a venda em ordem, com o valor.

Solução de problemas

A chamada devolve 404

O clickId não existe ou expirou. Confira o valor lido do cookie e lembre que, sem o monitoramento de conversão, o ID do clique vive só uma hora.

A chamada devolve 200 e nada é registrado

Um lead com clickId vazio e sem cliente correspondente é aceito e descartado — não há a que atribuir. Envie o ID do clique, ou um customerExternalId que a CodeQR já conheça.

A receita ficou cem vezes menor

amount é em centavos. 4990, não 49.90.

A mesma venda contou duas vezes

As duas chamadas usaram invoiceId diferentes, ou nenhum. A idempotência é por esse campo e vale por sete dias.

A venda não aparece na aba Events

A listagem de eventos de venda está falhando hoje. Use Clientes ou os contadores do link; os dois estão corretos.

Artigos relacionados