Actualizar una licencia in situ, de prueba a pago
Cuando un cliente convierte una prueba en pago o pasa de Standard a Pro, la cadena de la clave que ya activó no debería cambiar. Así se actualiza una licencia en el servidor con Keyright — quitando la marca de prueba, extendiendo la expiración, añadiendo entitlements — para que la app desplegada con el SDK adopte la nueva concesión en su próximo ValidateAsync, sin fricción de reactivación, además de cómo ajustar los tiempos de revalidación, mantener idempotente la llamada de actualización y auditar cada cambio de entitlements.
Un cliente termina su prueba y paga. O un cliente Standard sube a Pro. O compra un complemento a mitad del periodo. En cada uno de esos momentos el instinto es generar una clave de licencia nueva y enviarla por correo — y en cada uno de ellos es la decisión equivocada. La clave que el cliente ya activó es una concesión firmada de entitlements; convertir una prueba en pago, o Standard en Pro, es un cambio en lo que dice esa concesión, no un motivo para reemplazarla. Actualiza la licencia en el sitio y la cadena de la clave instalada del cliente nunca cambia: ninguna clave nueva que entregar, ningún copiar y pegar, ninguna reactivación, ningún ticket de “nunca recibí mi clave”.
Esta es una guía para hacer exactamente eso con un despliegue autoalojado de Keyright. Cambiaremos una licencia en el servidor, veremos cómo la app desplegada con el SDK adopta los nuevos entitlements en su próxima validación, y luego trataremos las partes que lo hacen instantáneo y correcto: propagación de la caché, idempotencia, bajadas de nivel y la traza de auditoría.
La app desplegada nunca cambia
Empecemos por el lado de la app, porque es la parte que no debe moverse. Una app .NET incrusta el SDK de Keyright, lo inicializa una vez y protege las funciones con entitlements:
KeyrightClient.Initialize(new KeyrightOptions
{
Product = "acme-studio",
PublicKeyBase64 = "MCowBQYDK2VwAyEA...", // la clave de verificación de tu despliegue
ServiceUrl = "https://license.acme.example",
});
var result = await client.ValidateAsync();
if (!result.IsValid)
{
// Falla en modo cerrado: sin licencia válida → sin funciones de pago.
EnterRestrictedMode(result);
return;
}
// Protege una función de pago con un entitlement, no con un nombre de nivel.
exportButton.Enabled = client.HasEntitlement("pro.export");
Fíjate en lo que la app no hace: no comprueba una cadena de nivel, no compara fechas, no trata “trial” como caso especial. Hace una pregunta por función — HasEntitlement("pro.export") — y falla en modo cerrado cuando la licencia es inválida. Esa única disciplina es lo que hace posible una actualización en el sitio, porque lo único que tiene que hacer una actualización es cambiar qué entitlements lleva la licencia. El código de la app ya está escrito para reaccionar.
Cambia la licencia, no la clave
En el lado del servidor, una actualización es un parche al registro de licencia existente. Keyright lo expone a través de la API de administración (y la misma acción está disponible como un botón en el panel). La licencia se direcciona por su id — no por la cadena de la clave, que permanece privada para el cliente:
PATCH /v1/admin/licenses/lic_7f3a9c2e HTTP/1.1
Host: license.acme.example
Authorization: Bearer {admin_token}
Idempotency-Key: order-558120
Content-Type: application/json
{
"tier": "pro",
"entitlements": ["core.use", "pro.export", "pro.batch"],
"expiresAt": "2027-11-14T00:00:00Z",
"trial": false
}
Esa sola llamada realiza toda la conversión de prueba a pago: quita la marca trial, empuja la expiración un año más allá e intercambia el conjunto de entitlements de la prueba por el de pago. El id de la licencia no cambia, así que la cadena de la clave que el cliente escribió en la app hace una semana sigue siendo válida y sigue siendo suya. Nada de su máquina, su activación o sus datos se mueve. La próxima vez que su app valide, el servicio de emisión firma una concesión nueva que lleva pro.export y pro.batch, y HasEntitlement("pro.export") devuelve true.
Una subida de nivel (Standard → Pro) tiene la forma idéntica — envías el nivel Pro y su conjunto mayor de entitlements. Un complemento a mitad de periodo es aún más pequeño: deja tier y expiresAt como están y envía la lista de entitlements con la capacidad extra añadida. Como la app protege con cadenas de entitlement individuales, añadir pro.batch a la lista desbloquea exactamente esa función y no toca nada más.
Cómo lo adopta la app
La actualización está activa en el servidor en el momento en que el PATCH se confirma. Cuándo la ve la app depende del tiempo de validación.
Entre validaciones el SDK sirve una concesión en caché para que la app siga funcionando sin conexión y no toque la red en cada comprobación de función. Si el cliente pagó durante esa ventana en caché, la app sigue mostrando la prueba hasta que la caché expire y revalide. Eso no es un fallo — es la tolerancia sin conexión que hace usable el SDK — pero es lo que hace que una actualización parezca rota.
Tres palancas cierran el hueco:
- Acorta el intervalo de revalidación en productos donde las actualizaciones instantáneas importan. Un
RevalidationIntervalmás corto significa que el siguienteValidateAsyncen línea ocurre antes, así que los nuevos entitlements llegan antes. El compromiso es más contactos con el servidor; ajústalo a la experiencia que quieres. - Fuerza una validación ante una acción del usuario. Dale a la app un elemento de menú “Actualizar licencia”, o dispara
ValidateAsynccuando el usuario abra la pantalla de éxito de la actualización tras volver del pago. Esto convierte el hueco de propagación en un solo viaje de ida y vuelta. - Revalida al reanudar. Llamar a
ValidateAsyncal arrancar la app o al enfocar la ventana significa que un cliente que pagó y reabrió la app recibe la actualización de inmediato, que es el camino de conversión más común.
// Llamado desde una acción "Actualizar licencia" tras volver el cliente del pago.
async Task RefreshAfterPurchaseAsync()
{
var result = await client.ValidateAsync(force: true); // omite la caché
if (result.IsValid && client.HasEntitlement("pro.export"))
UnlockProFeatures(result.LicenseInfo); // en vivo, misma clave
}
result.LicenseInfo lleva el nivel, el conjunto de entitlements y la expiración actualizados, así que la interfaz puede reetiquetar el plan y retirar el banner de “la prueba termina en N días” en la misma pasada.
Haz idempotente la actualización
Las actualizaciones suelen estar impulsadas por un webhook de facturación, y los webhooks se entregan al menos una vez — el mismo evento order.paid puede llegar dos veces, y una llamada que expire se reintentará. Si tu lógica de actualización fuera una mutación relativa (“añade 1 año”, “añade un entitlement”), un duplicado doblaría la expiración o acumularía una segunda copia. Así que modela la actualización como una declaración de estado objetivo, no como un delta.
El PATCH anterior hace esto: fija el nivel, la lista completa de entitlements y el expiresAt absoluto. Envíalo dos veces y la licencia converge al mismo registro — nivel pro, esos entitlements, esa expiración. La cabecera Idempotency-Key: order-558120 lo hace explícito: Keyright registra el resultado bajo esa clave, así que un reintento reproduce el resultado almacenado en lugar de volver a aplicar el cambio. Asóciala a la referencia del pedido o del pago — algo estable entre reintentos de la misma compra y distinto entre compras genuinamente diferentes.
// Manejador del webhook de facturación — seguro de ejecutar en cada entrega del evento.
app.MapPost("/webhooks/billing", async (BillingEvent e) =>
{
if (e.Type != "order.paid") return Results.Ok();
await adminApi.PatchLicenseAsync(e.LicenseId, new LicensePatch
{
Tier = e.PlanTier, // "pro"
Entitlements = EntitlementsForPlan(e.PlanTier),
ExpiresAt = e.CurrentPeriodEnd, // absoluto, no relativo
Trial = false,
}, idempotencyKey: e.OrderId);
return Results.Ok();
});
Bajadas de nivel y expiración
El mismo camino se ejecuta a la inversa, y como la app protege con entitlements no necesita código nuevo para manejarlo. Cuando una suscripción caduca, o dejas pasar el expiresAt o haces PATCH de la licencia al nivel inferior con el conjunto de entitlements reducido. En la próxima revalidación la concesión firmada ya no lleva pro.export, HasEntitlement("pro.export") devuelve false, y la interfaz protegida se degrada. Un plan perpetuo con el mantenimiento caducado es la misma idea — concedes los entitlements que al cliente todavía se le deben y retiras el resto.
Dos reglas mantienen esto limpio. Falla en modo cerrado: si result.IsValid es false, no concedas nada — nunca caigas en funciones de pago ante un error. Y degrada, no destruyas: una bajada de nivel debe ocultar o deshabilitar funciones, no borrar los datos del cliente, de modo que una eventual nueva subida simplemente vuelva a desbloquear lo que ya estaba ahí.
Mantén una traza de auditoría
Cada uno de estos PATCH es un cambio de entitlements contra una licencia concreta, y querrás el historial: cuándo la prueba pasó a Pro, qué complemento aterrizó en qué fecha, quién autorizó una actualización de cortesía. Keyright registra cada mutación de administración como un evento en la licencia — el actor, el nivel y el conjunto de entitlements antes/después, la clave de idempotencia y la marca de tiempo. Extraer ese historial de una licencia da una respuesta completa a “¿por qué tiene este cliente pro.batch?” sin adivinar, y es el registro con el que reconcilias frente a facturación cuando llega una disputa.
Todo el modelo, en una línea
Una licencia es una concesión mutable en el servidor detrás de una clave inmutable. Las actualizaciones, los cambios de nivel y los complementos son ediciones de la concesión; la clave nunca se mueve; el SDK refleja la edición en su próxima validación; y ajustas el tiempo de revalidación para decidir cuán instantáneo se siente eso. Escribe la app para que pregunte HasEntitlement(...) y falle en modo cerrado, y cada cambio comercial — de prueba a pago, de Standard a Pro, complemento, bajada de nivel — se convierte en un único PATCH idempotente con una traza de auditoría limpia detrás.
Prueba Nebula.NET
Endurece tu código .NET en minutos — empieza con la edición gratuita.