Skip to content
← Todas las publicaciones
· Delta1 Labs LicensingKeyright

Aprovisionamiento masivo de licencias con la API de administración de Keyright

Dar de alta un acuerdo empresarial de 2000 puestos con un POST a la vez es lento y te deja adivinando cuando un lote muere a la mitad. Así se aprovisiona en masa y se reejecuta con seguridad.

Un único POST /v1/admin/licenses por cliente es la forma correcta para la gestión diaria: un pago se confirma, tu manejador de webhook emite una licencia, listo. Deja de ser la forma correcta el día que un equipo de ventas cierra un acuerdo empresarial de 2000 puestos y alguien necesita aprovisionar cada uno de esos puestos antes de la reunión de arranque, o cuando das de alta a un revendedor cuyo catálogo siembra unos cientos de licencias de una vez.

Ejecuta eso como un bucle de 2000 POST individuales y surgen dos problemas de inmediato. Es lento: unos pocos cientos de milisegundos de ida y vuelta cada uno, en serie, son minutos de tiempo real y mucho desgaste de conexiones. Peor aún, es frágil a la mitad: si el trabajo muere en el elemento 1742 —un corte de red, un reinicio de proceso, un despliegue— te quedas adivinando qué licencias existen y cuáles no, y una reejecución ingenua arriesga acuñar 1741 duplicados. La solución es el endpoint de lotes de la API de administración, que emite muchas licencias en una sola solicitud, informa de un resultado por cada elemento y es seguro de reejecutar.

Idea clave: aprovisiona en masa con POST /v1/admin/licenses:batch en lugar de un bucle de un POST por licencia. Da a la solicitud una Idempotency-Key a nivel de lote y a cada elemento su propia idempotencyKey (derivada del id de tu registro) más un externalId para la unión de vuelta. El endpoint procesa los elementos de forma independiente y devuelve un resultado por elemento —created, duplicate o failed— así que un registro defectuoso nunca revierte los buenos y solo reintentas los fallos. Para miles de elementos, usa la forma asíncrona: el POST te devuelve un identificador de trabajo, consultas el trabajo hasta completed y luego lees los mismos resultados por elemento.

Por qué el bucle ingenuo duele

El bucle parece correcto en un script y se derrumba en producción:

// ANTIPATRÓN: un POST por cliente, sin idempotencia, sin plan para fallos parciales.
foreach (var seat in enterpriseDeal.Seats)          // 2.000 iteraciones
{
    var resp = await http.PostAsJsonAsync("/v1/admin/licenses", new {
        product = "acme-suite", edition = "pro", customer = seat.CustomerId });
    resp.EnsureSuccessStatusCode();                 // lanza → el bucle muere a la mitad
}

EnsureSuccessStatusCode() convierte el primer 503 transitorio en una excepción que aborta el bucle, y como nada registra qué puestos ya tuvieron éxito, tu única recuperación es empezar de nuevo, reemitiendo licencias para cada cliente procesado hasta ahora. Puedes añadir idempotencia por elemento a este bucle (y deberías, si un bucle es todo lo que tienes), pero sigues pagando 2000 idas y vueltas en serie y obteniendo 2000 señales independientes de éxito/fallo que tienes que coser tú mismo.

El endpoint de lotes

Una solicitud lleva un array de elementos. La solicitud recibe una Idempotency-Key a nivel de lote; cada elemento recibe su propia idempotencyKey y un externalId que lo vincula a tu registro.

POST /v1/admin/licenses:batch HTTP/1.1
Host: licensing.example.com
Authorization: Bearer {admin_token}
Idempotency-Key: deal-ACME-2026-11-15
Content-Type: application/json

{
  "defaults": { "product": "acme-suite", "edition": "pro", "seats": 1 },
  "items": [
    { "externalId": "crm:row_8831", "licensee": "ana@acme.example",
      "entitlements": { "export": "true" }, "idempotencyKey": "crm:row_8831" },
    { "externalId": "crm:row_8832", "licensee": "ben@acme.example",
      "idempotencyKey": "crm:row_8832" }
  ]
}

