---
title: "Integración inicial con Paddle"
description: "Integra Paddle con Adapty para gestionar pagos de suscripciones sin complicaciones."
---
Adapty admite flujos de suscripción web2app rastreando pagos y suscripciones web realizados a través de [Paddle](https://www.paddle.com/).
Esta integración cubre las compras iniciadas desde la web y las sincroniza con el acceso a la app móvil y los análisis, junto con las compras in-app de los stores.
Es útil en los siguientes escenarios:
- Recopilar datos de suscripción tanto de compras in-app como de compras en el sitio web en un único sistema
- Conceder acceso a funciones de pago en tu aplicación móvil a usuarios que compraron en tu sitio web
- Ver análisis y datos de suscripción de todos los canales de venta en un solo dashboard
:::note
Apple ahora permite que las aplicaciones de la App Store de EE. UU. incluyan enlaces a sistemas de pago externos, aunque es posible que las aplicaciones aún necesiten ofrecer compras in-app junto con las opciones externas. Consulta las directrices actuales de la App Store para tu región y categoría de aplicación.
:::
:::note
Esta integración se centra en el seguimiento y la sincronización de compras web de Paddle. Si necesitas enviar usuarios desde la app a un checkout web, usa los [paywalls web](web-paywall) de Adapty.
:::
Para configurar la integración con Paddle, sigue estos pasos:
## 1\. Conectar Paddle con Adapty \{#1-connect-paddle-to-adapty\}
La integración utiliza webhooks para enviar datos de suscripción desde Paddle a Adapty. Para conectar tus cuentas de Adapty y Paddle, necesitarás:
1. Proporcionar tus claves API de Paddle.
2. Añadir la URL del webhook de Adapty a Paddle.
:::note
Los pasos a continuación se aplican tanto a Producción como a Test. Puedes configurar ambos simultáneamente. Los enlaces proporcionados corresponden al entorno de Producción — para obtener los enlaces del entorno de Test, simplemente añade `sandbox-` al principio de cada URL. Por ejemplo, usa `https://sandbox-vendors.paddle.com/authentication-v2` en lugar de `https://vendors.paddle.com/authentication-v2`.
:::
### 1.1. Obtén y añade las claves API de Paddle \{#get-and-add-paddle-api-keys\}
1. En Paddle, ve a [Developer Tools → Authentication](https://vendors.paddle.com/authentication-v2) y haz clic en **New API key**.
2. Dale un nombre a la clave y establece la fecha de expiración. Para que la clave API funcione con Adapty, necesitas concederle el permiso **Read** para todas las entidades. Haz clic en **Save**.
3. Haz clic en **Copy key**.
4. En Adapty, ve a [App Settings → Paddle](https://app.adapty.io/settings/paddle) y pega la clave en la sección **Paddle API key**.
:::warning
Si estableciste una fecha de vencimiento para tu clave de API de Paddle, debes generar manualmente una nueva clave y actualizarla en Adapty antes de que expire. La integración dejará de funcionar sin previo aviso cuando la clave caduque, y los usuarios no podrán realizar compras.
:::
### 1.2. Añadir eventos que se enviarán a Adapty \{#add-events-that-will-be-sent-to-adapty\}
1. Copia la **Webhook URL** de la misma página de **Paddle** en Adapty.
2. En Paddle, ve a [**Developer Tools → Notifications**](https://vendors.paddle.com/notifications-v2) y haz clic en **New destination** para añadir un webhook.
3. Introduce un nombre descriptivo para el webhook. Te recomendamos incluir "Adapty" en él para que puedas encontrarlo fácilmente cuando lo necesites.
4. Pega la **Webhook URL** de Adapty en el campo **URL**. Asegúrate de usar el webhook para el entorno correcto.
5. Establece **Notification type** en **Webhook**.
6. Selecciona los siguientes eventos:
- `subscription.created`
- `subscription.updated`
- `transaction.created`
- `transaction.updated`
- `adjustment.created`
- `adjustment.updated`
7. Haz clic en **Save destination** para finalizar la configuración del webhook.
### 1.3. Obtener y añadir la clave secreta del webhook \{#retrieve-and-add-the-webhook-secret-key\}
1. En la ventana **Notifications**, haz clic en los tres puntos junto al webhook que acabas de crear y selecciona **Edit destination**.
2. Aparecerá un nuevo campo llamado **Secret key** en el panel **Edit destination**. Cópialo.
3. En Adapty, ve a [App Settings → Paddle](https://app.adapty.io/settings/paddle) y pega la clave en el campo **Notification secret key**. Esta clave se usa para verificar los datos del webhook en Adapty.
### 1.4. Vincula los clientes de Paddle con los perfiles de Adapty \{#14-match-paddle-customers-with-adapty-profiles\}
Adapty necesita vincular cada compra a un [perfil de cliente](profiles-crm) para que pueda usarse en tu app. De forma predeterminada, los perfiles se crean automáticamente cuando Adapty recibe webhooks de Paddle. Puedes elegir qué valor usar como `customer_user_id` en Adapty:
1. **Predeterminado y recomendado:** El `customer_user_id` que pasas en el campo `custom_data` (ver [documentación de Paddle](https://developer.paddle.com/build/transactions/custom-data))
2. El `email` del objeto Paddle Customer (ver [documentación de Paddle](https://developer.paddle.com/paddle-js/methods/paddle-checkout-open/#parameters))
3. El ID de cliente de Paddle en formato `ctm-...` (ver [documentación de Paddle](https://developer.paddle.com/paddle-js/methods/paddle-checkout-open/#parameters))
4. No crear perfiles. Elige esta opción si quieres tener mayor control sobre los perfiles de tus clientes y gestionarlos tú mismo.
Puedes configurar qué valor usar en el campo **Profile creation behavior** en [App Settings → Paddle](https://app.adapty.io/settings/paddle).
## 2. Añade productos de Paddle a Adapty \{#2-add-paddle-products-to-adapty\}
:::warning
Asegúrate de añadir tus productos de Paddle al Adapty Dashboard o de agregar un ID de producto de Paddle a tus productos existentes. Adapty solo registra eventos para transacciones vinculadas a estos productos. Si omites este paso, no se crearán eventos de transacción.
:::
Paddle funciona en Adapty igual que App Store y Google Play: es otra plataforma donde vendes productos digitales. Para configurarlo, añade los valores de `product_id` y `price_id` correspondientes de Paddle en la sección [Products](https://app.adapty.io/products) de Adapty.
En Paddle, los IDs de producto tienen el formato `pro_...` y los IDs de precio `pri_...`. Los encontrarás en tu [catálogo de productos de Paddle](https://vendors.paddle.com/products-v2) una vez que abras un producto específico:
Una vez añadidos tus productos, el siguiente paso es asegurarte de que Adapty pueda vincular la compra al usuario correcto.
## 3\. Dar acceso a los usuarios en el móvil \{#provide-access-to-users-on-the-mobile\}
Para asegurarte de que los usuarios que compran en la web obtengan acceso en el móvil, llama a `Adapty.activate()` o `Adapty.identify()` usando el mismo `customer_user_id` que pasaste al realizar la compra. Consulta [Identificar usuarios](identifying-users) para más detalles.
## 4\. Probar tu integración \{#test-your-integration\}
Una vez que todo esté configurado, puedes probar tu integración. Las transacciones realizadas en el entorno de Test de Paddle aparecerán como **Test** en Adapty. Las transacciones del entorno de Producción aparecerán como **Production**.
Tu integración ya está completa. Los usuarios pueden comprar suscripciones en tu sitio web y acceder automáticamente a las funciones premium en tu aplicación móvil, mientras tú haces seguimiento de todos los análisis de suscripciones desde tu Adapty Dashboard unificado.
## Consideraciones importantes \{#important-considerations\}
- En las analíticas de Adapty, los importes de las transacciones incluyen impuestos y comisiones de Paddle, lo que difiere del dashboard de Paddle, donde los importes se muestran después de impuestos y comisiones. Esto significa que las cifras que ves en Adapty serán más altas que las de tu dashboard de Paddle.
- A diferencia de otros stores, los reembolsos en Paddle solo afectan a la transacción específica que se reembolsa y no cancelan automáticamente la suscripción. La suscripción seguirá activa a menos que se cancele de forma explícita.
- También puedes incluir `variation_id` en el campo `custom_data` para atribuir compras a instancias de paywall específicas. Adapty procesará estos datos desde los webhooks y los incluirá en las analíticas.
### Períodos de prueba de pago \{#paid-trials\}
Al trabajar con períodos de prueba de pago en Paddle, necesitas crear dos productos en Adapty:
1. Crea un producto que no sea suscripción y vincúlalo al precio de Paddle que cobra por el período de prueba.
2. Luego crea un producto de suscripción (mensual, semanal, etc.) y vincúlalo al precio de Paddle que tiene el componente de prueba gratuita.
Desde el punto de vista de Paddle, se trata de un único producto con dos precios en una sola transacción: un precio para el cargo del período de prueba (p. ej., $0,99) y otro precio para la prueba gratuita ($0,00).
Desde la perspectiva de Adapty, esto genera dos eventos separados: una compra única por el pago de la prueba y un evento de inicio de prueba para el producto de suscripción.
Por ejemplo, cuando un usuario inicia una prueba de pago de $0,99 para una suscripción de $9,99/mes, Paddle crea una sola transacción con ambos precios, mientras que Adapty lo procesa como una compra única de $0,99 (pago inmediato) y un evento de inicio de prueba a $0,00 (suscripción futura a $9,99/mes).
:::note
Cuando los usuarios cancelan una prueba de pago, recibirás los eventos **Trial expired** y **Trial renewal canceled**.
:::
## Saca más partido a tus datos de Paddle \{#get-more-from-your-paddle-data\}
:::important
Para que tus eventos de Paddle funcionen con las integraciones, tus usuarios deben haber iniciado sesión en la app con su cuenta de App Store/Google Play al menos una vez.
:::
Una vez que te integres con Paddle, Adapty está listo para ofrecer información de inmediato. Para aprovechar al máximo tus datos de Paddle, puedes configurar integraciones adicionales de Adapty para reenviar eventos de Paddle, centralizando todos tus análisis de suscripciones en un único Adapty Dashboard.
Integraciones que puedes usar para reenviar y analizar tus eventos de Paddle:
- [AppsFlyer](appsflyer)
- [Webhook](webhook)
- [Posthog](posthog)
## Limitaciones actuales \{#current-limitations\}
- **Cancelaciones**: Paddle tiene dos opciones de cancelación de suscripción:
1. Cancelación inmediata: La suscripción se cancela de inmediato.
2. Cancelación al final del período: La suscripción se cancela al final del período de facturación actual (similar a las suscripciones in-app en los stores).
- **Reembolsos**: Adapty registra los reembolsos totales y parciales.
- **Período de gracia**: Por defecto, Paddle aplica un período de gracia fijo de 30 días para problemas de facturación, durante el cual la suscripción permanece activa. Puedes [personalizar la duración del período de gracia y la acción al final del mismo (pausar o cancelar la suscripción)](https://developer.paddle.com/build/retain/configure-payment-recovery-dunning#prerequisites).
**Pruebas**: Si el cobro falla al finalizar una prueba, el estado de la suscripción cambia a `past_due`. En producción, Paddle Retain aplica una ventana de gestión de impagos para intentar recuperar el pago antes de cancelar o pausar la suscripción. En sandbox, Retain no está disponible, por lo que no se realizan reintentos de pago y la suscripción permanece en `past_due` indefinidamente.
---
**Ver también:**
- [Validar una compra en Paddle, obtener un nivel de acceso e importar el historial de transacciones desde Paddle con la API del lado del servidor](api-adapty/operations/validatePaddlePurchase)