Documentación de Rekomi
Para marcasInstalar el seguimiento
Marcas

Instalar en Paddle

Conecta tu cuenta de Paddle Billing a Rekomi de forma nativa, apunta un destino de notificaciones de Paddle a Rekomi y pega el secreto de firma, para que las ventas y los reembolsos se registren automáticamente sin código en tu backend.

Logo de Paddle

Paddle es un Merchant of Record: tu cliente le paga a Paddle y Paddle te transfiere el dinero. Rekomi se integra con Paddle Billing de forma nativa. Apuntas un destino de notificaciones de Paddle (webhook) directamente a Rekomi y pegas su secreto de firma en tu panel. Rekomi verifica cada evento y registra la conversión, así que no hay ningún reenvío en tu backend que montar ni mantener. ¿Todavía lo estás valorando? Consulta Por qué Rekomi para Paddle →.

La atribución tiene dos mitades: el script de Rekomi captura el clic del afiliado en tus páginas de marketing, y tú llevas esa referencia a Paddle Checkout a través de customData. Cuando Paddle envía el pedido a Rekomi, la referencia del evento se empareja con el afiliado.

¿Buscas un checkout personalizado u otra plataforma? Usa en su lugar la API servidor a servidor; esa vía envía las conversiones desde tu propio backend.

1. Instala el script de cabecera

Pega el script de cabecera de Rekomi en el <head> de tu sitio de marketing, en todas las páginas que puedan llevar a una compra, para que el clic se capture antes de que el comprador abra Paddle Checkout.

<script async src="https://api.rekomi.com/api/v1/r/loader.js" data-program-id="YOUR_PROGRAM_ID" data-rkmi-email-capture="auto"></script>

En un creador de sitios sin código (Webflow, Framer, Squarespace, etc.), usa el campo de código personalizado para el head de la plataforma. Tu ID de programa está en el panel, en Configuración, Seguimiento, Snippet del sitio web (el centro de instalación).

Rekomi registra el correo que un visitante referido escribe en cualquier campo de correo o de texto de las páginas donde se ejecuta la etiqueta (alta, inicio de sesión, checkout y otros formularios) para que la venta se pueda acreditar aunque tu checkout no pase ninguna referencia. Sin referencia no se registra nada. Quita el atributo data-rkmi-email-capture para desactivarlo; las llamadas explícitas a Rekomi.convert() siguen funcionando.

2. Pasa la referencia a Paddle Checkout

Cuando abras Paddle Checkout, adjunta la referencia de window.Rekomi.getReferral() en customData bajo la clave rekomi_ref. Paddle la guarda en la transacción y la incluye en cada webhook de ese pedido.

const referral = window.Rekomi && window.Rekomi.getReferral();
Paddle.Checkout.open({
  items: [{ priceId: 'pri_xxx', quantity: 1 }],
  customData: {
    rekomi_ref: referral || null,
  },
  settings: {
    successUrl: 'https://yourdomain.com/thanks',
  },
});

La clave de customData tiene que ser exactamente rekomi_ref. Ese valor es el slug del enlace de tu afiliado, que es lo que Rekomi usa para emparejar la venta.

Coincidencia por correo del lead (respaldo). Cuando una transacción completada llega a Rekomi sin rekomi_ref, Rekomi también compara el correo del comprador con los leads que el script de Rekomi capturó en tu propio sitio en los últimos 90 días (activa la captura de correo en tu formulario de alta con data-rkmi-email-capture="auto" en la etiqueta del loader; consulta seguimiento de leads) y acredita al afiliado que trajo ese lead. Algo que conviene saber: las notificaciones predeterminadas de Paddle pueden no incluir el objeto del cliente, solo su id, así que el evento en sí puede llegar sin correo. Cuando no lo trae, Rekomi lee el cliente con la clave de API de solo lectura de Paddle del paso 5, siempre que tengas una guardada y uses la captura de leads. Así que el respaldo necesita una de las dos cosas: la entidad del cliente incluida en la notificación, o la clave de API guardada en Rekomi. La referencia en customData siempre gana cuando está presente, igual que el historial previo del cliente, y un afiliado que compra con su propio correo no se acredita.

3. Obtén tu URL de webhook de Rekomi

En Rekomi, abre Guía de configuración, elige Conectar pasarela de pago y haz clic en Conectar Paddle. Rekomi muestra una URL de webhook única para tu espacio de trabajo, por ejemplo:

La página Conectar Paddle en Rekomi con la URL de webhook por espacio de trabajo, la lista de eventos, los campos del secreto de firma y de la clave de API de solo lectura opcional, y el selector de entorno

https://api.rekomi.com/api/webhooks/paddle/<your-token>

