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 claves de licencia son el tipo de derecho de Clave de Licencia. Crea un derecho de Clave de Licencia una vez con el límite de activación, vencimiento e instrucciones que desees, asígnalo a cualquier producto y Dodo Payments genera y entrega una clave por compra o asiento de suscripción, automáticamente.

​
¿Qué son las Claves de Licencia?

Las claves de licencia son tokens únicos que autorizan el acceso a tu producto. Son ideales para:
  • Licenciamiento de software: Aplicaciones de escritorio, plugins y CLIs
  • Controles por asiento: Limitar activaciones por usuario o dispositivo
  • Bienes digitales: Restringir descargas, actualizaciones o características premium
Dentro de Dodo Payments, las claves de licencia se gestionan a través del sistema de Derechos, lo que significa que el ciclo de vida de cada clave (creación, vencimiento, revocación, reactivación) está impulsado por los mismos eventos de pago y suscripción que tus otros entregables.

​
Crear un Derecho de Clave de Licencia

1

Open Entitlements

Ve a Derechos en tu panel de Dodo Payments y haz clic en + para crear un nuevo derecho.
2

Choose License Key

Selecciona Clave de Licencia como la integración. Configura cómo se comporta cada clave emitida:
  • Límite de Activaciones: Activaciones concurrentes máximas por clave (por ejemplo, 1 para usuario único, 5 para licencias de equipo, dejar en blanco para ilimitado).
  • Duración: Cuánto tiempo permanece válida la clave después de la emisión (por ejemplo, 30 días, 1 año). Para las claves emitidas por suscripción, dejar en blanco; las claves permanecen válidas mientras la suscripción esté activa.
  • Instrucciones de Activación: Instrucciones para el cliente enviadas por correo electrónico con la clave. Ejemplos: Paste the key in Settings → License o Run: mycli activate <key>.
Formulario de derecho de Clave de Licencia con límite de activación, duración e instrucciones
3

Save the entitlement

Guardar. El derecho ahora está disponible para adjuntar a cualquier producto.

​
Adjuntar a Productos

Abre un producto, expande Configuración Avanzada → Derechos y Créditos, y selecciona tu derecho de Clave de Licencia. Un solo producto puede entregar una clave de licencia junto con otros derechos (acceso a Discord, descargas de archivos, acceso a repositorio de GitHub, etc.) en la misma compra.
Panel de derechos de producto con Clave de Licencia seleccionada

​
Cómo se Emiten las Claves

La emisión de claves sigue el ciclo de vida de concesión estándar:
EventoComportamiento
payment.succeeded (único)Genera una clave por cada quantity comprado. La caducidad de la clave respeta la duración del derecho.
subscription.activeGenera una clave por cada quantity de suscripción (asiento). La clave no tiene caducidad; la validez está ligada al estado de la suscripción.
subscription.renewedSin operación. Las claves existentes persisten.
subscription.on_holdDesactiva las claves. Se reactivan cuando la suscripción sale de espera.
subscription.cancelled / expiredDesactiva las claves permanentemente.
subscription.plan_changedDesactiva las claves antiguas; emite nuevas para el nuevo plan.
refund.succeeded (único)Desactiva las claves.
Revocación manual vía API/panelDesactiva las claves con revocation_reason: manual. No se reactivan automáticamente en la renovación de la suscripción.
Clave de licencia desactivada directamenteRevoca la concesión con revocation_reason: license_key_disabled. Rehabilitar la clave reactiva la concesión automáticamente.

​
Comportamiento de Cantidad

  • Productos de suscripción emiten una clave por asiento (subscriptions.quantity).
  • Productos de una sola vez emiten una clave por línea de artículo en el carrito (product_cart.quantity).
  • Concesiones manuales de API emiten exactamente una clave.

​
Activación, Validación, Desactivación

Los endpoints de API para activación/validación/desactivación son públicos y no requieren una clave API. Úsalos directamente desde software de escritorio, CLIs o clientes basados en navegador para verificar claves en tiempo de ejecución.
Endpoints Públicos: Los endpoints para activar, desactivar y validar licencias son públicos y no requieren una clave API. Llámalos directamente desde tus aplicaciones cliente sin exponer tus credenciales API.

​
Activar una licencia

import DodoPayments from 'dodopayments';

// No API key needed for public license endpoints
const client = new DodoPayments();

const response = await client.licenses.activate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
  name: 'Device Name',
});

console.log(response.id);

​
Validar una licencia

const response = await client.licenses.validate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
});

console.log(response.valid);

​
Desactivar una instancia de activación

await client.licenses.deactivate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
  license_key_instance_id: 'instance_abc123',
});

​
Gestionar Claves

Abre el derecho de Clave de Licencia desde tu panel para ver cada concesión (una fila por clave de cliente) con fecha de entrega, conteo de activaciones y una acción de revocación. Cada detalle de concesión muestra la clave de licencia subyacente, vencimiento, activaciones usadas y el límite de activaciones. También puedes listar concesiones de forma programática: 
const grants = await client.entitlements.grants.list('ent_license_key_id', {
  status: 'delivered',
});

for (const grant of grants.items) {
  console.log(grant.license_key.key, grant.license_key.activations_used);
}

​
Importar Claves de Licencia Existentes vía API

