Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

Las Entitlements convierten un pago exitoso o una suscripción activa en acceso real: una clave de licencia en la bandeja de entrada de tu cliente, un rol en Discord, un repositorio de GitHub, una plantilla de Notion, un enlace de remix de Framer, una invitación a un chat de Telegram o un paquete de archivos descargables. Dodo Payments emite, rastrea y revoca ese acceso automáticamente a medida que cambia el ciclo de vida del pago.
Panel de control de Entitlements con una lista de entitlements a la izquierda y actividad de concesiones a la derecha

​
¿Qué son las Entitlements?

Un entitlement es una definición reutilizable de algo que entregas a un cliente: una clave de licencia Pro, un rol de Discord de “Patrons”, acceso a tu repositorio privado en GitHub, un paquete de libros electrónicos descargables. Adjuntas entitlements a productos, y Dodo Payments se encarga del resto. Cuando un cliente compra el producto, Dodo Payments crea una concesión, una emisión individual de ese entitlement para el cliente. Las concesiones pasan por un pequeño conjunto de estados: pending mientras la entrega está en progreso, delivered una vez que el cliente tiene acceso, failed si la entrega no se pudo completar, e revoked cuando el acceso es retirado.
Las Entitlements regulan el cumplimiento (¿tiene acceso el cliente?). Los créditos regulan el consumo (¿cuánto pueden usar?). Ambos se pueden adjuntar al mismo producto. Ver Facturación Basada en Créditos para créditos.

​
Integraciones Disponibles

Dodo Payments entrega cada entitlement a través de una integración dedicada. Elige la integración que se adapte a lo que vendes.

License Keys

Genera claves de licencia únicas con límites de activación y expiración. Ideal para software, plugins y CLIs.

Digital Files

Entrega archivos descargables (libros electrónicos, plantillas, medios) con URLs de descarga presignadas e instrucciones opcionales.

Discord

Concede un rol en tu servidor de Discord a un cliente cuando realiza una compra. Revoca automáticamente si se cancela.

GitHub

Añade clientes como colaboradores a un repositorio privado al nivel de permiso que elijas.

Telegram

Añade clientes a un chat o canal privado de Telegram después de la compra.

Framer

Desbloquea un enlace de remix de una plantilla de Framer para los clientes que paguen.

Notion

Duplica una plantilla de Notion en el espacio de trabajo del cliente en el momento de la compra.

​
Cómo Funcionan las Concesiones

Las concesiones son impulsadas por los mismos eventos de pago y suscripción que ya recibes como webhooks. No necesitas llamar tú al API de concesiones para las compras. Dodo Payments crea y revoca concesiones automáticamente según el ciclo de vida del pago subyacente.

​
Ciclo de Vida de la Concesión

1

Created

Se crea una concesión cuando se completa un pago o una suscripción se vuelve activa. Las claves de licencia pasan directamente a delivered. Todas las demás integraciones comienzan en pending. Las integraciones basadas en OAuth (Discord, GitHub, Notion) incluyen un oauth_url que el cliente debe visitar para completar el consentimiento. Las integraciones directas de la plataforma (Telegram, Framer, Archivos Digitales) permanecen en pending sólo brevemente mientras se aprovisiona la entrega, luego pasan a delivered.
2

Delivered

Una vez completada la entrega (clave de licencia generada, rol asignado, acceso al repositorio concedido, enlaces de archivo resueltos, OAuth completado), la concesión se mueve a delivered y se establece delivered_at.
3

Failed

Si la llamada de integración devuelve un error no recuperable (token de OAuth revocado, permiso denegado, archivo ya no existe), la concesión se mueve a failed. Los campos error_code e error_message capturan la razón.
4

Revoked

Cuando se retira el acceso (suscripción cancelada, reembolso emitido, o revocación iniciada por el comerciante), la concesión se mueve a revoked. El campo revocation_reason registra el desencadenante.

​
Comportamiento de la Concesión por Evento

