Introdução
Métodos de rastreio baseados no navegador estão a falhar cada vez mais: bloqueadores de cookies, políticas ITP/ETP e restrições nos cookies de terceiros causam perda de dados de atribuição. Para comerciantes, isto significa faturação de comissões incerta e maiores perdas por dispersão. Server‑to‑Server (S2S) e Conversions API (CAPI) complementam o rastreio do lado do cliente e garantem que conversões são registadas, validadas e disponibilizadas para comissionamento de forma fiável. Este guia mostra como configurar S2S/CAPI para a Affilentra, mapear corretamente os payloads de eventos, evitar duplicados e definir prioridades de fallback para o processo de comissionamento.
Visão geral: arquitetura e papéis
A Affilentra fornece a plataforma com papéis separados: o Comerciante (Merchant) reporta conversões, os Affiliates fornecem IDs de clique/click‑IDs, e a plataforma trata do rastreio, validação e faturação. Para operação resiliente recomendamos uma arquitetura híbrida:
- Rastreio do lado do cliente (Pixel/JS) como via primária e leve para transmitir Click‑IDs.
- Eventos do lado do servidor (S2S/CAPI) como fonte fiável para confirmações de conversão e pagamento.
- Mecanismos de postback para parceiros que enviam eventos a partir dos seus próprios servidores.
Passo 1 — Configuração básica da interface S2S
Preparação:
- SSL/TLS obrigatório para todos os endpoints.
- Atribuição de uma chave API ou HMAC‑Key à sua conta Affilentra (self‑hosted: gerível localmente).
- Definir um esquema de evento obrigatório e versão (por exemplo, v1, v2).
Recomendações de implementação:
- Exponha um endpoint POST seguro no lado do comerciante que aceite conversões e as encaminhe para a Affilentra ou envie directamente para a Affilentra se a sua infraestrutura o suportar.
- Autenticação via Authorization‑Header (API‑Key) ou assinatura HMAC em headers + Timestamp, para prevenir ataques de replay.
- As respostas de confirmação devem devolver um ID único de Server‑Event que a Affilentra utilize em auditorias.
Passo 2 — Mapeamento de payload: campos obrigatórios e complementos úteis
Um mapeamento consistente reduz erros de matching. Os seguintes campos devem constar em cada evento S2S:
- event_type: ex. purchase, refund, lead
- event_id: ID globalmente único (UUIDv4 ou similar) para deduplicação
- transaction_id: número de encomenda/pagamento da loja
- click_id / affiliate_id: ID do tracking de afiliados (se existir)
- amount e currency: valor bruto e moeda
- status: authorized, paid, refunded — para decisão sobre direito à comissão
- timestamp: carimbo de data/hora ISO8601 UTC
- user_identifiers: email hashed (SHA256), ID do cliente (opcional) — nunca emails em texto simples
Campos opcionais recomendados:
- item_lines: SKU, quantity, unit_price — para comissões baseadas em produto
- client_ip, user_agent — para análises forenses e deteção de anomalias
- payment_method, shipping_status — para comissões temporizadas
Passo 3 — Deduplicação & validação de conversões
Objetivo: aceitar cada conversão apenas uma vez para cálculo de comissões, ao mesmo tempo que se harmonizam sinais legítimos que chegam múltiplas vezes.
Estratégia de deduplicação recomendada:
- Chave primária: event_id. Se event_id estiver presente e for novo, aceitar e armazenar.
- Chave de fallback: transaction_id + affiliate_id + intervalo. Se event_id estiver ausente, o sistema verifica transaction_id combinado com affiliate_id dentro de uma janela de tempo configurável.
- Prioridade das fontes: atribua a cada fonte um nível de confiança (ver seção seguinte). Em caso de conflitos, vence a fonte com prioridade mais alta.
- Verificação de assinatura: HMAC ou assinatura equivalente para validar a origem.
Regras de validação para elegibilidade de comissão:
- Apenas eventos com status = paid (ou estado de pagamento explicitamente confirmado) disparam pagamentos de comissão.
- No caso de reembolsos ou chargebacks: marcar automaticamente e bloquear ou recuperar a comissão, dependendo da sua prática comercial.
- Verificar se click_id / affiliate_id é plausível e corresponde à campanha.
Passo 4 — Prioridades de fallback no processo de comissão
Legenda: as fontes podem ser client (pixel no browser), server (S2S/CAPI) ou partner (postback de afiliado). Recomendações de prioridade para a maioria dos comerciantes:
- 1. Confirmação de pagamento server-side (Loja -> Affilentra): confiança máxima, porque o estado de pagamento vem da base de dados.
- 2. Partner-postback com assinatura validada e transaction_id: prova direta do sistema de afiliados.
- 3. Eventos Server-CAPI que contenham Click-IDs e estejam assinados.
- 4. Evento client-side Pixel/JS: bom para tempo real, mas com menor confiança em casos de perda de cookies.
- 5. Importações manuais/em lote: prioridade mais baixa e apenas para reconciliação.
Regras essenciais:
- Uma conversão já confirmada por um sinal de prioridade mais alta não deve ser sobrescrita por um sinal posterior de prioridade inferior.
- Registre conflitos e torne‑os visíveis em processos de reconciliação.
- Janelas de tempo configuráveis: por ex., atribuição inicial pelo cliente e status final pelo servidor dentro de 24–72 horas (ajustável).
Segurança e proteção de dados
Recomendações:
- Transmita dados pessoais apenas em forma hashed (por ex., SHA256 do e‑mail com salt, se necessário).
- Autentique cada requisição S2S e verifique Timestamp + Nonce para evitar replay.
- Registe apenas os dados necessários para troubleshooting e anonimizar informações sensíveis.
- Documente versões de esquema e ofereça uma estratégia de migração (evitar breaking changes).
Operações e monitorização
Como garantir segurança operacional e rastreabilidade:
- Implemente um sistema Dead‑Letter para eventos rejeitados/defeituosos.
- Alertas para anomalias (por ex., queda súbita de eventos S2S ou aumento de duplicados).
- Reconciliações regulares entre pedidos da loja, provedores de pagamento e relatórios Affilentra.
- Audit‑logs que documentem alterações em regras de comissão e ajustes manuais.
Caso prático: Mapeamento de uma confirmação de compra
Payload mínimo aceitável (campos de exemplo):
- event_type: purchase
- event_id: uuid-xyz
- transaction_id: 2026‑000123
- click_id: abc123
- amount: 129.90
- currency: EUR
- status: paid
- timestamp: 2026-10-23T12:34:56Z
- user_identifiers: {email_hash: "sha256:..."}
Importante: Se click_id estiver em falta, o evento ainda pode ser processado — porém com prioridade de atribuição mais baixa e verificação adicional do transaction_id.
Resumo
Eventos S2S/CAPI são indispensáveis para captar conversões de forma fiável quando métodos do lado do cliente falham. Configure uma interface S2S assinada e protegida por TLS, utilize event_ids únicos, mapeie campos obrigatórios de forma consistente e implemente uma prioridade de origem clara para comissões. Monitorização, reconciliação e regras de hashing compatíveis com proteção de dados completam a configuração. A combinação de pixel do cliente + S2S/CAPI com validação deduplicadora fornece a base mais robusta para faturação transparente através da Affilentra.
Próximo passo
Experimentar a Affilentra
Plataforma unificada que reúne de forma transparente fornecimento de produtos, tracking, validação de conversões, cálculo de comissões e pagamentos entre funções claramente separadas; opção de instalação self-hosted com licença perpétua sem participação na receita; comerciantes mantêm o controlo sobre produtos, condições e materiais promocionais; parceiros recebem links de tracking pessoais e historial de pagamentos rastreável.