Documentación de Rekomi
Para marcasInstalar el seguimiento
Marcas

Instalar en Dodo Payments

Conecta Dodo Payments de forma nativa: pega una clave de API con acceso de escritura activado y Rekomi crea el endpoint de webhook en el propio Dodo, así que los pagos, las renovaciones de suscripción, los reembolsos y las disputas se registran automáticamente sin pegar nada de vuelta. Lleva rekomi_ref en los metadatos del checkout para que cada venta se acredite al afiliado correcto.

Logo de Dodo Payments

Dodo Payments es un comerciante registrado (Merchant of Record) para productos digitales y SaaS, y Rekomi lo admite de forma nativa. La configuración se reduce a pegar un dato: le das a Rekomi una clave de API con acceso de escritura activado, y Rekomi la valida en vivo, crea el endpoint de webhook en tu propia cuenta de Dodo Payments y obtiene su secreto de firma por ti. No hay nada que pegar de vuelta en Dodo ni ningún formulario de webhook que rellenar a mano. A partir de ahí, los pagos, las renovaciones de suscripción, los reembolsos y las disputas llegan a Rekomi sin código de reenvío que escribir ni mantener. ¿Todavía lo estás valorando? Consulta Por qué Rekomi para Dodo Payments →.

Una cosa que conviene saber desde el principio: la clave debe tener el acceso de escritura activado. Las claves de solo lectura de Dodo pasan la validación normal pero no pueden crear webhooks, así que con una clave de solo lectura la conexión falla a mitad de camino con un error que lo dice tal cual. Después de conectar, la clave solo se usa para gestionar el endpoint de webhook y para una comprobación de salud periódica de solo lectura; tus ventas llegan por el webhook firmado, no por la clave.

Qué necesitas

  • Una cuenta de Dodo Payments en modo en vivo. El modo de prueba es un universo completamente aparte, en otro host (test.dodopayments.com), con sus propias claves y sus propios webhooks; Rekomi rechaza las credenciales de modo de prueba en una conexión de producción con un error claro antes de guardar nada.
  • Una clave de API con acceso de escritura activado. En Dodo Payments, abre Developer > API Keys y crea una clave (llámala "Rekomi"). Las claves de Dodo no caducan; si alguna vez se revoca, las comprobaciones de salud periódicas de Rekomi marcan la conexión como rota y te avisan por correo (también puedes confirmarlo al momento con el botón Comprobar conexión de la página de configuración).
  • Dos minutos. No hay baile de OAuth, ni formulario de webhook, ni secreto que copiar; todo el flujo es pegar un dato.

Conectar en Rekomi

Paso 1. Ve a /dashboard/setup/dodo.

La página Conectar Dodo Payments en Rekomi con el formulario de la clave de API

Paso 2. Pega tu clave de API con acceso de escritura activado y haz clic en Conectar Dodo Payments. Rekomi valida la clave en vivo contra Dodo, crea el endpoint de webhook apuntando a la URL de tu espacio de trabajo con exactamente el conjunto de eventos que necesita y obtiene por sí mismo el secreto de firma del endpoint. Si cualquiera de las dos mitades falla, un endpoint cuyo secreto no se pudo guardar se elimina de nuevo en lugar de dejarlo entregando eventos que Rekomi no puede verificar (en el raro caso de que esa limpieza también falle, el endpoint huérfano se marca para eliminarlo y cuenta para el límite de endpoints de Dodo hasta que lo borres).

Eso es todo. La página de configuración muestra la URL del webhook y los eventos registrados solo como referencia; Rekomi gestiona el endpoint de principio a fin.

Atribución: lleva rekomi_ref en los metadatos del checkout (obligatorio)

Dodo aloja su checkout en su propio dominio, así que el referido del afiliado tiene que viajar desde el navegador del visitante hasta el registro del pago. Este paso es obligatorio para atribuir clientes nuevos: sin él, las ventas llegan sin referido y no se acredita ninguna comisión, salvo que el correo del comprador coincida con un lead capturado en tu sitio (el respaldo que se explica al final de esta sección).

Primero, asegúrate de que el script de seguimiento de Rekomi está instalado en tu sitio de marketing, para que el clic del afiliado se capture y window.Rekomi.getReferral() devuelva un valor cuando un visitante aterriza desde un enlace de afiliado. Ese script es el mismo que usa toda instalación de Rekomi; la receta de tu plataforma en el centro de instalación lo cubre. No hay ningún script específico de Dodo que añadir: la conexión nativa que configuraste arriba es la que registra la venta. Después, elige la receta que encaja con tu forma de vender:

