Casos de uso
Medir el uso y vender créditos
Vende consumo sobre el licenciamiento — renderizados, llamadas a la API, generaciones de IA, exportaciones — con bolsas de créditos de Keyright vinculadas a una licencia: tarifica cada acción, financia una bolsa y luego consulta saldos y gasta créditos desde tu aplicación con precio en seco y reintentos idempotentes, en línea o desde un bloque offline firmado.
Objetivo
Cobrar por el uso, no solo por el puesto. El licenciamiento responde a «¿puede este cliente ejecutar el software?»; los créditos responden a «¿cuánto ha consumido?» — para que puedas vender renderizados, llamadas a la API, generaciones de IA, exportaciones o cualquier acción medida sobre una licencia, con cuotas y excedente. Tu aplicación tarifica una acción, gasta créditos contra una bolsa vinculada a la clave de licencia del cliente, y Keyright descuenta de forma atómica y registra el uso.
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 producto — consulta Primeros pasos.
Cuándo usarlo
- Úsalo si tu producto vende consumo (por renderizado, por exportación, por generación) junto a — o en lugar de — una licencia plana por puestos, con cuotas, recargas y excedente.
- Úsalo si necesitas mostrar un coste antes de que el usuario confirme (precio en seco) o medir en máquinas aisladas (bloques de crédito firmados).
- No lo uses si solo vendes puestos y licencias perpetuas/por plazo — los créditos son puramente aditivos y un producto que nunca configura una bolsa nunca los toca.
El modelo
- Bolsa de créditos — un saldo de créditos vinculado a una clave de licencia. Una licencia puede tener una o varias bolsas (p. ej. una bolsa mensual de «renders» y una bolsa de recarga para «excedente»), cada una con un nombre de unidad que eliges.
- Coste de acción — cuánto cuesta en créditos una unidad de una
actionmedida. Los costes se definen por producto (p. ej.render= 1,hd-export= 5). - Consumir — tu aplicación gasta créditos por una acción; Keyright comprueba el saldo, lo descuenta de forma atómica y registra el uso. Saldo lee lo que queda.
El consumo usa autenticación por clave de licencia — la misma clave que tu aplicación ya tiene, sin token de administración. Las dos llamadas son solo en línea (no hay alternativa offline); para máquinas desconectadas, consulta bloques de crédito aislados.
Qué haces tú (lado del proveedor)
Configuración única: tarifica cada acción, crea una bolsa vinculada a una licencia y financiala. Hazlo desde el panel (la sección de créditos del producto) o desde la API de administración con tu token de administración del producto.
SVC=https://keyright.delta1labs.com
# 1. what an action costs
curl -X POST "$SVC/admin/products/<your-product>/action-costs" \
-H "X-Admin-Token: $TOKEN" -H "Content-Type: application/json" \
-d '{"action":"render","credits":1}'
# 2. a pool bound to a license key (-> returns {"id":"pool_..."})
curl -X POST "$SVC/admin/credit-pools" \
-H "X-Admin-Token: $TOKEN" -H "Content-Type: application/json" \
-d '{"licenseId":"<LICENSE_KEY>","product":"<your-product>","name":"Render credits","unit":"renders"}'
# 3. fund it
curl -X POST "$SVC/admin/credit-pools/<POOL_ID>/grant" \
-H "X-Admin-Token: $TOKEN" -H "Content-Type: application/json" \
-d '{"amount":1000}'
Las bolsas también admiten recarga, transferencia, reinicios programados y umbrales de saldo bajo; el uso se puede consultar por bolsa y entre productos para la generación de informes (GET /admin/usage). Consulta la referencia de la API HTTP para ver toda la superficie de administración.
balance().En tu código
Cada SDK expone las mismas dos llamadas; por HTTP en bruto son POST /v1/balance y POST /v1/consume. Dos características las hacen seguras en producción:
dryRun— tarifica una acción sin cobrar, p. ej. para mostrar un coste antes de que el usuario confirme.idempotencyKey— una clave que tú aportas para que una llamada reintentada repita el primer resultado en lugar de cobrar dos veces. Pásala siempre en un cobro real, así un reintento de red nunca factura por partida doble.
consume devuelve un status de ok, insufficient (créditos insuficientes), unknown_action (sin coste configurado), no_pool / ambiguous_pool (no hay una única bolsa de la que descontar) o not_found.
// .NET
var pools = await client.BalanceAsync(licenseKey); // remaining balance per pool
var quote = await client.ConsumeAsync(licenseKey, "render", dryRun: true); // price only
var res = await client.ConsumeAsync(licenseKey, "render", quantity: 1, idempotencyKey: txnId);
if (res.Status == "ok") Console.WriteLine($"charged {res.TotalCost} {res.Unit}, {res.Balance} left");
// Node.js
const { pools } = await client.balance(licenseKey);
const quote = await client.consume(licenseKey, 'render', { dryRun: true });
const res = await client.consume(licenseKey, 'render', { quantity: 1, idempotencyKey: txnId });
# Python
pools = client.balance(license_key)
quote = client.consume(license_key, "render", dry_run=True)
res = client.consume(license_key, "render", quantity=1, idempotency_key=txn_id)
// Java
List<PoolBalance> pools = client.balance(licenseKey);
ConsumeResult quote = client.consume(licenseKey, "render", 1, null, true); // dry run
ConsumeResult res = client.consume(licenseKey, "render", 1, txnId, false); // real charge
# Any language (raw HTTP) — the same two calls, authenticated with the license key, no admin token
curl -s -X POST "$BASE/v1/balance" -H "content-type: application/json" \
-d '{"key":"<LICENSE_KEY>","product":"<your-product>"}' # remaining balance per pool
curl -s -X POST "$BASE/v1/consume" -H "content-type: application/json" \
-d '{"key":"<LICENSE_KEY>","product":"<your-product>","action":"render","dryRun":true}' # price only
curl -s -X POST "$BASE/v1/consume" -H "content-type: application/json" \
-d '{"key":"<LICENSE_KEY>","product":"<your-product>","action":"render","quantity":1,"idempotencyKey":"<txn-id>"}'
# -> { "status":"ok", "totalCost":1, "unit":"renders", "balance":4929 } (fail closed on any non-ok status)
Cualquier lenguaje sin SDK usa estos endpoints HTTP directamente — consulta Usar la API HTTP directamente. Hay recorridos ejecutables de todo lo anterior (operación 6) en los ejemplos del SDK en GitHub.
Cuando una bolsa se agota, consume devuelve insufficient y no descuenta. Tu aplicación decide si bloquear la acción, ponerla en cola o pedir al cliente que recargue — configura una bolsa de excedente para permitir un excedente controlado.
Bloques de crédito aislados
Las máquinas desconectadas también pueden medir: el proveedor emite un bloque de crédito firmado (una asignación fija que el cliente gasta offline) y concilia la cantidad gastada cuando la máquina se vuelve a conectar. Esto mantiene los productos basados en uso funcionando en despliegues totalmente aislados (air-gapped). Los bloques aislados son un derecho de los niveles autoalojados superiores. Consulta Funcionar offline / aislado para el panorama offline completo.
Cloud frente a autoalojado
El modelo de créditos, las dos llamadas de runtime y la configuración de administración son idénticos en ambos modos. Las diferencias:
- URL base / token.
$BASE/SVCeshttps://keyright.delta1labs.comen Keyright Cloud o la URL de tu propio servicio de emisión cuando es autoalojado; las llamadas de runtimebalance/consumese autentican con la clave de licencia del cliente en ambos casos. - Los bloques de crédito aislados son una característica de los niveles autoalojados superiores (una máquina aislada no puede llegar a Keyright Cloud en absoluto), mientras que la medición en línea funciona en ambos.
Verificar
- Tarifica una acción, crea una bolsa sobre una licencia de prueba y concédele créditos — confirma que la bolsa muestra el saldo financiado (
BalanceAsync/POST /v1/balance). - Llama a
consumepara la acción condryRun: truey confirma que devuelve el precio con el saldo sin cambios. - Llama a
consumede verdad con unaidempotencyKey— confirmastatus: ok, que el saldo baja en el coste de la acción y que el uso queda registrado. - Vuelve a llamar a
consumecon la mismaidempotencyKey— confirma que repite el primer resultado y no vuelve a cobrar. - Agota la bolsa y confirma que
consumedevuelveinsufficientsin descontar.
Véase también
- Primeros pasos — emite y verifica tu primera licencia.
- Vender actualizaciones y controlar versiones — controla qué compilaciones puede usar una licencia.
- Funcionar offline / aislado — leases offline firmados, archivos de licencia y bloques de crédito.
- Referencia de la API HTTP — el mapa completo de endpoints de administración + runtime.