Tracking de cliques

O Tracking é a porta de entrada do funil de afiliados: cada hit em um Link de afiliado vira um Clique imutável (clk_ + ULID), com o visitante identificado, a geolocalização derivada do IP e os dados que o módulo de Atribuição usa para ligar uma venda a um afiliado. O objetivo é duplo: medir o tráfego de cada afiliado (separando bots de humanos) e garantir atribuição confiável mesmo quando o clique e a conversão acontecem em momentos ou dispositivos diferentes. A estratégia é server-side first: o id do clique é anexado à URL de destino como repass_cid, para o seu sistema capturá-lo no signup e devolvê-lo na conversão via API. Cookie first-party, e-mail hasheado e fingerprint são fallbacks, nessa ordem.

As rotas de ingestão GET /t/{token}, POST /track/click e POST /track/identify são públicas, não exigem Authorization. O tenant (organização) é derivado do próprio Link, nunca de sessão. Essas rotas têm CORS liberado (GET/POST) e estão fora do mecanismo de Idempotency-Key. As rotas de consulta (/clicks, /links/{id}/stats) exigem sessão ou API key e são sempre escopadas à sua organização.

O fluxo do redirect `/t/{token}`

O redirect é o caminho mais comum: o afiliado divulga uma URL como https://api.userepass.com/t/ana-promo, o visitante clica, o clique é registrado server-side e ele segue para o destino com o repass_cid anexado. Em caso de sucesso, a resposta é um 302 para o destino com repass_cid=clk_... anexado (preservando a query existente) e um Set-Cookie repass_vid (httpOnly, sameSite=lax, secure em produção, maxAge = janela de atribuição em segundos).

curl -i "https://api.userepass.com/t/ana-promo?sub=campanha-x"
# HTTP/1.1 302 Found
# location: https://loja.exemplo.com/?repass_cid=clk_01J9Z8K3M0XQ2R7B4D6F8H0A1C
# set-cookie: repass_vid=vis_01J9Z8K3M0XQ2R7B4D6F8H0A1C; Max-Age=2592000; Path=/; HttpOnly; SameSite=Lax

O token na rota aceita 1 a 64 caracteres (mais permissivo que o formato de criação do Link, 3 a 50 [a-z0-9-]), de propósito: um token malformado responde 404 (e não 400). O lookup é case-insensitive.

Como o destino é resolvido

A URL de destino segue a cadeia destinationUrl do Link → landingUrl do Programa → nenhum destino. Quando há destino, é o redirect 302; quando não há nenhum, o redirect responde 404 (mesmo tendo registrado o clique). A query sub (1 a 120 chars) sobrepõe o subId default do Link, permitindo sub-tracking de campanha por hit. Veja também Links e cupons.

Status que alteram o fluxo

Programa archived, afiliado pending, link inactive...

Situação	Comportamento
Programa `archived` (com landing)	302 para a landing com `repass_notice=program_archived`, sem registrar o clique, sem cookie e sem `repass_cid`
Programa `archived` (sem landing)	410 `error.code: "gone"`
Afiliado `pending`	Redireciona ao destino sem registrar; sem destino algum → 410 `error.code: "gone"`
Afiliado `rejected` / `banned`	410 `error.code: "gone"`
Link `inactive`	410 `error.code: "gone"`
Token inexistente	404 `error.code: "resource_not_found"`

Todas as respostas 410 usam o mesmo error.code gone (apenas a message varia entre “link inativo” e “programa arquivado”). Programa paused e afiliado paused registram cliques normalmente.

Identidade do visitante

Cada clique grava como o visitante foi identificado. Há três sinais, persistidos no próprio Clique:

string (vis_ + ULID)

Identificador do visitante, persistido no cookie first-party repass_vid com maxAge igual à janela de atribuição. Um visitorId recebido (cookie ou payload) só é reaproveitado se for um id válido; caso contrário um novo é gerado silenciosamente: formato inválido nunca é erro.

string (SHA-256 hex)

Associação cross-device. O e-mail nunca trafega cru: apenas o SHA-256 em hex (64 chars). Veja /track/identify abaixo.

string (SHA-256 hex)

Fallback probabilístico de identidade: SHA-256 de ip | user-agent | accept-language, calculado server-side. Por design tem baixa entropia (colide em NAT/CGNAT) e é o último sinal na ordem de matching da atribuição.