Checkouts creados con la API de Dodo. Lee el referido en tu frontend con window.Rekomi.getReferral(), envíalo a tu backend con la petición de checkout y ponlo en metadata al hacer POST /checkouts, /subscriptions o /payments:

{
  "product_cart": [{ "product_id": "prod_your_product", "quantity": 1 }],
  "metadata": { "rekomi_ref": "REFERRAL_FROM_YOUR_FRONTEND" }
}

Enlaces de pago estáticos. Añade al enlace el parámetro de metadatos en formato plano; Dodo copia los parámetros de consulta metadata_key=value a los metadatos del pago (fíjate en la forma plana con guion bajo, no en la forma con corchetes metadata[rekomi_ref] que usan otras plataformas):

const ref = window.Rekomi?.getReferral?.();
const url = new URL("https://checkout.dodopayments.com/buy/prod_your_product");
if (ref) url.searchParams.set("metadata_rekomi_ref", ref);
// use url.toString() as the href on your Buy button

Los metadatos de la suscripción se conservan durante toda su vida, y Rekomi recurre además al historial de atribución del cliente, así que las renovaciones acreditan al mismo afiliado. El valor se compara con el slug del afiliado sin distinguir mayúsculas de minúsculas, así que un código guardado como SERKAN acredita al afiliado cuyo slug es serkan.

Coincidencia por correo del lead (respaldo). Cuando un pago llega a Rekomi sin rekomi_ref en sus metadatos y el evento lleva el correo del cliente, Rekomi compara además ese correo con los leads que el script de Rekomi capturó en tu propio sitio en los últimos 90 días (la etiqueta que reparte Rekomi lleva data-rkmi-email-capture="auto", que registra como lead el correo escrito en tu formulario de registro; consulta seguimiento de leads) y acredita al afiliado que trajo ese lead. El referido de los metadatos siempre gana cuando está presente, igual que el historial previo del cliente, y un afiliado que compra con su propio correo no se acredita.

Cómo se registran las ventas y las renovaciones

  • Cada cobro llega como un evento de pago. Las compras sueltas, el primer cobro de una suscripción, cada renovación, los cobros por cambio de plan y los cobros de recuperación de una suscripción en espera se registran todos desde el evento payment.succeeded de Dodo, por el importe cobrado.
  • Inicial o renovación se deduce. El evento de pago de Dodo no indica si es el primer cobro o una renovación, así que Rekomi lo deduce: un pago de una suscripción que Rekomi ya ha visto se registra como recurrente, y uno de una suscripción nueva como inicial. Si alguna vez las entregas llegan desordenadas, las dos etiquetas pueden intercambiarse; los importes son siempre correctos, y la comisión sigue la etiqueta asignada (las reglas recurrentes, como los retrasos y los topes, dependen de ella).
  • Las comisiones se calculan sobre el importe de la venta sin impuestos. Dodo Payments es un comerciante registrado e informa del cobro con su desglose de impuestos, así que Rekomi registra la venta menos la línea de impuestos: tus afiliados ganan sobre la venta, no sobre el impuesto que añadió el país del comprador. Los reembolsos y las disputas informan de importes con impuestos incluidos, y toda devolución de comisión está limitada a lo que se acreditó, así que un reembolso o una disputa total retira exactamente el importe comisionable. Un matiz, para ser transparentes: un reembolso parcial no trae desglose de impuestos, así que retira el importe indicado (impuestos incluidos) contra el crédito sin impuestos; algo conservador, nunca por encima del crédito original, y una secuencia de parciales converge exactamente en una devolución total.
  • Las pruebas gratuitas no disparan ningún evento de pago hasta que terminan, así que no existe comisión hasta el primer cobro real. Los eventos del ciclo de vida de la suscripción (activa, en espera, cancelada, caducada) llegan como señales de baja para las reglas de comisión que tienen en cuenta las bajas.
  • Todo se deduplica por los ids subyacentes de pago, suscripción, reembolso y disputa, así que los reintentos y las reentregas manuales de Dodo nunca se cuentan dos veces.

Reembolsos y disputas