EventoComportamiento
payment.succeeded (pago único)Emitir una concesión por cada entitlement adjunto.
payment.succeeded (pago vinculado a suscripción)Sin operación. Las concesiones son impulsadas por el evento de suscripción a continuación.
subscription.activeEmitir concesiones para cualquier entitlement adjunto que aún no tenga uno. Reemitir cualquier concesión previamente revocada para la misma suscripción.
subscription.renewedSin operación. Las concesiones existentes persisten a través de renovaciones.
subscription.on_holdRevocar todas las concesiones entregadas y pendientes. revocation_reason: subscription_on_hold.
subscription.cancelledRevocar todas. revocation_reason: subscription_cancelled.
subscription.expiredRevocar todas. revocation_reason: subscription_expired.
subscription.plan_changedRevocar todas las concesiones actuales, luego emitir concesiones para los entitlements del nuevo plan. revocation_reason: plan_changed.
refund.succeeded (pago único)Revocar concesiones para ese pago. revocation_reason: refund.
Revocación manual de APIRevocar con revocation_reason: manual. Las revocaciones manuales no se reemiten automáticamente en la renovación de suscripción.
Clave de licencia desactivadaPara concesiones de clave de licencia, desactivar la clave subyacente revoca la concesión con revocation_reason: license_key_disabled. La concesión se reactiva automáticamente si se vuelve a habilitar la clave.
Desviación de plataforma detectadaSi la parte de la plataforma de una integración se desincroniza (un rol de Discord eliminado manualmente, la App de GitHub perdiendo acceso al repositorio, o un paso de conciliación detectando un objetivo faltante), la concesión es revocada con revocation_reason: platform_external. No se reemiten automáticamente en la renovación de suscripción hasta que se resuelva el problema subyacente de la plataforma.
Las concesiones dirigidas por suscripción son idempotentes por (entitlement, customer, subscription); las renovaciones y reactivaciones no crean concesiones duplicadas. Las concesiones únicas son idempotentes por (entitlement, customer, payment).

​
Crea tu primer entitlement

1

Open Entitlements

Ve a Entitlements en tu panel de control de Dodo Payments y haz clic en + para crear un nuevo entitlement.
2

Pick an integration

Elige el tipo de integración: Clave de Licencia, Archivos Digitales, Discord, GitHub, Telegram, Framer o Notion. Para integraciones de plataforma, conecta tu cuenta primero si aún no lo has hecho.
3

Configure delivery

Rellena los campos específicos de la integración. Por ejemplo, GitHub solicita un repositorio y un nivel de permiso; Discord solicita un servidor y un rol opcional; Clave de Licencia pide límites de activación y caducidad.
Formulario de nuevo Entitlement con selector de integración y campos de configuración
4

Save

Guarda el entitlement. Ahora puedes adjuntarlo a cualquier producto.

​
Adjuntar Entitlements a Productos

Abre un producto, expande Configuración Avanzada → Entitlements y Créditos, y selecciona los entitlements que deben entregarse cuando se compra el producto. Un solo producto puede entregar múltiples entitlements a la vez. Por ejemplo, un plan Pro puede incluir una clave de licencia, acceso a GitHub y un rol en Discord.
Panel de selección de entitlement de producto que muestra casillas de verificación para cada entitlement disponible

​
Experiencia del Cliente

​
Correo electrónico y portal del cliente

Los clientes reciben un correo electrónico de entrega después de la compra que contiene la clave de licencia, los enlaces de descarga, los enlaces de invitación de OAuth, o la invitación a la plataforma, lo que aplique a los entitlements del producto. Los mismos detalles permanecen disponibles indefinidamente desde el Portal del Cliente bajo su historial de pedidos.

​
Entrega basada en OAuth

El acceso de suscriptores a Discord, GitHub y Notion requiere que el cliente autorice a Dodo Payments para otorgarles acceso. Estas concesiones permanecen en estado pending hasta que el cliente completa el flujo OAuth usando el enlace de su correo electrónico o portal del cliente. Una vez que autorizan, la concesión pasa a delivered y el acceso a la plataforma se aprovisiona inmediatamente.