¿Ya tienes claves de licencia en otro sistema? Usa la API de Crear Clave de Licencia para importarlas a Dodo Payments. Esto te permite migrar claves existentes sin interrumpir a tus clientes, quienes continúan activando, validando y desactivando con las mismas cadenas de clave sin reemisión.
Las claves de licencia creadas o actualizadas a través de la API no disparan notificaciones por correo electrónico a los clientes. Si necesitas notificar a los clientes sobre una clave importada, gestiona eso por separado en tu aplicación.
const licenseKey = await client.licenseKeys.create({
  customer_id: 'cus_abc123',
  product_id: 'prod_456',
  key: 'YOUR-EXISTING-LICENSE-KEY',
  activations_limit: 5,
  expires_at: '2026-12-31T23:59:59Z',
});

​
Cómo difieren las claves importadas de las generadas automáticamente

CampoClave generada automáticamenteClave importada
source"auto""import"
payment_idConfigurado al pago de origennull (sin transacción de Dodo Payments)
subscription_idConfigurado si la clave fue emitida vía suscripciónnull a menos que esté vinculado explícitamente
Notificación por correo electrónico al clienteEnviado al emitirseNo enviado, gestionar por separado
Usa el campo source en las respuestas de GET /license_keys para distinguir el inventario migrado de las claves emitidas orgánicamente al conciliar o auditar.
¿Migrando de Polar.sh o Lemon Squeezy? El dodo-migrate CLI automatiza importaciones masivas de productos, clientes, descuentos y claves de licencia en un solo comando y asigna automáticamente IDs externos a IDs de Dodo.

​
Claves de Licencia en URL de Retorno

Cuando un cliente completa una compra de un producto con un derecho de Clave de Licencia, la clave generada se añade automáticamente a tu return_url como un parámetro de consulta. Esto te permite mostrar la clave inmediatamente en tu página de éxito sin hacer una llamada API adicional. 
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com
Si la compra genera múltiples claves (cantidad > 1), se separan por comas: 
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001,LK-002&email=customer%40example.com
Para suscripciones, se usa subscription_id en lugar de payment_id: 
https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001&email=customer%40example.com
Analiza el parámetro license_key en tu página de retorno para mostrar la clave inmediatamente, mejorando la experiencia post-compra.

​
Gestión de API

Activación, desactivación y validación son públicas; no se requiere clave API.

Activate License

Crea o registra una instancia de activación para una clave de licencia.

Deactivate License

Revoca una activación previa para liberar capacidad.

Validate License

Verifica autenticidad, estado y restricciones antes de otorgar acceso.
Crea, lista, recupera y actualiza registros individuales de claves de licencia. Úsalos para importar claves existentes u obtener detalles de uso.

Create License Key

Crea una nueva clave de licencia o importa una existente.

List License Keys

Navega por todas las claves con detalles de estado y uso.

Get License Key

Recupera una clave específica y sus metadatos.

Update License Key

Modifica caducidad, límites de activación o habilita/deshabilita una clave.
Gestiona el propio derecho de Clave de Licencia: su límite de activación, duración e instrucciones.

Create Entitlement

Crea un derecho de Clave de Licencia.

Update Entitlement

Actualiza la configuración del derecho.

List Grants

Lista las claves emitidas para un derecho.

Revoke Grant

Revoca manualmente la clave de un cliente.

​
Webhooks

La entrega y revocación de claves de licencia activan los cuatro eventos webhook entitlement_grant.*. La carga útil de concesión incluye un objeto license_key con la clave, caducidad, activaciones utilizadas y límite. Los eventos heredados license_key.* (license_key.created) continúan activándose para el ciclo de vida del registro subyacente de la clave de licencia; vea la página de carga útil de webhook de Clave de Licencia.
Para nuevas integraciones, escuche entitlement_grant.delivered en lugar de license_key.created. El evento de derecho te dice que la entrega está completa en todas las integraciones en el producto, no solo en la clave de licencia.

​
Claves de Licencia Heredadas

Los productos creados con la bandera antigua license_key_enabled han sido automáticamente migrados a un derecho de Clave de Licencia. La migración es transparente: las claves de los clientes existentes continúan funcionando sin cambios, los endpoints públicos /licenses/activate, /licenses/validate, /licenses/deactivate siguen funcionando, y los endpoints de la API /license_keys/* continúan leyendo y escribiendo en el mismo almacén de claves.La sección de panel de Claves de Licencia independiente permanece disponible como una lista plana de cada clave emitida, útil para auditoría y búsqueda. La nueva configuración (cambiando límites de activación, duraciones o instrucciones) debe hacerse editando el derecho de Clave de Licencia migrado en Derechos.

​
Mejores Prácticas

  • Mantén claros los límites de activación: Elige valores predeterminados sensatos (1 para aplicaciones de un solo usuario, 3-5 para licencias de equipo) y documéntalos.
  • Proporciona instrucciones de activación precisas: Los clientes las copian de su correo electrónico, así que las rutas y comandos exactos ahorran tickets de soporte.
  • Valida las claves en el servidor: Para productos conectados a la red, valida a través de /licenses/validate en lugar de almacenar en caché la activación localmente.
  • Usa webhooks para revocación: Escucha entitlement_grant.revoked para desactivar características en la aplicación inmediatamente cuando un cliente cancela o solicita un reembolso.
  • Prueba con suscripciones y adquisiciones únicas: El comportamiento de las claves de licencia difiere sutilmente entre ambos, así que prueba ambos antes de lanzar.
Last modified on May 14, 2026