Atribuição server-side (S2S)

A atribuição primária não depende de cookie nem de fingerprint: ela depende do id do clique. No redirect, o repass_cid=clk_... é anexado à URL de destino. Seu sistema deve capturá-lo no signup (por exemplo, persistindo-o junto ao usuário) e devolvê-lo no evento de conversão. Esse é o sinal mais forte e o que você deve priorizar.

# Mais tarde, ao registrar a venda, devolva o clique capturado:
curl https://api.userepass.com/conversions \
  -H "Authorization: Bearer rstr_..." \
  -H "Content-Type: application/json" \
  -d '{
    "clickId": "clk_01J9Z8K3M0XQ2R7B4D6F8H0A1C",
    "externalId": "order_9281",
    "amount": 19900
  }'

Quando não há clickId, a conversão cai para os fallbacks na ordem visitorId → emailHash → fingerprint. Os detalhes do algoritmo de candidatos e dos modelos (last-click é o default do Programa) estão em Atribuição e Conversões e fraude.

Valores monetários são sempre inteiros em centavos (19900 = R$ 199,00). Veja Convenções de IDs e recursos.

Geolocalização

A cada clique, o IP é resolvido para country (ISO), region (ISO da primeira subdivisão) e city (nome em inglês). A resolução é best-effort: qualquer falha deixa a geo null e nunca impede o registro do clique. A geo derivada é preservada mesmo depois que o IP é truncado pela minimização de dados (LGPD).

Detecção de bot

Bots são registrados (com bot: true e um botReason), porém ficam fora dos stats públicos e da atribuição, auditáveis e filtráveis via GET /clicks?bot=true.

`botReason`	Critério
`user_agent`	User-agent ausente/vazio (nenhum browser real omite o UA), ou que casa com a lista de padrões: crawlers, headless, `curl`, `wget`, `python-`, `scrapy`, `facebookexternalhit`, `whatsapp`, `telegrambot`, `pingdom`, `lighthouse`, `uptime`, `monitor` etc.
`ip_blocklist`	IP dentro de um CIDR de datacenter bloqueado

Previews de mensageiros (whatsapp, facebookexternalhit, telegrambot) são classificados como bot: um link compartilhado no WhatsApp gera um clique bot: true, não um humano.

Cross-device via e-mail hasheado

Quando o visitante faz signup, seu sistema pode associar o visitorId a um e-mail hasheado com POST /track/identify. Conversões posteriores do mesmo e-mail hasheado, em outro device, atribuem ao clique original, desde que dentro da janela de atribuição.

curl https://api.userepass.com/track/identify \
  -H "Content-Type: application/json" \
  -d '{
    "visitorId": "vis_01J9Z8K3M0XQ2R7B4D6F8H0A1C",
    "emailHash": "a1b2c3d4e5f60718293a4b5c6d7e8f90112233445566778899aabbccddeeff00"
  }'

{
  "id": "vid_01J9ZB2N4P7QX1R5T8V0C2E4G6",
  "organizationId": "org_01J9Z3K8YQ4N2T7B6F0X1A2C3D",
  "visitorId": "vis_01J9Z8K3M0XQ2R7B4D6F8H0A1C",
  "emailHash": "a1b2c3d4e5f60718293a4b5c6d7e8f90112233445566778899aabbccddeeff00",
  "createdAt": "2026-06-13T12:00:00.000Z"
}

O emailHash deve casar ^[a-f0-9]{64}$: e-mail cru é rejeitado com 400. A operação é idempotente por (visitorId, emailHash): um replay devolve 200 com a mesma identidade e não re-emite evento. A organização da identidade vem do clique mais recente do visitante; um visitante sem nenhum clique responde 404 (uma identidade sem clique não tem valor para atribuição).

A identidade fica vinculada à organização do clique mais recente. Se o visitante clicou em links de mais de uma organização, a identidade é criada apenas na org do último clique.

Janela de atribuição e ciclo de vida do clique

O clique não tem um campo de status explícito: seu estado é derivado de expiresAt, convertedAt e ipTruncatedAt. A janela é expiresAt = occurredAt + attributionWindowDays do Programa (default 30 dias, faixa 1 a 365); o cookie repass_vid tem a mesma validade. Não há deduplicação: recarregar a página gera um clique novo. “Únicos” existem apenas nos stats, via visitorId distinto.