​
Revocación

Las concesiones revocadas son eliminadas a nivel de plataforma: el rol de Discord se elimina, el colaborador de GitHub se elimina, la clave de licencia se desactiva. Los clientes ven el cambio reflejado en el portal del cliente.
Para Archivos Digitales, la revocación elimina el acceso a las URLs presignadas en adelante, pero no invalida las copias que un cliente ya haya descargado. Planifica el contenido de manera acorde.

​
Gestionar Concesiones

Abre cualquier entitlement desde el panel para ver sus concesiones. El panel de detalles de la concesión muestra el total de concesiones, filtros de estado, información del cliente, fechas de entrega y una acción de revocación. También puedes gestionar las concesiones de forma programática: 
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
});

// List grants for an entitlement
const grants = await client.entitlements.grants.list('ent_abc123', {
  status: 'delivered',
});

// Revoke a single grant
await client.entitlements.grants.revoke('grant_xyz789', {
  path_id: 'ent_abc123',
});

​
Gestión de API

Create Entitlement

Crea un nuevo entitlement de cualquier tipo de integración.

List Entitlements

Lista entitlements con filtrado por tipo de integración.

Get Entitlement

Recupera un entitlement y su configuración resuelta.

Update Entitlement

Actualiza nombre, descripción o configuración de integración.

Delete Entitlement

Elimina un entitlement de manera blanda; las concesiones existentes no se ven afectadas.

Upload File

Sube un archivo a un entitlement de Archivos Digitales (hasta 100 MB).

List Grants

Lista todas las concesiones para un entitlement con filtros por estado y cliente.

Revoke Grant

Revoca manualmente una concesión única.

​
Webhooks

Dodo Payments dispara cuatro eventos webhook para el ciclo de vida de la concesión. Suscríbete a estos eventos para mantener tu aplicación sincronizada con lo que cada cliente puede acceder.
EventoOcurre cuando
entitlement_grant.createdSe crea una nueva concesión. Las concesiones de claves de licencia llegan delivered; todas las demás integraciones llegan pending y pasan a delivered una vez que la llamada a la plataforma tiene éxito (o, para integraciones basadas en OAuth, una vez que el cliente autoriza).
entitlement_grant.deliveredLa concesión pasa a entregado. El cliente ahora tiene acceso.
entitlement_grant.failedLa concesión no pudo ser entregada. Inspecciona error_code e error_message.
entitlement_grant.revokedEl acceso ha sido retirado. Inspecciona revocation_reason.

Entitlement Grant Webhook Payloads

Ve el esquema completo de payload, eventos de muestra, y referencia a revocation_reason.

​
Mejores Prácticas

  • Usa un entitlement por canal de entrega. No compartas un solo entitlement de Discord entre productos con diferentes intenciones de rol; crea uno por rol para una revocación limpia.
  • Prueba primero en modo de prueba. Crea el entitlement, adjúntalo a un producto de prueba, realiza una compra y observa la transición de la concesión a través de pending → delivered. Confirma que cancelar la suscripción de prueba revoca la concesión.
  • Escucha a entitlement_grant.delivered, no payment.succeeded. Un pago puede tener éxito antes de que se complete el cumplimiento (especialmente para flujos OAuth). Espera el evento entregado antes de desbloquear funciones dependientes en tus propios sistemas.
  • Trata a entitlement_grant.failed como accionable. Una concesión fallida significa que un cliente pagó pero no obtuvo acceso. Muéstralas a tu equipo de soporte o activa una reemisión.
  • Mapea revocation_reason a tus flujos de retención. Un revoke subscription_on_hold es recuperable (el cliente puede actualizar su tarjeta). Un revoke manual es intencional. Trátalos de manera diferente en las comunicaciones con el cliente.
Last modified on May 14, 2026