Introducción
Los webhooks son la columna vertebral de las integraciones modernas: impulsan la automatización en tiempo real, reducen el trabajo manual y mejoran la transparencia entre comerciantes, socios y sistemas de facturación. Para los operadores de programas de afiliación resulta especialmente crítico sincronizar de forma fiable los eventos de conversión, la preparación de pagos y la ejecución de los mismos. Este artículo muestra flujos de trabajo prácticos con webhooks en Affilentra —incluyendo plantillas de payload y notas de integración para sistemas contables, proveedores de pago y sistemas ERP internos.
¿Por qué webhooks con Affilentra?
Affilentra ofrece una plataforma de afiliación self-hosted con roles claramente separados (operador del software, comerciante, socio). Los webhooks permiten aquí enviar eventos del programa de afiliación de forma automatizada a sistemas externos: conversiones validadas, listas de pago preparadas y actualizaciones de estado. Gracias a la arquitectura self-hosted, los comerciantes mantienen la gobernanza de los datos y pueden operar puntos finales de webhook por sí mismos o integrarlos en middleware existente.
Tipos de eventos esenciales y su uso
Los siguientes eventos forman la base para flujos de trabajo prácticos:
- conversion.created – se registró y validó un evento de seguimiento.
- conversion.updated – cambios de estado (p. ej., chargeback, reembolso, conversión confirmada).
- payout.prepared – se creó una lista de pago o una entrada de pago para la contabilidad.
- payout.paid – el pago se ha transmitido al proveedor de pago o se ha marcado como abonado.
- accounting.export_ready – los datos relevantes para la contabilidad están listos para exportar (p. ej., como asiento contable o CSV).
- erp.update_required – cambio de estado que debe actualizarse en el ERP interno (p. ej., estado de cumplimiento o de factura).
Plantillas de payload (ejemplos)
Los siguientes payloads están pensados como plantillas para la integración. Ajuste los campos a su esquema interno y procese solamente los campos que necesite.
conversion.created (ejemplo)
{
"event": "conversion.created",
"timestamp": "2026-11-04T10:15:30Z",
"conversion": {
"id": "conv_12345",
"merchant_id": "m_987",
"partner_id": "p_456",
"offer_id": "o_22",
"amount": 149.90,
"currency": "EUR",
"status": "pending_validation",
"meta": { "order_ref": "ORD-20261104-001" }
}
}
payout.prepared (ejemplo)
{
"event": "payout.prepared",
"timestamp": "2026-11-04T11:00:00Z",
"payout": {
"id": "po_20261104_01",
"merchant_id": "m_987",
"partner_id": "p_456",
"gross_amount": 320.00,
"fees": 5.00,
"net_amount": 315.00,
"currency": "EUR",
"payout_method": "bank_transfer",
"batch_id": "batch_20261104",
"entries": [ { "conversion_id": "conv_12345", "amount": 120.00 }, { "conversion_id": "conv_12346", "amount": 200.00 } ]
}
}
payout.paid (Ejemplo)
{
"event": "payout.paid",
"timestamp": "2026-11-04T12:30:00Z",
"payout": {
"id": "po_20261104_01",
"paid_at": "2026-11-04T12:28:00Z",
"transaction_id": "txn_7890",
"provider_status": "settled"
}
}
accounting.export_ready (Ejemplo)
{
"event": "accounting.export_ready",
"timestamp": "2026-11-04T12:35:00Z",
"export": {
"id": "exp_20261104_01",
"format": "csv",
"records": [ { "account_code": "8400", "debit": 0, "credit": 315.00, "description": "Affiliate Payout" } ]
}
}
Flujos típicos de integración
1) Conversión → Preparación contable
Flujo: conversion.created → conversion.updated (confirmado) → accounting.export_ready.
- En conversion.created: almacene un registro mínimo en la capa intermedia, realice validaciones (p. ej. duplicados, referencias CVR/pedido).
- En conversion.updated con estado confirmed: genere el asiento contable (cliente, ingresos, IVA) o marque la conversión para incluirla en la siguiente exportación.
- En accounting.export_ready: genere CSV/DATEV/JSON y colóquelo en el directorio contable o envíelo por SFTP a su asesor fiscal.
2) Preparación de pago → Proveedor de pagos
Flujo: payout.prepared → API del proveedor de pagos → payout.paid.
- payout.prepared: genere un lote con entradas de pago, compruebe límites y disponibilidad (saldo, estado KYC).
- Envíe el lote a su proveedor de pagos; utilice llamadas idempotentes y proporcione batch_id como referencia.
- Reciba la respuesta del proveedor, marque las transacciones y espere el evento payout.paid para el asiento final.
3) Sincronización ERP para cumplimiento y estado de facturas
Flujo: conversion.updated / erp.update_required → API del ERP.
- En cambios de estado (p. ej. fulfilled, refunded) Affilentra envía un evento erp.update_required.
- Mapeo: external_reference → número de pedido en el ERP; actualice el estado de cumplimiento, los números de factura y el estado de pago.
- Buenas prácticas: use acuse de recibo por lotes, limitación de tasa y verifique la unicidad de las referencias.
Buenas prácticas para integraciones robustas
- Seguridad: Firme las cargas útiles de los Webhooks con HMAC (SHA256) y verifique marcas de tiempo para prevenir ataques de reproducción.
- Idempotencia: Procese la misma event_id varias veces sin efectos secundarios. Use claves de idempotencia dedicadas.
- Manejo de errores: Implemente lógica de reintento con backoff exponencial; registre las entregas fallidas de forma centralizada.
- Versionado: Introduzca un campo de versión del esquema del evento para mantener la compatibilidad ante cambios de esquema.
- Batching: Envíe eventos agregados para contabilidad y pagos (p. ej. batch_id) para reducir esfuerzo y latencia.
- Minimización de datos: Envíe solo los campos que los sistemas de destino necesitan; externalice metadatos adicionales de forma opcional.
- Monitorización: Supervise tasas de entrega, latencia y tasa de errores; notifique a los responsables ante fallos.
Indicaciones según rol
- Comerciante (Merchant): Establezca endpoints de Webhook, seleccione eventos y defina métodos de pago. El self‑hosting permite control total sobre los flujos de datos.
- Socio (Publisher): Benefíciese de enlaces de seguimiento auditables y notificaciones transparentes de estado de pago, que pueden entregarse vía Webhooks a paneles o herramientas contables.
- Operador de software: Proporcione firmas seguras, documentación y monitorización; ofrezca plantillas y ejemplos de mapeo para proveedores contables y de pagos comunes.
Ejemplos prácticos: pasos de implementación
- Defina los eventos relevantes y un conjunto mínimo de campos necesarios (p. ej. conversion_id, amount, currency).
- Configure una middleware o un pequeño servicio receptor que valide Webhooks, deduplique y enrute a los sistemas destino.
- Implemente firmas HMAC y verifique marcas de tiempo dentro de una ventana corta (p. ej. 5 minutos).
- Pruebe con eventos simulados: conversion.created → payout.prepared → payout.paid → accounting.export_ready.
- Documente códigos de error y procesos de recuperación para sus equipos de finanzas y operaciones.
Conclusión y siguiente paso
Con Affilentra se pueden modelar de forma práctica y segura los flujos de trabajo de Webhooks para el seguimiento de conversiones, la preparación de pagos y los exportes contables —especialmente en escenarios self‑hosted donde el control y la protección de datos son centrales. La combinación de esquemas de eventos claros, procesamiento idempotente y lotes de pago controlados reduce el trabajo manual y aumenta la transparencia para comerciantes y socios.
¿Listo para usar Webhooks en producción? Elegir inicio
Siguiente paso
Probar Affilentra
Plataforma unificada que integra de forma transparente la entrega de productos, el seguimiento, la validación de conversiones, el cálculo de comisiones y los pagos con roles claramente diferenciados; opción de instalación self-hosted con licencia perpetua sin participación en ingresos; los comerciantes mantienen el control sobre productos, condiciones y materiales promocionales; los socios reciben enlaces de seguimiento personales e historial de pagos comprobable.