defaults se aplica a cada elemento para que no repitas product y edition 2000 veces; cualquier campo fijado en un elemento anula el valor por defecto. La respuesta es un estado múltiple: un 207 general, con un objeto de resultado por elemento en el mismo orden en que los enviaste.

HTTP/1.1 207 Multi-Status
Content-Type: application/json

{
  "created": 1,
  "duplicate": 1,
  "failed": 0,
  "results": [
    { "externalId": "crm:row_8831", "status": "created",
      "licenseId": "lic_7f3a9c2e" },
    { "externalId": "crm:row_8832", "status": "duplicate",
      "licenseId": "lic_41b0d8a7" }
  ]
}

Tres resultados por elemento, y la distinción es todo el objetivo:

  • created — se acuñó una licencia nueva; licenseId es tuyo para persistir.
  • duplicate — ya se había emitido un elemento con esta idempotencyKey; se devuelve el id de licencia existente y no se acuña nada nuevo. Esto es lo que hace segura una reejecución.
  • failed — el elemento fue rechazado (un campo obligatorio ausente, un licensee malformado); un reason y un code dicen por qué. Los demás elementos no se ven afectados.
cliente deaprovisión.endpoint de lotes/admin/licenses:batch — N elem.created→ persistir licenseIdduplicate→ licenseId existentefailed→ reason + codePOST lote (idempotente)reenviar SOLO el subconjunto fallidomisma idempotencyKey por elemento → los previos vuelven como duplicate, nunca reacuñados

Un cliente de aprovisionamiento que se reejecuta con seguridad

El ayudante del lado del proveedor hace cuatro cosas: fragmenta tus registros en lotes, envía cada lote, recoge los resultados por elemento y escribe de vuelta los id de licencia en tu sistema de registro. La fragmentación importa: una sola solicitud de 2000 elementos es mucho que mantener abierto, y unos pocos cientos por lote mantienen cada petición rápida mientras sigue recortando las idas y vueltas en dos órdenes de magnitud.

public sealed class LicenseProvisioner(HttpClient http)
{
    const int ChunkSize = 200;

    public async Task<ProvisionReport> ProvisionAsync(
        IReadOnlyList<SeatRecord> seats, CancellationToken ct)
    {
        var report = new ProvisionReport();

        foreach (var chunk in seats.Chunk(ChunkSize))
        {
            var body = new BatchRequest
            {
                Defaults = new() { Product = "acme-suite", Edition = "pro", Seats = 1 },
                Items = chunk.Select(s => new BatchItem
                {
                    ExternalId     = s.CrmRowId,          // clave de unión con tu CRM
                    Licensee       = s.Email,
                    IdempotencyKey = s.CrmRowId,          // la misma clave hace seguras las reejecuciones
                }).ToArray(),
            };

            using var req = new HttpRequestMessage(HttpMethod.Post, "/v1/admin/licenses:batch");
            req.Headers.Add("Idempotency-Key", $"deal-{DealId}-{chunk[0].CrmRowId}");
            req.Content = JsonContent.Create(body);

            // Reintentar el lote completo es seguro: los creados vuelven como `duplicate`.
            var resp = await Resilience.Pipeline.ExecuteAsync(
                async t => await http.SendAsync(req, t), ct);

            var batch = await resp.Content.ReadFromJsonAsync<BatchResponse>(ct);
            foreach (var r in batch!.Results)
                report.Record(r);                         // persistir licenseId o registrar el fallo
        }

        return report;
    }
}

Como cada elemento lleva una idempotencyKey derivada de un id de registro estable, reejecutar toda la llamada ProvisionAsync —tras un fallo, un lote a medio terminar o simplemente porque una reconciliación nocturna vuelve a ejecutarse— nunca duplica. Los elementos ya emitidos vuelven como duplicate con su id de licencia original; solo los registros genuinamente nuevos son created. Obtienes el subconjunto fallido directamente de report y puedes reenviar solo esos una vez corregido el registro subyacente.