LGPD: minimização de IP após 90 dias

Para minimização de dados, o IP completo nunca é retido por mais de 90 dias. Após esse prazo, o IP do clique é truncado:

IPv4 → prefixo /24 (ex.: 200.10.20.0/24)
IPv6 → prefixo /48
IP que não parseia → null

A geo derivada é preservada e o campo ipTruncatedAt é preenchido. O truncamento emite um evento-resumo click.ips_truncated por organização afetada.

O IP completo nunca entra no histórico de eventos: o payload de click.recorded já é gerado com o IP truncado, pois esse payload é entregue nos webhooks de saída. O IP completo fica disponível apenas no registro do clique, dentro da janela de 90 dias, como sinal antifraude.

Consultar cliques (autenticado)

As rotas de consulta exigem sessão ou API key e são escopadas à sua organização.

curl "https://api.userepass.com/clicks?program_id=prog_01J9...&bot=false&limit=25" \
  -H "Authorization: Bearer rstr_..."

curl "https://api.userepass.com/clicks/clk_01J9Z8K3M0XQ2R7B4D6F8H0A1C" \
  -H "Authorization: Bearer rstr_..."

curl "https://api.userepass.com/links/link_01J9.../stats?from=2026-05-01&to=2026-06-01" \
  -H "Authorization: Bearer rstr_..."

GET /clicks usa paginação por cursor e aceita os filtros program_id, affiliate_id, link_id, bot, converted, occurred_after e occurred_before. GET /links/{linkId}/stats retorna { linkId, period: { from, to }, clicks: { total, unique } } no período informado por from/to (default: últimos 30 dias) sempre excluindo bots: unique conta visitorId distintos. Para os parâmetros completos, veja a aba Referência da API.

Eventos emitidos

Cada mudança de estado emite um evento, disponível para você assinar via webhooks. Cliques não registrados (programa arquivado, afiliado pendente, link inativo) não emitem evento algum.

Evento	Quando
`click.recorded`	A cada clique registrado (redirect ou snippet). O `ip` no payload já vai truncado.
`visitor.identified`	Na primeira associação `(visitorId, emailHash)`: replays não re-emitem.
`click.ips_truncated`	Resumo por organização em cada lote da rotina de truncamento de IP.

Consulte o catálogo de eventos para os payloads completos.

Próximos passos

Atribuição

Como o clique vencedor é escolhido (clickId → visitorId → emailHash → fingerprint) e os modelos por programa.

Conversões e fraude

Como registrar vendas server-to-server e os sinais antifraude que usam o tracking.

Links e cupons

Como os tokens de redirect e os sub-ids de campanha são criados.

Integração básica

Passo a passo para colocar o tracking e a primeira conversão no ar.

Introdução

Convenções da API

Conceitos

Webhooks & Eventos

Guias

Tracking de cliques

O fluxo do redirect `/t/{token}`

Como o destino é resolvido

Status que alteram o fluxo

Identidade do visitante

Atribuição server-side (S2S)

Geolocalização

Detecção de bot

Cross-device via e-mail hasheado

Janela de atribuição e ciclo de vida do clique

LGPD: minimização de IP após 90 dias

Consultar cliques (autenticado)

Eventos emitidos

Próximos passos

Atribuição

Conversões e fraude

Links e cupons

Integração básica

​O fluxo do redirect /t/{token}

​Como o destino é resolvido

​Status que alteram o fluxo

​Identidade do visitante

​Atribuição server-side (S2S)

​Geolocalização

​Detecção de bot

​Cross-device via e-mail hasheado

​Janela de atribuição e ciclo de vida do clique

​LGPD: minimização de IP após 90 dias

​Consultar cliques (autenticado)

​Eventos emitidos

​Próximos passos

Atribuição

Conversões e fraude

Links e cupons

Integração básica

O fluxo do redirect `/t/{token}`

Como o destino é resolvido

Status que alteram o fluxo

Identidade do visitante

Atribuição server-side (S2S)

Geolocalização

Detecção de bot

Cross-device via e-mail hasheado

Janela de atribuição e ciclo de vida do clique

LGPD: minimização de IP após 90 dias

Consultar cliques (autenticado)

Eventos emitidos

Próximos passos