Comprobar claves de licencia desde tu app en Node o Go: límite de dispositivos, caducidad y revocación
Cuando Skalp genera una clave de licencia para cada venta, tu app la comprueba con una sola llamada a la API. La respuesta dice si la clave funciona y, si no, por qué: ha caducado, se revocó tras un reembolso, superó su límite de dispositivos o pertenece a una suscripción que terminó. Abajo tienes la configuración y el código para Node, Go y HTTP sin más.
Configura el producto
- Crea un producto y pon su entrega en clave de licencia. Cada pedido recibe entonces una clave nueva.
- Fija un límite de dispositivos si una clave solo debe funcionar en unos pocos equipos, y una duración si la licencia debe caducar tras un número de días. Deja la duración vacía para una licencia de por vida, o vende el producto como suscripción para que la clave funcione mientras el plan esté pagado.
- Crea una clave API con un solo alcance,
licenses:validate. Con ese alcance la clave no puede leer pedidos ni cambiar nada, así que puede ir dentro de tu app.
Node
import { Skalp } from '@skalpgg/sdk'
const skalp = new Skalp({ apiKey: LICENSE_CHECK_KEY })
const result = await skalp.licenses.validate({
key: enteredKey,
hardwareId: machineId,
})
if (!result.valid) {
showError(result.message)
} else {
unlock(result.license?.expiresAt)
}
El paquete funciona en Node 20+, Bun, Deno y entornos edge. En un navegador se niega a arrancar con una clave API salvo que pases dangerouslyAllowBrowser: true, así que la comprobación para una página web va en tu servidor.
Go
client := skalp.New(skalp.Options{APIKey: licenseCheckKey})
res, err := client.ValidateLicense(ctx, skalp.ValidateLicenseParams{
Key: enteredKey,
HardwareID: machineID,
})
if err != nil {
return err
}
if !res.Valid {
return fmt.Errorf("license: %s", res.Message)
}
Cualquier otro lenguaje
curl https://api.skalp.gg/v1/licenses/validate \
-H "x-api-key: $SKALP_LICENSE_CHECK_KEY" \
-H "content-type: application/json" \
-d '{"key":"THE-BUYERS-KEY","hardwareId":"9f2c41..."}'
Añade "productId" al cuerpo si una clave de otro de tus productos no debe desbloquear este.
Qué significan los códigos
| Código | Significado |
|---|
VALID | La clave funciona. La respuesta incluye también su fecha de caducidad y cuántos dispositivos usa. |
NOT_FOUND | No existe ninguna clave así en tu tienda. |
PRODUCT_MISMATCH | La clave pertenece a un producto distinto del productId enviado. |
LICENSING_DISABLED | La entrega del producto no está en clave de licencia. |
REVOKED | El pedido se reembolsó o perdió un contracargo. |
SUSPENDED | La licencia está suspendida. |
EXPIRED | La licencia ha pasado su fecha de fin. |
SUBSCRIPTION_INACTIVE | La suscripción a la que pertenece la clave ha terminado. |
DEVICE_LIMIT_REACHED | La clave ya está vinculada a tantos equipos como permite el producto. |
Límite de dispositivos
Si envías un hardwareId y el producto tiene límite de dispositivos, la primera comprobación desde un equipo nuevo lo vincula a la clave. Las comprobaciones desde equipos vinculados pasan, y un equipo nuevo por encima del límite recibe DEVICE_LIMIT_REACHED. Envía un valor que no cambie en un mismo equipo y aplícale un hash antes, para que ningún dato de hardware en bruto salga del ordenador. Cuando un comprador cambia de PC, tu servidor puede liberar las plazas con licenses.resetDevices. Esa llamada necesita el alcance licenses:write, así que nunca va dentro de la propia app.
Funcionar sin conexión
Comprueba la clave al arrancar la app y guarda la última respuesta buena con su fecha. Si no hay red, acepta la respuesta guardada durante el periodo de gracia que elijas, unos días por ejemplo, y vuelve a comprobar cuando la app recupere la conexión. Una clave revocada mientras tanto falla en esa comprobación.
Tener tu propia copia
Si prefieres comprobar las claves en tu propio backend, tómalas del webhook order.paid, que lleva las licencias del pedido. Los webhooks de reembolsos y disputas te dicen cuándo desactivar una clave. Webhooks y la API.
Preguntas frecuentes
¿Es seguro meter una clave API en una app de escritorio?
Solo una clave cuyo único alcance sea licenses:validate. Puede comprobar claves y nada más.
¿Puede un comprador pasar su licencia a un ordenador nuevo?
Sí, en cuanto liberes sus dispositivos con licenses.resetDevices desde tu servidor o tu herramienta de soporte.
¿Qué pasa con la clave cuando termina una suscripción?
A partir de ese momento la comprobación devuelve SUBSCRIPTION_INACTIVE.
¿Tengo que usar el SDK?
No. La comprobación es un único POST por HTTPS con un cuerpo JSON, así que sirve cualquier lenguaje que pueda enviar una petición.