Cópiala. Esta URL es única para ti y es la forma en que Rekomi sabe a qué espacio de trabajo pertenece un evento. Mantenla en privado.

4. Crea el destino de notificaciones en Paddle

En Paddle, ve a Developer tools → Notifications → New destination y pega la URL de webhook de Rekomi. Activa estos eventos:

  • transaction.completed
  • subscription.created
  • subscription.updated
  • subscription.canceled
  • adjustment.created
  • adjustment.updated

Guarda el destino, vuelve a abrirlo y copia su secreto de firma (empieza por pdl_ntfset_).

5. Pega el secreto de firma en Rekomi

De vuelta en Conectar Paddle, pega el secreto de firma, elige tu entorno (En vivo o Sandbox) y haz clic en Conectar Paddle. Ese secreto de firma es lo que permite a Rekomi verificar que cada evento entrante viene de verdad de tu cuenta de Paddle; se guarda cifrado y no se vuelve a mostrar.

Si quieres, pega también una clave de API de solo lectura de Paddle (Developer tools → Authentication). No hace falta para registrar una venta que lleva rekomi_ref; Rekomi la usa para validar la conexión al conectar, para las comprobaciones de estado periódicas que confirman que la conexión funciona, y para leer el correo del comprador desde el cliente cuando una notificación no lo incluye y la venta sigue sin atribuir (la coincidencia por correo del lead del paso 2), nunca para recuperar eventos perdidos. El seguimiento funciona solo con el secreto de firma.

Y ya está. A partir de ahora, cada venta completada en Paddle que lleve un rekomi_ref se acredita automáticamente al afiliado correcto.

Reembolsos

Los reembolsos y los contracargos se gestionan automáticamente, sin configurar nada más. Cuando Paddle aprueba un ajuste de reembolso o de contracargo (que llega por los eventos adjustment.created / adjustment.updated), Rekomi revierte la comisión de forma proporcional y actualiza el saldo pendiente del afiliado.

Detalles que conviene conocer

Captura el clic antes de que se abra el overlay. El overlay de Paddle Checkout corre en un iframe que Rekomi no puede tocar, así que la referencia tiene que estar ya capturada (el script de cabecera tiene que haberse ejecutado y window.Rekomi.getReferral() tiene que devolver un valor) antes de que el comprador abra el Checkout. En visitas en frío donde un botón "Comprar" abre el overlay al instante, el loader asíncrono suele ser lo bastante rápido; si ves que se pierden clics, retrasa la apertura del overlay unos 200 ms después de la carga.

Los importes no necesitan conversión. Paddle envía los totales como cadenas de enteros en unidades menores (por ejemplo "4900" = $49.00) y Rekomi los lee tal cual. No los multipliques por 100.

Las comisiones se calculan sobre el importe sin impuestos. Paddle es un Merchant of Record: cobra él mismo el impuesto sobre las ventas y el IVA, así que ese dinero nunca es ingreso tuyo. Rekomi calcula la comisión sobre el total de la transacción menos sus impuestos, descontando cualquier crédito de saldo del cliente que Paddle haya aplicado, y las recuperaciones por reembolso restan el importe sin impuestos del propio reembolso, así que se mantienen exactamente simétricas con lo que se acreditó. Tus afiliados ganan sobre la venta en sí, nunca sobre el impuesto que añadió el país del comprador.

Una sola fuente de conversiones por espacio de trabajo. La conexión con Paddle es excluyente con Stripe (a través de la app de Rekomi para Stripe), Braintree, Shopify, Lemon Squeezy, Chargebee, Polar, Recurly, Gumroad, Creem, Dodo Payments, Mollie y la API S2S, para que la misma venta nunca se cuente dos veces. Desconecta una antes de conectar otra.

Solución de problemas

Una venta de Paddle no apareció en Rekomi. Comprueba tres cosas: que el script de cabecera está en la página que abre el Checkout, que el customData de la transacción contiene rekomi_ref con el slug del afiliado, y que el afiliado está Aprobado. El registro de notificaciones de Paddle muestra la entrega y el código de respuesta de Rekomi para cada evento.

Paddle muestra un 401 del webhook. El secreto de firma en Rekomi falta o no coincide con el del destino. Vuelve a copiar el secreto desde el destino de Paddle y reconecta. Si rotas el secreto en Paddle, tienes que volver a pegarlo en Rekomi. (Un 404 en su lugar significa que el token de la URL del webhook está caducado; reconecta para obtener la URL actual.)

La conexión aparece como rota en Rekomi. El destino se eliminó o su secreto se rotó. Vuelve a crearlo o a copiarlo en Paddle, y después reconecta en la página Conectar Paddle.