Conectar Paddle
Pega una clave de API de Paddle de solo lectura para importar ventas de software y SaaS, reembolsos e impuestos por producto y país.
Paddle es el merchant of record del software que vendes fuera de las tiendas de apps: apps de escritorio, apps web, planes SaaS y licencias. Se conecta con una única clave de API de solo lectura en lugar de OAuth. Creas la clave en el panel de Paddle, la pegas en Revenue Sensor y eliges qué productos de Paddle sincronizar. La clave se guarda cifrada y nunca sale de nuestro servidor; tu inicio de sesión de Paddle nunca interviene.
Antes de empezar
- Acceso al panel de Paddle de la cuenta de vendedor cuyas ventas quieres seguir, con permiso para crear claves de API en Developer tools.
- Saber si quieres la cuenta live o el sandbox. Paddle emite claves distintas para cada uno, y la clave decide cuál leemos; no hay nada más que elegir.
Crea una clave de API de solo lectura
- 1
Abre Developer tools
En el panel de Paddle, ve a Developer tools → Authentication y crea una nueva clave de API. Ponle un nombre que reconozcas después, como «Revenue Sensor».
- 2
Concede solo permisos de lectura
Marca acceso de lectura para Transactions, Adjustments, Products y Addresses. Addresses aparece bajo Customers y nos da el país del comprador, así que déjalo aunque parezca no tener relación. No hacen falta permisos de escritura.
- 3
Copia la clave una sola vez
Paddle muestra la clave una única vez al crearla. Cópiala de inmediato; si la pierdes, revócala y crea otra.
Conecta la cuenta
- 1
Pégala
Integrations → Paddle → Connect en la consola de Revenue Sensor y pega la clave de API. Revenue Sensor lee el prefijo para distinguir una clave live de una de sandbox y confirma cuál usará antes de continuar.
- 2
Elige tus productos
Las unidades que sincronizas son productos de Paddle, no apps de tienda. Elige los productos que quieres en el libro; cada uno aparece como su propia línea de ingresos y puede asignarse a una app si pertenece a alguna. Solo se obtiene lo que seleccionas, y solo eso cuenta para tu plan.
- 3
Deja que corra la primera sincronización
Paddle conserva todo tu historial, así que la primera sincronización rellena hasta un año de transacciones pagadas y reembolsos. Suele tardar unos minutos y puedes salir de la página mientras se ejecuta.
Qué se importa
| Campo | Notas |
|---|---|
| Ingresos | Transacciones pagadas, registradas el día en que se cobró el dinero y no el día en que se emitió la factura. Se muestran por producto, por día y por país del comprador, sin impuestos. La comisión de Paddle no se descuenta, igual que Google Play se muestra en bruto antes de la comisión de Google. |
| Impuestos | Paddle recauda el impuesto sobre ventas y el IVA como merchant of record y lo indica en cada línea, así que el impuesto se importa por separado y la vista con impuestos incluidos está disponible para esta fuente. |
| Reembolsos y contracargos | Los reembolsos y contracargos aprobados reducen los ingresos el día en que se aprueban, y el importe también se registra como cifra de reembolso a modo de contexto. Un contracargo revertido devuelve el dinero. Los créditos y los avisos de contracargo no se tratan como reembolsos. |
| País | Tomado de la dirección de facturación del cliente. Solo se usa el código de país. |
Todas las monedas de Paddle son compatibles
Las transacciones se importan en la moneda en que se cobraron y se convierten como cualquier otra fuente. Las monedas sin decimales, como JPY y KRW, se leen correctamente, así que una venta en Japón no se registra a una centésima de su valor.
Actualizaciones en tiempo real (opcional)
Revenue Sensor sincroniza Paddle cada 30 minutos. Si prefieres ver una venta o un reembolso nuevos en uno o dos minutos, apunta un destino de notificaciones de Paddle hacia nosotros. Las cifras siguen viniendo de la API de Paddle; el webhook solo nos indica que sincronicemos antes.
- 1
Copia la URL del webhook
Abre la conexión de Paddle en la consola de Revenue Sensor. El panel «Real-time updates» muestra una URL única para esta conexión; cópiala.
- 2
Crea un destino de notificaciones
En Paddle ve a Developer tools → Notifications → New destination. Pega la URL, elige Webhook como tipo y suscríbete a los eventos transaction, adjustment y subscription.
- 3
Guarda el secreto
Paddle muestra un secreto de firma al crear el destino. Pégalo en el panel «Real-time updates» y guarda. Lo usamos para verificar cada entrega y descartar todo lo que no esté firmado; se guarda cifrado y no vuelve a mostrarse.
Resolución de problemas
- La clave es rechazada: comprueba que tiene acceso de lectura a los cuatro apartados Transactions, Adjustments, Products y Addresses. Una clave sin Addresses pasa una comprobación básica pero falla en la sincronización.
- No aparece ningún producto: la clave pertenece a otra cuenta, o al sandbox cuando esperabas live (o al revés). El prefijo de la clave te dice cuál es.
- Falta una venta: solo se importan transacciones pagadas y completadas. Los borradores, las facturas sin pagar y las transacciones canceladas todavía no son ingresos.
- Los ingresos parecen mayores que tu liquidación: es lo esperado. El impuesto se mantiene aparte y la comisión de Paddle no se descuenta, así que la cifra es el ingreso bruto antes de la parte de Paddle.
- Un reembolso aparece en un día distinto al de la venta: los reembolsos se registran el día en que se aprueban, no se retrotraen a la compra original.