API de Licencias

La API de Licencias te permite crear políticas de licencia, emitir claves, validarlas en tiempo de ejecución, gestionar puestos y dispositivos, y automatizar la emisión de claves desde webhooks de pago. Soporta validación online, respaldo offline con JWT y modos híbridos.

Dos audiencias, dos niveles de autenticación:

Audiencia	Autenticación	Endpoints
Tu app / SDK (tiempo de ejecución)	No requiere Bearer token	`/validate`, `/activate`, `/deactivate`, `/usage`, `/revocation-list`
Admin / Consola (gestión)	Bearer token + permiso	Todo lo demás

Todos los endpoints requieren el header x-tenant.

Políticas

Las políticas definen qué otorga una licencia — funcionalidades, puestos, dispositivos, expiración, formato de clave y modo de validación.

GET/api/licensing/policiesRequires: manage:license-policies

Lista todas las políticas del tenant actual. Soporta paginación y búsqueda.

Parámetros de consulta

Parámetro	Tipo	Descripción
`page`	`number`	Número de página (por defecto: 1)
`limit`	`number`	Elementos por página (por defecto: 20)
`search`	`string`	Filtrar por nombre o slug

Respuesta exitosa


{
  "success": true,
  "data": [
    {
      "id": "pol_abc123",
      "name": "Pro Plan",
      "slug": "pro-plan",
      "validationMode": "HYBRID",
      "isActive": true,
      "offlineGraceDays": 7,
      "revocationTtlMin": 60,
      "dimensions": {
        "seats": { "enabled": true, "defaultMax": 5 },
        "devices": { "enabled": true, "defaultMax": 3 },
        "expiry": { "enabled": true, "defaultDays": 365 },
        "features": { "enabled": true, "available": ["analytics", "export", "api-access"] },
        "keyFormat": {
          "prefix": "VIG",
          "segments": 4,
          "segmentLength": 4,
          "separator": "-",
          "charset": "BASE32"
        }
      },
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 3, "pages": 1 }
}

POST/api/licensing/policiesRequires: manage:license-policies

Crear una nueva política de licencia.

Cuerpo de la solicitud


{
  "name": "Pro Plan",
  "slug": "pro-plan",
  "validationMode": "HYBRID",
  "dimensions": {
    "seats": { "enabled": true, "defaultMax": 5 },
    "devices": { "enabled": true, "defaultMax": 3 },
    "expiry": { "enabled": true, "defaultDays": 365 },
    "features": { "enabled": true, "available": ["analytics", "export"] },
    "keyFormat": {
      "prefix": "VIG",
      "segments": 4,
      "segmentLength": 4,
      "separator": "-",
      "charset": "BASE32"
    }
  }
}

Campo	Tipo	Requerido	Descripción
`name`	`string`	Sí	Nombre para mostrar
`slug`	`string`	Sí	Slug único (ej. `pro-plan`)
`validationMode`	`ONLINE \| HYBRID \| OFFLINE`	No	Por defecto: `HYBRID`
`dimensions`	`object`	No	Configuración de puestos, dispositivos, funcionalidades, expiración y formato de clave
`offlineGraceDays`	`number`	No	Días que una clave permanece válida offline (por defecto: 7)
`revocationTtlMin`	`number`	No	Minutos antes de que la revocación se propague (por defecto: 60)

GET/api/licensing/policies/:idRequires: manage:license-policies

Obtener una política individual por ID.

PATCH/api/licensing/policies/:idRequires: manage:license-policies

Actualizar una política. Solo se modifican los campos proporcionados.

DELETE/api/licensing/policies/:idRequires: manage:license-policies

Eliminar una política. Falla si aún hay claves emitidas bajo ella.

Claves

Las claves se emiten contra una política y se otorgan a un licenciatario (usuario, organización o dispositivo).

GET/api/licensing/keysRequires: manage:license-keys

Listar todas las claves. Filtrable por estado y política.

Parámetros de consulta

Parámetro	Tipo	Descripción
`page`	`number`	Número de página
`limit`	`number`	Elementos por página
`policyId`	`string`	Filtrar por política
`status`	`ACTIVE \| SUSPENDED \| REVOKED \| EXPIRED`	Filtrar por estado

POST/api/licensing/keysRequires: manage:license-keys

Emitir una nueva clave de licencia.

Cuerpo de la solicitud


{
  "policyId": "pol_abc123",
  "licenseeType": "USER",
  "licenseeId": "user_xyz789",
  "notes": "Issued via Stripe checkout"
}

La respuesta incluye el objeto completo de la clave con key (la cadena de licencia) y jwtToken (para validación offline).

GET/api/licensing/keys/:idRequires: manage:license-keys

Obtener una clave individual por ID, incluyendo la política relacionada, puestos y dispositivos.

POST/api/licensing/keys/:id/suspendRequires: manage:license-keys

Suspender una clave. Puede ser reactivada posteriormente.

POST/api/licensing/keys/:id/revokeRequires: manage:license-keys

Revocar permanentemente una clave.

POST/api/licensing/keys/:id/reissueRequires: manage:license-keys

Reemitir una clave con derechos actualizados. La clave anterior se revoca y se genera una nueva.

Cuerpo opcional


{
  "features": ["analytics", "export", "api-access"],
  "seatMax": 10,
  "deviceMax": 5,
  "expiresAt": "2027-03-15T00:00:00Z"
}

Puestos

GET/api/licensing/keys/:id/seatsRequires: manage:license-keys

Listar todos los puestos (usuarios asignados) de una clave.

POST/api/licensing/keys/:id/seatsRequires: manage:license-keys

Asignar un puesto a un usuario. Falla si se alcanza el límite de puestos.


{ "userId": "user_abc" }

DELETE/api/licensing/keys/:id/seats/:userIdRequires: manage:license-keys

Liberar un puesto de un usuario.

Dispositivos

GET/api/licensing/keys/:id/devicesRequires: manage:license-keys

Listar todos los dispositivos activados de una clave.

DELETE/api/licensing/keys/:id/devices/:deviceIdRequires: manage:license-keys

Eliminar un dispositivo de una clave.

Validación (Pública)

Estos endpoints son llamados por tu aplicación en tiempo de ejecución. No se requiere Bearer token.

POST/api/licensing/validate

Validar una clave de licencia online. Devuelve validez, funcionalidades, conteo de puestos/dispositivos y expiración.

Cuerpo de la solicitud


{ "key": "VIG-A8BC-D3EF-G4HJ-K5LM" }

Respuesta exitosa


{
  "valid": true,
  "features": ["analytics", "export"],
  "seats": { "used": 2, "max": 5 },
  "devices": { "used": 1, "max": 3 },
  "expiresAt": "2027-01-15T00:00:00Z"
}

Respuesta de clave inválida


{
  "valid": false,
  "reason": "REVOKED"
}

Valores posibles de reason: INVALID, EXPIRED, REVOKED, SUSPENDED, SEAT_LIMIT, DEVICE_LIMIT.

Activación de Dispositivos (Pública)

POST/api/licensing/activate

Registrar un dispositivo contra una clave de licencia. Usa esto en el primer inicio de una app de escritorio/móvil.


{
  "key": "VIG-A8BC-D3EF-G4HJ-K5LM",
  "fingerprint": "a1b2c3d4e5f6",
  "name": "John's MacBook Pro"
}

Devuelve 200 en caso de éxito. Lanza 409 si se alcanza el límite de dispositivos.

POST/api/licensing/deactivate

Eliminar un dispositivo de una clave. Úsalo cuando el usuario cierra sesión o desinstala la app.


{
  "key": "VIG-A8BC-D3EF-G4HJ-K5LM",
  "fingerprint": "a1b2c3d4e5f6"
}

Seguimiento de Uso (Público)

POST/api/licensing/usage

Registrar una métrica de uso contra una clave. Útil para licencias medidas/basadas en consumo.


{
  "key": "VIG-A8BC-D3EF-G4HJ-K5LM",
  "metric": "api_calls",
  "amount": 1
}

GET/api/licensing/usage/:key

Obtener los datos de uso actuales de una clave en todas las métricas.

Lista de Revocación (Pública)

GET/api/licensing/revocation-list

Devuelve un JWT firmado que contiene todos los JTIs de claves revocadas. Usado por el SDK para verificación de revocación offline.

La respuesta es application/jwt con Cache-Control: public, max-age=3600. El SDK obtiene esto automáticamente.

Reglas de Automatización

Las reglas de automatización conectan eventos de pago (Stripe, PayPal) con acciones de licencia (emitir, activar, suspender, revocar).

GET/api/licensing/automationRequires: manage:license-policies

Listar todas las reglas de automatización.

POST/api/licensing/automationRequires: manage:license-policies

Crear una nueva regla de automatización.


{
  "name": "Stripe checkout → issue key",
  "provider": "stripe",
  "triggerEvent": "checkout.session.completed",
  "action": "issue_key",
  "policyId": "pol_abc123",
  "isActive": true
}

Proveedor	Eventos de activación
`stripe`	`checkout.session.completed`, `invoice.paid`, `payment_intent.succeeded`
`paypal`	`PAYMENT.CAPTURE.COMPLETED`
`manual`	`manual_trigger`

Acción	Descripción
`issue_key`	Emitir una nueva clave bajo la política vinculada
`activate_key`	Activar una clave existente
`suspend_key`	Suspender una clave
`revoke_key`	Revocar una clave

GET/api/licensing/automation/:idRequires: manage:license-policies

Obtener una regla de automatización individual.

PATCH/api/licensing/automation/:idRequires: manage:license-policies

Actualizar una regla de automatización.

DELETE/api/licensing/automation/:idRequires: manage:license-policies

Eliminar una regla de automatización.

Webhooks

Estos endpoints reciben eventos de proveedores de pago. Se verifican mediante firma y no requieren Bearer token.

POST/api/licensing/webhooks/stripe

Recibe eventos de webhook de Stripe. Verificado mediante el header stripe-signature. Configura STRIPE_LICENSING_WEBHOOK_SECRET en tu entorno.

POST/api/licensing/webhooks/paypal

Recibe eventos de webhook de PayPal. Verificado mediante HMAC-SHA256. Configura PAYPAL_LICENSING_WEBHOOK_SECRET y PAYPAL_LICENSING_WEBHOOK_ID en tu entorno.

Estadísticas

GET/api/licensing/statsRequires: view:license-stats

Devuelve estadísticas agregadas de licencias.


{
  "success": true,
  "data": {
    "totalPolicies": 3,
    "totalKeys": 142,
    "activeKeys": 98,
    "revokedKeys": 12,
    "suspendedKeys": 5,
    "expiredKeys": 27,
    "policyDistribution": [
      { "policyId": "pol_abc", "policyName": "Pro Plan", "count": 80 }
    ],
    "recentKeys": []
  }
}