Créditos y uso medido

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. Los créditos son opcionales: un producto que solo vende puestos nunca tiene que usarlos.

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 (por ejemplo, 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 action medida (p. ej. render = 1, hd-export = 5). Los defines por producto.
• 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 sin conexión); para máquinas desconectadas, consulta la sección «Bloques de crédito aislados» más abajo.

En tu aplicación

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

Cualquier lenguaje sin SDK usa los 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.

Configuración inicial del proveedor

Configura los costes y financia las bolsas desde la API de administración (con tu token de administración del producto) o el panel. Tarifica una acción, crea una bolsa vinculada a una licencia y concede créditos:

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. Consulta la referencia de la API HTTP para ver toda la superficie de administración.

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 sin conexión) 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. Los bloques aislados son un derecho de los niveles autoalojados superiores.

Preguntas frecuentes

¿Tengo que usar créditos? No. Los créditos son puramente aditivos — el licenciamiento por puestos y perpetuo funciona exactamente como antes si nunca configuras una bolsa.

¿Qué ocurre 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).

¿Es seguro reintentar un cobro? Sí, cuando pasas una idempotencyKey. Una llamada repetida con la misma clave devuelve el resultado original y nunca vuelve a cobrar.