Casos de uso
Ofrecer una prueba gratuita
Deja que los clientes obtengan por sí mismos una clave de prueba con tiempo limitado desde tu propio sitio — Keyright la acuña, la envía por correo y tu aplicación la activa exactamente igual que una clave de pago — o entrega a un evaluador aislado un archivo de prueba offline firmado.
Objetivo
Deja que un cliente potencial pruebe tu producto antes de comprarlo, sin trabajo por tu parte: hace clic en Start free trial (iniciar prueba gratuita) en tu sitio de marketing, Keyright acuña una licencia de prueba con tiempo limitado, le envía la clave por correo y tu aplicación la activa exactamente igual que una clave de pago. Cuando la prueba expira, la aplicación vuelve a su estado sin licencia, y comprar una clave real sustituye a la prueba sin reinstalar.
A lo largo de la página, $BASE es la URL de tu servicio de emisión y $TOKEN es un token de administración del tenant — consulta Primeros pasos.
Cuándo usarlo
- Úsalo si quieres una evaluación de autoservicio impulsada desde tu propio sitio, una prueba por correo por producto, con el reloj arrancando cuando el cliente activa.
- Úsalo si tienes un evaluador aislado (air-gapped) o corporativo — entrégale en su lugar un archivo de prueba offline firmado (más abajo), sin necesidad de red.
- No lo uses para extender o convertir a un cliente de pago — las renovaciones y las mejoras son cambios del lado del proveedor sobre una licencia existente (consulta Activar, desactivar y mover puestos). Las pruebas están desactivadas por defecto; un producto las ofrece solo cuando estableces una duración de prueba.
Lo que haces tú (lado del proveedor)
1. Habilitar las pruebas en un producto
Una prueba se define por tres cosas: días (duración; <= 0 la desactiva), nivel (el nivel de funciones que otorga la prueba) y puestos.
Panel: abre la pestaña Products (productos) y establece la duración, el nivel y los puestos de la prueba en el producto.
pro) y puestos (1) — y confirma que cualquiera puede obtener una por sí mismo con un correo de trabajo.API — establécelos en un producto existente:
curl -X POST $BASE/admin/products/nebula/trial -H "X-Admin-Token: $TOKEN" -H "content-type: application/json" \
-d '{"days":30,"tier":"enterprise","seats":1}'
# -> { "product":"nebula", "trialDays":30, "trialTier":"enterprise", "trialSeats":1 }
O establécelos al crear el producto (trialDays, trialTier, trialSeats en POST /admin/products):
curl -X POST $BASE/admin/products -H "X-Admin-Token: $TOKEN" -H "content-type: application/json" \
-d '{"name":"Nebula","slug":"nebula","trialDays":30,"trialTier":"enterprise","trialSeats":1}'
GET /admin/products devuelve los trialDays/trialTier/trialSeats de cada producto. Pon days en 0 para volver a desactivar las pruebas.
2. Permitir que un cliente solicite una prueba
POST /v1/trial es público (sin autenticación) y abierto a CORS, de modo que un formulario de navegador en tu sitio de marketing puede hacerle POST directamente:
curl -X POST $BASE/v1/trial -H "content-type: application/json" \
-d '{"product":"nebula","email":"dev@acme.com","company":"Acme"}'
{
"ok": true,
"product": "nebula",
"trial": true,
"emailed": true,
"expiresUtc": "2026-10-23T12:00:00.0000000Z",
"days": 30,
"created": true
}
La respuesta confirma que la prueba se emitió y se envió por correo — deliberadamente no contiene la clave (ningún campo key, tier ni seats). Keyright envía por correo la clave de prueba a la dirección; el cliente la introduce luego en tu aplicación, donde se activa exactamente igual que una clave de pago.
| Campo | Obligatorio | Notas |
|---|---|---|
product | sí | el slug del producto |
email | sí | la prueba queda asociada a esta dirección |
company | no | se convierte en el nombre del licenciatario; por defecto es el correo |
tenant | no | solo necesario si el mismo slug existe en más de un tenant, para desambiguar |
Una prueba por correo por producto. Volver a solicitar con el mismo correo devuelve la misma clave (created:false) en lugar de acuñar una nueva — idempotente y resistente al abuso, de modo que un refresco o un segundo clic nunca reinicia el reloj ni acumula pruebas.
Respuestas:
| Estado | Cuándo |
|---|---|
200 | prueba emitida (o se devuelve la existente) |
400 | email/product faltante o inválido, o el slug existe en más de un tenant (pasa tenant) |
403 | las pruebas no están habilitadas para ese producto (trialDays <= 0) |
404 | producto desconocido |
Conectar un botón “Iniciar prueba gratuita”
Como /v1/trial está abierto a CORS, una página estática puede invocarlo con fetch:
<button id="trial">Start free trial</button>
<script>
document.getElementById('trial').onclick = async () => {
const res = await fetch('https://keyright.delta1labs.com/v1/trial', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ product: 'nebula', email: userEmail, company: userCompany }),
});
const data = await res.json();
// The key is emailed, not returned — tell the customer to check their inbox.
if (res.ok) show(`Check ${userEmail} for your trial key — it expires ${data.expiresUtc}.`);
else show(data.error);
};
</script>
En tu código
El cliente recibe la clave de prueba por correo y luego la introduce en tu aplicación — donde se activa exactamente igual que una clave de pago, sin una ruta de código de prueba aparte. Se la pasas a activate() como a cualquier clave de pago. Con Nebula, por ejemplo:
nebula register --key LIC-XXXXXXXXXXXXXXXXXXXX
Como una clave de prueba se activa mediante exactamente la misma llamada que una clave de pago, no hay que escribir ninguna ruta de código de prueba aparte — el fragmento de activación para .NET, Node.js, Python, Java y HTTP puro es el bloque multilenguaje de Activar, desactivar y mover puestos; pásale la clave de prueba sin cambios. La forma de CLI anterior realiza una activación en línea (POST /v1/activate), vincula la máquina y devuelve un lease firmado con trial:true y el vencimiento de la prueba. Tu aplicación lo lee de LicenseInfo: IsTrial == true, ExpiryUtc es el fin de la prueba y DaysRemaining va en cuenta atrás. Muestra el banner de evaluación (p. ej. “Prueba Enterprise — 27 días restantes”) y condiciona lo que quieras detrás de info.IsTrial. Gracias al lease en caché, la aplicación sigue funcionando offline hasta que expire la prueba; al vencer, el lease deja de validar y la aplicación falla de forma cerrada al estado gratuito/sin licencia (consulta Integración del SDK de .NET).
Las pruebas tienen en cuenta la duración desde la primera activación y la manipulación del reloj — un cliente no puede recuperar tiempo retrasando el reloj. De prueba a pago es fluido: cuando el cliente compra y activa una clave que no es de prueba, esta sustituye a la prueba restante sin reinstalar. La forma completa de activación para claves de prueba, por plazo y perpetuas está en Activar, desactivar y mover puestos.
Pruebas offline para evaluadores aislados
Las pruebas de autoservicio usan la ruta en línea, pero esa no es la única forma de probar. Para un evaluador aislado o corporativo también puedes repartir un archivo de licencia de prueba offline firmado y con tiempo limitado — sin necesidad de red en absoluto. Con la CLI de Nebula:
nebula license --sign --trial --tier enterprise --expiry 2026-10-23 \
--licensee "Acme Corp" --private-key ./keys/nebula.private.json --out acme-trial.json
El archivo lleva el indicador trial y un expiryUtc; el SDK lo valida contra la clave pública integrada y lo trata como una prueba hasta que expira. Este es el análogo offline del flujo de autoservicio anterior — la misma semántica de prueba, entregada como archivo en lugar de como activación. Consulta Ejecutar offline / aislado.
Cloud vs autoalojado
Solo dos cosas cambian entre Keyright Cloud y autoalojado: la URL $BASE (en Cloud es https://keyright.delta1labs.com) y de dónde sale $TOKEN. Un punto sí es realmente específico del modo:
- Las pruebas de autoservicio necesitan SMTP. Keyright entrega la clave de prueba por correo, de modo que la instancia debe tener SMTP configurado (
KEYRIGHT_SMTP_*) — sin él la prueba se acuña pero el cliente nunca recibe la clave. En Keyright Cloud la entrega de correo ya está conectada; en autoalojado la configuras tú. - La ruta del archivo de prueba offline no necesita SMTP (ni red) en absoluto.
Verificar
- Habilita las pruebas en el producto (
days > 0) y luego hazPOST /v1/trialcon un correo de prueba — espera200con"emailed": truey unexpiresUtc. - Comprueba la bandeja de entrada para ver la clave de prueba, y confirma que la vista Licenses del panel muestra ahora una licencia de prueba para ese correo.
- Activa la clave en tu aplicación y confirma que muestra el banner de evaluación con
IsTrial == truey unDaysRemainingen cuenta atrás. - Vuelve a solicitar la prueba con el mismo correo — espera la misma clave de vuelta y
"created": false(sin licencia nueva, sin reinicio del reloj).
Véase también
- Primeros pasos — emite y verifica tu primera licencia (de pago).
- Activar, desactivar y mover puestos — cómo se activan las claves de prueba, por plazo y perpetuas y cómo se reflejan en
LicenseInfo. - Ejecutar offline / aislado — archivos de licencia y de prueba offline firmados.
- Referencia de la API HTTP — el mapa completo de endpoints, incluido
/v1/trial.