Los reembolsos anulan la comisión automáticamente: un reembolso parcial retira la parte reembolsada, y varios parciales siguen retirando hasta agotar la comisión original, nunca más allá. Dodo permite reembolsos hasta 30 días después de la transacción; cada parcial llega como su propio evento de reembolso. Para ser transparentes: a veces Dodo informa de un reembolso total sin importe en el evento; Rekomi lo trata como un reembolso de todo lo que queda en la conversión, que es la lectura segura (la devolución está limitada a la comisión original en cualquier caso). Un evento sin importe que dice ser parcial se marca para revisión en lugar de adivinarlo.

Las disputas (contracargos) retiran el dinero en disputa en cuanto se abre la disputa. Si más adelante la ganas, en esta versión la comisión no se restaura automáticamente; la victoria queda registrada para que la ajustes a mano si quieres. Perder una disputa no cambia nada más (el dinero ya se retiró al abrirse).

Salvedad para quien usa su propio proveedor. Dodo permite a algunos comerciantes procesar a través de su propia cuenta de Stripe o Adyen detrás del checkout de Dodo (BYOP). Los pagos se registran con normalidad en ambos casos, pero los pagos BYOP pueden no emitir nunca webhooks de reembolso ni de disputa (el comerciante los gestiona en su propio proveedor), así que las devoluciones de comisión por reembolsos BYOP son manuales.

Monedas

La función Adaptive Currency de Dodo puede mostrar más de 80 monedas locales en el checkout, y la lista de más de 135 monedas admitidas por Rekomi las cubre todas: VND, NGN, CLP y los códigos de tres decimales KWD, BHD y OMR se registran con normalidad, con el cálculo de tres decimales bien resuelto. En el raro caso de que un importe llegue en una moneda fuera de la lista, ese evento se omite y se marca en lugar de adivinarlo, para que nunca se calcule una comisión sobre un importe deformado.

Seguridad

  • Cada entrega de webhook se verifica por firma (el esquema standard-webhooks: HMAC sobre el id de entrega, la marca de tiempo y el body, con una ventana de frescura de 300 segundos) antes de procesar nada, y cualquier entrega malformada se rechaza.
  • La clave de API y el secreto de firma del webhook se guardan cifrados en reposo y la API nunca los devuelve. Tú nunca ves ni manejas el secreto de firma; Rekomi lo obtiene y lo guarda directamente.
  • Desconectar elimina el endpoint de webhook en Dodo, borra los dos secretos y retira la URL del webhook.
  • El modo en vivo y el modo de prueba están aislados por construcción: son hosts distintos con claves distintas y webhooks distintos, y además los eventos se cotejan con el negocio conectado antes de registrar nada.

Particularidades que conviene conocer

  • Una sola fuente de conversiones por espacio de trabajo. Dodo Payments Connect es excluyente con Stripe (a través de la app de Rekomi para Stripe), Paddle, Braintree, Shopify, Lemon Squeezy, Chargebee, Polar, Recurly, Gumroad, Creem, Mollie y la API S2S, para que la misma venta nunca se cuente dos veces. Desconecta una antes de conectar otra. Y para ser precisos con un caso límite: si vendes a través de Dodo con BYOP sobre tu propia cuenta de Stripe, el carril a conectar es el de Dodo; Stripe Connect no vería esos cobros tal como los informa Dodo.
  • Las claves de API de Dodo no caducan. Si la comprobación de salud marca la conexión como rota, es que la clave se revocó en Dodo, o que el endpoint de webhook se eliminó o se desactivó allí; nunca es una caducidad rutinaria. No hay API para rotar el secreto, así que la recuperación es siempre el mismo pegado: crea una clave nueva con acceso de escritura activado y vuelve a conectar.
  • El endpoint se puede desactivar desde el panel de Dodo. Si pasa, la página de configuración y el correo para reconectar lo dicen expresamente: vuelve a activarlo en el panel de Dodo, o reconecta (lo que lo vuelve a crear).
  • No edites la lista de eventos del endpoint en el panel de Dodo. Rekomi registra el endpoint con exactamente los eventos que necesita; desmarcar cualquiera de ellos detiene esas entregas en silencio (Dodo no muestra ningún error en ninguna parte). La comprobación de salud compara la lista de eventos del endpoint con el conjunto registrado y marca la conexión como rota si se quitaron eventos; reconectar restaura el conjunto completo.
  • Dodo limita los endpoints de webhook por cuenta. Si tu cuenta está en el límite, la conexión falla con un error que lo dice tal cual; elimina un endpoint que no uses en el panel de Dodo y vuelve a intentarlo.
  • Cambiar de modo deja huérfano el endpoint antiguo. El modo en vivo y el de prueba son universos aparte, así que reconectar en otro modo no puede limpiar el endpoint del modo anterior. Si cambias, elimina el endpoint antiguo en el panel de Dodo de ese modo (también cuenta para el límite de endpoints).
  • La cadena de reintentos dura unas 27.5 horas. Dodo entrega hasta 8 veces a lo largo de unas 27.5 horas (al momento, y luego a los 5 segundos, 5 minutos, 30 minutos, 2 horas, 5 horas, 10 horas y 10 horas). Rekomi responde con un error a propósito cuando por un momento no puede procesar un evento de dinero, para que Dodo lo vuelva a entregar; para lo que sobreviva a la cadena, el panel de Dodo tiene registros de entrega con reentrega manual, y Rekomi registra las reentregas de forma segura, sin contar dos veces.
  • La atribución por código de cupón todavía no está conectada para Dodo. La atribución va en los metadatos rekomi_ref; los códigos de descuento por afiliado siguen funcionando como descuentos normales, solo que por sí solos no atribuyen la venta en este carril.