Grandes volúmenes: el trabajo asíncrono

Por encima de unos pocos cientos de elementos, prefiere la forma asíncrona para no mantener una única petición HTTP abierta mientras se acuñan miles de licencias. Añade "mode": "async" y el endpoint devuelve un identificador de trabajo en lugar de resultados en línea:

POST /v1/admin/licenses:batch HTTP/1.1
Authorization: Bearer {admin_token}
Idempotency-Key: deal-ACME-2026-11-15

{ "mode": "async", "defaults": { "product": "acme-suite", "edition": "pro" },
  "items": [ /* 2.000 elementos */ ] }
HTTP/1.1 202 Accepted
{ "jobId": "job_b914f27c", "status": "pending", "total": 2000 }

Consulta el trabajo hasta que se asiente y luego lee los mismos results por elemento que habrías obtenido de forma síncrona:

BatchResponse job;
do
{
    await Task.Delay(TimeSpan.FromSeconds(2), ct);
    job = await http.GetFromJsonAsync<BatchResponse>(
        $"/v1/admin/jobs/{jobId}", ct);
}
while (job!.Status is "pending" or "running");

foreach (var r in job.Results) report.Record(r);   // created / duplicate / failed, como antes

El trabajo es direccionable por su id, así que la consulta sobrevive a un reinicio de tu proceso de aprovisionamiento: persistes el jobId, y si tu worker muere, reanudas la consulta del mismo trabajo en lugar de reemitir. La Idempotency-Key a nivel de lote garantiza que incluso enviar el mismo lote dos veces devuelva el mismo trabajo en lugar de iniciar un segundo.

El lado del cliente: nada especial

Todo lo anterior produce licencias ordinarias: la emisión masiva es una comodidad para el proveedor, no un tipo de licencia distinto. Cada puesto aprovisionado se valida a través del SDK exactamente como uno emitido de forma individual, sin conexión contra la clave pública incrustada:

var client = KeyrightClient.Initialize(new KeyrightOptions
{
    Product         = "acme-suite",
    PublicKeyBase64 = Embedded.PublicKey,     // se incluye en tu binario; no es un secreto
    ServiceUrl      = "https://licensing.example.com",
});

LicenseInfo info = client.Validate();          // sin conexión, nunca lanza
if (!info.IsValid || !info.IsEnabled("acme.export"))
    return Gate.Deny("La exportación requiere una licencia activa.");

El usuario final nunca sabe si su puesto fue uno de dos o uno de dos mil. Esa separación —masivo en el lado de la emisión, verificación idéntica en el lado del cliente— es lo que te permite dar de alta un acuerdo empresarial en una sola operación reconciliable sin cambiar una línea del código de control que ejecutan tus clientes.

Rendimiento, en breve

Dos límites prácticos moldean cómo marcas el ritmo de un despliegue grande. Mantén los fragmentos en los cientos bajos para que cada petición siga siendo rápida y el array de resultados por elemento siga siendo fácil de manejar. Y conduce los lotes con una pequeña concurrencia acotada en lugar de mil peticiones en paralelo: una cola corta de dos o tres lotes en vuelo basta para saturar el rendimiento del servicio de emisión sin disparar sus límites de tasa. Cuando un lote vuelve limitado por tasa, el reintento con fluctuación de tu pipeline de resiliencia lo maneja, y como el lote es idempotente, el reintento está libre de duplicados.

Esa es toda la forma del aprovisionamiento masivo bien hecho: una llamada de lote idempotente por fragmento, un resultado por elemento que puedes reconciliar con tus registros por externalId, un trabajo asíncrono para los despliegues grandes y una reejecución siempre segura porque cada elemento conoce su propia identidad. El acuerdo de 2000 puestos se vuelve una operación que puedes ejecutar, inspeccionar y volver a ejecutar, no un bucle frágil que esperas que termine.

Prueba Nebula.NET

Endurece tu código .NET en minutos — empieza con la edición gratuita.