Introducción
Los métodos de seguimiento basados en el navegador fallan cada vez más: los bloqueadores de cookies, las políticas ITP/ETP y las cookies de terceros limitadas provocan pérdidas de datos de atribución. Para los comerciantes esto significa liquidaciones de comisiones inseguras y un aumento de las pérdidas por dispersión. Server‑to‑Server (S2S) y Conversions API (CAPI) complementan el seguimiento del lado del cliente y garantizan que las conversiones se registren, validen y entreguen como susceptibles de comisión de forma fiable. Esta guía muestra cómo configurar S2S/CAPI para Affilentra, mapear correctamente los payloads de eventos, evitar duplicados y establecer prioridades de fallback para el proceso de comisiones.
Resumen: arquitectura y roles
Affilentra proporciona la plataforma con separación de roles: el comerciante (Merchant) reporta conversiones, los afiliados facilitan las clic‑/Click‑IDs, y la plataforma se encarga del seguimiento, la validación y la liquidación. Para un funcionamiento resiliente recomendamos una arquitectura híbrida:
- Seguimiento del lado del cliente (pixel/JS) como vía primaria y ligera para transmitir Click‑IDs.
- Eventos del lado del servidor (S2S/CAPI) como fuente fiable para confirmaciones de compra y pago.
- Mecanismos de postback para partners que envíen sus propios eventos desde servidor.
Paso 1 — Configuración básica de la interfaz S2S
Preparación:
- SSL/TLS obligatorio para todos los endpoints.
- Asignación de una clave API o HMAC‑Key a su cuenta de Affilentra (self‑hosted: gestionable localmente).
- Definir un esquema de eventos obligatorio y versionado (p. ej. v1, v2).
Recomendaciones de implementación:
- Exponer un endpoint POST seguro en el lado del comerciante que acepte conversiones y las reenvíe a Affilentra, o enviarlas directamente a Affilentra si su infraestructura lo maneja.
- Autenticación mediante Authorization‑Header (API‑Key) o firma HMAC en header + timestamp para prevenir ataques de reproducción.
- Las respuestas de confirmación deberían devolver un ID único de Server‑Event que Affilentra use para auditorías.
Paso 2 — Mapeo de payloads: campos obligatorios y complementos recomendables
Un mapeo consistente reduce errores en el emparejamiento. Los siguientes campos deberían estar presentes en cada evento S2S:
- event_type: p. ej. purchase, refund, lead
- event_id: ID globalmente único (UUIDv4 o similar) para deduplicación
- transaction_id: número de pedido/pago de la tienda
- click_id / affiliate_id: ID del seguimiento de afiliados (si existe)
- amount y currency: importe bruto y moneda
- status: authorized, paid, refunded — para decidir sobre el derecho a comisión
- timestamp: sello de tiempo ISO8601 en UTC
- user_identifiers: correo electrónico hasheado (SHA256), ID de cliente (opcional) — nunca correos en texto claro
Campos opcionales recomendados:
- item_lines: SKU, quantity, unit_price — para comisiones basadas en producto
- client_ip, user_agent — para análisis forense y comprobaciones de anomalías
- payment_method, shipping_status — para comisiones condicionadas por tiempo
Paso 3 — Dedupliación y validación de conversiones
Objetivo: Aceptar cada conversión solo una vez para el cálculo de comisiones y, al mismo tiempo, armonizar señales legítimas que lleguen múltiples veces.
Estrategia de deduplicación recomendada:
- Clave primaria: event_id. Si event_id está presente y es nuevo, aceptarlo y almacenarlo.
- Clave de respaldo: transaction_id + affiliate_id + ventana. Si falta event_id, el sistema comprueba transaction_id combinado con affiliate_id dentro de una ventana de tiempo configurable.
- Prioridad de fuentes: Asigne a cada fuente un nivel de confianza (ver la siguiente sección). En caso de conflicto, gana la fuente con mayor prioridad.
- Verificación de firma: HMAC o firma comparable para validar la procedencia.
Reglas de validación para elegibilidad de comisión:
- Sólo los eventos con status = paid (o un estado de pago explícitamente confirmado) desencadenan pagos de comisión.
- En caso de reembolsos o contracargos: marcar automáticamente y bloquear o recuperar la comisión, dependiendo de su práctica comercial.
- Comprobar que click_id / affiliate_id sea plausible y coincida con la campaña.
Paso 4 — Prioridades de fallback en el proceso de comisión
Leyenda: Las fuentes pueden ser client (pixel en navegador), server (S2S/CAPI) o partner (postback de afiliado). Recomendación de prioridades para la mayoría de comerciantes:
- 1. Confirmación de pago del lado del servidor (Shop -> Affilentra): Máxima confianza, porque el estado de pago proviene de la base de datos.
- 2. Partner‑Postback con firma validada y transaction_id: prueba directa desde el sistema de afiliados.
- 3. Eventos Server‑CAPI que contienen Click‑IDs y están firmados.
- 4. Evento clientside Pixel/JS: Bueno para tiempo real, pero menor confianza en caso de pérdida de cookies.
- 5. Importaciones manuales/por lotes: Prioridad más baja y sólo para conciliación.
Reglas esenciales:
- Una conversión ya confirmada por una prioridad superior no debe ser sobrescrita por una señal posterior de prioridad inferior.
- Registrar conflictos y hacerlos visibles en procesos de conciliación.
- Ventanas de tiempo configurables: p. ej. atribución inicial por cliente y estado final por servidor dentro de 24–72 horas (ajustable).
Seguridad y protección de datos
Recomendaciones:
- Transmita datos personales solo en forma hash (p. ej. SHA256 del correo electrónico con salt si es necesario).
- Autentique cada solicitud S2S y verifique Timestamp + Nonce para evitar replays.
- Registre solo los datos necesarios para la resolución de problemas y anonimize la información sensible.
- Documente versiones de esquema y ofrezca una estrategia de migración (evitar cambios incompatibles).
Operaciones y monitorización
Así garantiza la seguridad operativa y la trazabilidad:
- Implemente un sistema Dead‑Letter para eventos rechazados/erróneos.
- Alertas ante anomalías (p. ej. caída repentina de eventos S2S o aumento de duplicados).
- Conciliaciones regulares entre pedidos de la tienda, proveedores de pago e informes de Affilentra.
- Registros de auditoría que documenten cambios en reglas de comisión y ajustes manuales.
Caso práctico: mapeo de una confirmación de compra
Payload mínimo aceptable (campos de ejemplo):
- 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: Si falta click_id, el evento aún puede procesarse — sin embargo con una prioridad de atribución menor y una verificación adicional sobre transaction_id.
Resumen
Los eventos S2S/CAPI son imprescindibles para captar conversiones de forma fiable cuando fallan los métodos del lado del cliente. Configure una interfaz S2S firmada y protegida por TLS, utilice event_ids únicos, mapee consistentemente los campos obligatorios e implemente una prioridad clara de fuentes para comisiones. La monitorización, la conciliación y reglas de hashing conformes con la protección de datos completan la configuración. La combinación de pixel del cliente + S2S/CAPI con una validación de desduplicación proporciona la base más robusta para una facturación transparente a través de Affilentra.
Siguiente paso
Probar Affilentra por usted mismo
Plataforma unificada que integra de forma transparente la publicación de productos, el seguimiento, la validación de conversiones, el cálculo de comisiones y los pagos mediante roles claramente diferenciados; opción de instalación self-hosted con licencia perpetua sin participación en ingresos; los comerciantes conservan el control sobre productos, condiciones y creatividades; los socios reciben enlaces de seguimiento personales e historial de pagos verificable.