> ## 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.
# Introducción
> Entregue automáticamente claves de licencia, archivos descargables, feature flags y acceso a plataformas como Discord, GitHub, Telegram, Framer y Notion cuando los clientes paguen.
Las autorizaciones 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 feature flag que tu aplicación verifica, un rol en Discord, un repositorio de GitHub, una plantilla de Notion, un enlace de remix de Framer, una invitación al chat de Telegram o un paquete de archivos descargables. Dodo Payments emite, rastrea y revoca ese acceso automáticamente a medida que el ciclo de vida del pago cambia.
## ¿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](/features/credit-based-billing) 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.
Genera claves de licencia únicas con límites de activación y expiración. Ideal para software, plugins y CLIs.
Entrega archivos descargables (libros electrónicos, plantillas, medios) con URLs de descarga presignadas e instrucciones opcionales.
Restringe funciones en tu propia aplicación después de una compra. Entregado al instante, verificado a través de API, revocado al cancelar.
Otorga un rol a un cliente en tu servidor de Discord cuando compran. Revoca automáticamente al cancelar.
Agrega a los clientes como colaboradores en un repositorio privado al nivel de permisos que elijas.
Agrega a los clientes a un chat o canal privado de Telegram después de la compra.
Desbloquea un enlace de remix de plantilla de Framer para los clientes que pagan.
Duplica una plantilla de Notion en el espacio de trabajo del cliente al comprar.
***
## Cómo funcionan las autorizaciones
Las autorizaciones son impulsadas por los mismos eventos de pago y suscripción que ya recibes como webhooks. No necesitas llamar a la API de autorización para las compras. Dodo Payments crea y revoca autorizaciones automáticamente basándose en el ciclo de vida de pago subyacente.
### Ciclo de vida de la autorización
Se crea una autorización cuando se completa un pago o una suscripción se activa. Las claves de licencia y los feature flags pasan directamente a `delivered`. Toda otra integración comienza 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 plataforma (Telegram, Framer, Archivos Digitales) están en `pending` brevemente mientras se provisiona la entrega, luego transicionan a `delivered`.
Una vez completada la entrega (clave de licencia generada, rol asignado, acceso al repositorio otorgado, enlaces de archivos resueltos, OAuth completado), la autorización pasa a `delivered` y se establece `delivered_at`.
Si la llamada a la integración devuelve un error no reintentable (token de OAuth revocado, permiso denegado, archivo que ya no existe), la autorización pasa a `failed`. Los campos `error_code` e `error_message` capturan la razón.
Cuando se retira el acceso (suscripción cancelada, reembolso emitido o revocación iniciada por el comerciante), la autorización pasa a `revoked`. El campo `revocation_reason` registra el desencadenante.
### Comportamiento de la autorización por evento
| Evento | Comportamiento |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment.succeeded` (pago único) | Emitir una autorización por cada derecho adjunto. |
| `payment.succeeded` (pago vinculado a suscripción) | Sin acción. Las autorizaciones son impulsadas por el evento de suscripción a continuación. |
| `subscription.active` | Emitir autorizaciones para cualquier derecho adjunto que aún no tenga uno. Reevaluar cualquier autorización previamente revocada para la misma suscripción. |
| `subscription.renewed` | Sin acción. Las autorizaciones existentes persisten a través de renovaciones. |
| `subscription.on_hold` | Revocar todas las autorizaciones entregadas y pendientes. `revocation_reason: subscription_on_hold`. |
| `subscription.cancelled` | Revocar todo. `revocation_reason: subscription_cancelled`. |
| `subscription.expired` | Revocar todo. `revocation_reason: subscription_expired`. |
| `subscription.plan_changed` | Revocar todas las autorizaciones actuales, luego emitir autorizaciones para los derechos del nuevo plan. `revocation_reason: plan_changed`. |
| `refund.succeeded` (pago único) | Revocar autorizaciones para ese pago. `revocation_reason: refund`. |
| Revocación manual de API | Revocar con `revocation_reason: manual`. Las revocaciones manuales no se reanudan automáticamente en la renovación de la suscripción. |
| Licencia deshabilitada | Para autorizaciones de clave de licencia, deshabilitar la clave subyacente revoca la autorización con `revocation_reason: license_key_disabled`. La autorización se reactiva automáticamente si la clave se vuelve a habilitar. |
| Desajuste de plataforma detectado | Si el lado de la integración de la plataforma se desincroniza (un rol de Discord eliminado manualmente, el App de GitHub perdiendo acceso al repositorio o un pase de reconciliación detectando un objetivo perdido), la autorización se revoca con `revocation_reason: platform_external`. No se reanuda automáticamente en la renovación de la suscripción hasta que se resuelva el problema subyacente de la plataforma. |
Las autorizaciones impulsadas por suscripción son idempotentes por `(entitlement, customer, subscription)`; las renovaciones y reactivaciones no crean autorizaciones duplicadas. Las autorizaciones de una sola vez son idempotentes por `(entitlement, customer, payment)`.
***
## Crea tu primer derecho
Dirígete a **Entitlements** en tu panel de Dodo Payments y haz clic en **+** para crear un nuevo derecho.
Elige el tipo de integración: Clave de Licencia, Archivos Digitales, Feature Flag, Discord, GitHub, Telegram, Framer o Notion. Para integraciones de plataforma, conecta tu cuenta primero si aún no lo has hecho.
Completa los campos específicos de la integración. Por ejemplo, GitHub pide un repositorio y un nivel de permiso; Discord pide un servidor y un rol opcional; Clave de Licencia pide límites de activación y caducidad.
Guarda el derecho. Ahora puedes adjuntarlo a cualquier producto.
## Adjunta derechos a productos
Abre un producto, expande **Configuración Avanzada → Derechos y Créditos**, y selecciona los derechos que se deben entregar cuando se compra el producto. Un solo producto puede entregar múltiples derechos a la vez. Por ejemplo, un plan Pro puede incluir una clave de licencia, acceso a GitHub y un rol de Discord.
***
## Experiencia del Cliente
### Correo electrónico y portal del cliente
Los clientes reciben un correo de entrega después de la compra que contiene la clave de licencia, enlaces de descarga, enlaces de invitación OAuth o invitación de plataforma, lo que aplique a los derechos en el producto. Los mismos detalles permanecen disponibles indefinidamente en el [Portal del Cliente](/features/customer-portal) bajo su historial de pedidos.
### Entrega basada en OAuth
El acceso del suscriptor de Discord, GitHub y Notion requiere que el cliente autorice a Dodo Payments para otorgarle acceso. Estas autorizaciones permanecen en estado `pending` hasta que el cliente complete el flujo OAuth usando el enlace de su correo electrónico o portal de cliente. Una vez que autorizan, la autorización pasa a `delivered` y el acceso a la plataforma se provisiona inmediatamente.
### Revocación
Las autorizaciones revocadas se eliminan a nivel de plataforma: se elimina el rol de Discord, se elimina el colaborador de GitHub, se desactiva la clave de licencia. Los clientes ven el cambio reflejado en el portal del cliente.
Para Archivos Digitales, la revocación elimina el acceso a las URL pre-firmadas en adelante pero no invalida las copias que un cliente ya ha descargado. Planifica el contenido del plan en consecuencia.
***
## Gestiona Autorizaciones
Abre cualquier derecho desde el panel para ver sus autorizaciones. El panel de detalle de autorización muestra autorizaciones totales, filtros de estado, información del cliente, fechas de entrega y una acción de revocación.
También puedes gestionar autorizaciones de forma programática:
```typescript TypeScript theme={null} theme={null}
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', {
id: 'ent_abc123',
});
```
```python Python theme={null} theme={null}
client.entitlements.grants.list(
"ent_abc123",
status="Delivered",
)
client.entitlements.grants.revoke(
"grant_xyz789",
id="ent_abc123",
)
```
```go Go theme={null} theme={null}
grants, _ := client.Entitlements.Grants.List(
ctx, "ent_abc123",
dodopayments.EntitlementGrantListParams{Status: dodopayments.F("delivered")},
)
_, _ = client.Entitlements.Grants.Revoke(ctx, "grant_xyz789", "ent_abc123")
```
***
## Gestión de API
Crea un nuevo derecho de cualquier tipo de integración.
Enumera derechos con filtrado por tipo de integración.
Recupera un derecho y su configuración resuelta.
Actualiza nombre, descripción o configuración de integración.
Eliminar un derecho de forma temporal; las autorizaciones existentes no se ven afectadas.
Sube un archivo a un derecho de Archivos Digitales (hasta 500 MiB).
Lista todas las autorizaciones para un derecho con filtros de estado y cliente.
Revoca manualmente una sola autorización.
***
## Webhooks
Dodo Payments dispara cuatro eventos de webhook para el ciclo de vida de la autorización. Suscríbete a estos eventos para mantener tu aplicación sincronizada con lo que cada cliente puede acceder.
| Evento | Se activa cuando |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entitlement_grant.created` | Se crea una nueva autorización. Las autorizaciones de clave de licencia llegan `delivered`; cada otra integración llega `pending` y transiciona a `delivered` una vez que la llamada a la plataforma tiene éxito (o, para las integraciones basadas en OAuth, una vez que el cliente autoriza). |
| `entitlement_grant.delivered` | La autorización transiciona a entregada. El cliente ahora tiene acceso. |
| `entitlement_grant.failed` | No se pudo entregar la autorización. Inspecciona `error_code` e `error_message`. |
| `entitlement_grant.revoked` | Se ha retirado el acceso. Inspecciona `revocation_reason`. |
Visualiza el esquema completo de carga útil, eventos de muestra y referencia `revocation_reason`.
***
## Mejores Prácticas
* **Usa un derecho por canal de entrega.** No compartas un solo derecho de Discord entre productos con intenciones de rol diferentes; crea uno por rol para una revocación limpia.
* **Prueba primero en modo de prueba.** Crea el derecho, adjúntalo a un producto de prueba, realiza una compra y observa la transición de la autorización a través de `pending → delivered`. Confirma que cancelar la suscripción de prueba revoca la autorización.
* **Escucha `entitlement_grant.delivered`, no `payment.succeeded`.** Un pago puede tener éxito antes de que se complete el cumplimiento (especialmente para flujos de OAuth). Espera el evento entregado antes de desbloquear funciones dependientes en tus propios sistemas.
* **Trata `entitlement_grant.failed` como accionable.** Una autorización fallida significa que un cliente pagó pero no obtuvo acceso. Muestra estos a tu equipo de soporte o activa una nueva concesión.
* **Mapea `revocation_reason` a tus flujos de retención.** Una revocación `subscription_on_hold` es recuperable (el cliente puede actualizar su tarjeta). Una revocación `manual` es intencional. Trátalos de manera diferente en las comunicaciones con el cliente.