Probar el flujo

El modo de prueba de Dodo es un host aparte, y las conexiones de producción de Rekomi rechazan a propósito las credenciales de modo de prueba, así que un ensayo completo se hace en un entorno de pruebas. Lo que puedes verificar en producción sin gastar dinero:

  1. Conecta y luego haz clic en Comprobar conexión en la página de configuración: sondea en vivo el endpoint de webhook que creó Rekomi (validez de la clave, existencia del endpoint, la marca de desactivado y la lista de eventos del endpoint, en una sola comprobación).
  2. Confirma que el endpoint aparece en tu panel de Dodo en Developer > Webhooks, apuntando a la URL de tu espacio de trabajo.
  3. Haz una compra real a través de un enlace de afiliado con ?via= apuntando al slug de enlace de un afiliado aprobado, confirma la conversión en la pestaña Rendimiento de la campaña en menos de un minuto, luego reembólsala y confirma que la comisión se retira.

Solución de problemas

"...has WRITE ACCESS enabled (read-only keys cannot create webhooks)..." La clave se validó pero no pudo crear el endpoint de webhook. Las claves de solo lectura de Dodo pueden leer tu cuenta pero no escribir en ella; crea una clave con acceso de escritura activado en Developer > API Keys y conecta con esa.

"reached its webhook endpoint limit." Tu cuenta está en el límite de endpoints de Dodo, así que se rechazó la creación. Elimina un endpoint que no uses en el panel de Dodo (Developer > Webhooks) y conecta de nuevo.

"Test mode connections are not available here." Seleccionaste (o tu clave pertenece a) el modo de prueba de Dodo en una conexión de producción. El modo de prueba es un universo aparte; conecta con una clave de modo en vivo.

Aviso "Your Dodo Payments connection is broken." o correo para reconectar. O la clave de API guardada dejó de validarse (se revocó en Dodo), o el endpoint de webhook desapareció o se desactivó, o se editó la lista de eventos del endpoint y ya no está suscrito a todo lo que Rekomi necesita. El mensaje dice cuál de ellas. Si el endpoint está desactivado, vuelve a activarlo en el panel de Dodo o reconecta; para todo lo demás, crea una clave nueva con acceso de escritura activado y reconecta en /dashboard/setup/dodo; tu historial de seguimiento se conserva.

Las ventas llegan pero no se acredita a ningún afiliado. El pago llegó a Rekomi pero no llevaba rekomi_ref. Verifica que tu llamada de creación del checkout pone metadata.rekomi_ref (o que tus enlaces de pago estáticos llevan el parámetro plano ?metadata_rekomi_ref=), y que el script de seguimiento corrió antes de que el comprador hiciera clic (para que window.Rekomi.getReferral() tuviera un valor).

Una venta en una moneda poco habitual no se registró. Rekomi admite más de 135 monedas, así que ahora es raro; si pasa, el evento estaba fuera de la lista y se omitió y se marcó a propósito (consulta Monedas más arriba) en lugar de registrarlo con un valor adivinado.

Falta una conversión después de una caída. La cadena de reintentos de Dodo cubre unas 27.5 horas. Para cualquier cosa anterior, abre la entrega en los registros de webhooks del panel de Dodo y vuelve a entregarla; Rekomi la registra de forma segura, sin contar dos veces.