Provisionnement de licences en masse via l'API d'administration Keyright
Intégrer un contrat entreprise de 2000 postes un POST à la fois est lent et vous laisse deviner quand un lot meurt en cours de route. Voici comment provisionner en masse et relancer sans risque.
Un seul POST /v1/admin/licenses par client est la bonne forme pour la facturation quotidienne : un paiement passe, votre gestionnaire de webhook émet une licence, terminé. Ce n’est plus la bonne forme le jour où une équipe commerciale conclut un contrat entreprise de 2000 postes et où quelqu’un doit provisionner chacun de ces postes avant la réunion de lancement — ou quand vous intégrez un revendeur dont le catalogue amorce quelques centaines de licences d’un coup.
Exécutez cela comme une boucle de 2000 POST individuels et deux problèmes surgissent aussitôt. C’est lent : quelques centaines de millisecondes d’aller-retour chacun, en série, font des minutes de temps réel et beaucoup de va-et-vient de connexions. Pire, c’est fragile en plein milieu : si le travail meurt à l’élément 1742 — un incident réseau, un redémarrage de processus, un déploiement — vous êtes réduit à deviner quelles licences existent et lesquelles non, et une relance naïve risque de frapper 1741 doublons. La solution est le point de terminaison par lots de l’API d’administration, qui émet de nombreuses licences en une seule requête, rapporte un résultat pour chaque élément et peut être relancé sans risque.
À retenir : provisionnez en masse avec POST /v1/admin/licenses:batch au lieu d’une boucle d’un POST par licence. Donnez à la requête une Idempotency-Key au niveau du lot et à chaque élément sa propre idempotencyKey (dérivée de l’id de votre enregistrement) plus un externalId pour la jointure retour. Le point de terminaison traite les éléments indépendamment et renvoie un résultat par élément — created, duplicate ou failed — de sorte qu’un enregistrement défectueux n’annule jamais les bons et que vous ne relancez que les échecs. Pour des milliers d’éléments, utilisez la forme asynchrone : le POST vous rend un identifiant de travail, vous interrogez le travail jusqu’à completed, puis vous lisez les mêmes résultats par élément.
Pourquoi la boucle naïve fait mal
La boucle paraît correcte dans un script et s’effondre en production :
// ANTI-MODÈLE : un POST par client, sans idempotence, sans plan pour les échecs partiels.
foreach (var seat in enterpriseDeal.Seats) // 2 000 itérations
{
var resp = await http.PostAsJsonAsync("/v1/admin/licenses", new {
product = "acme-suite", edition = "pro", customer = seat.CustomerId });
resp.EnsureSuccessStatusCode(); // lève → la boucle meurt en cours
}
EnsureSuccessStatusCode() transforme le premier 503 transitoire en exception qui interrompt la boucle, et comme rien n’enregistre quels postes ont déjà réussi, votre seul recours est de recommencer, en réémettant des licences pour chaque client déjà traité. Vous pouvez greffer l’idempotence par élément sur cette boucle (et vous le devriez, si une boucle est tout ce que vous avez), mais vous payez toujours 2000 allers-retours en série et obtenez 2000 signaux de succès/échec indépendants que vous devez recoudre vous-même.
Le point de terminaison par lots
Une requête porte un tableau d’éléments. La requête reçoit une Idempotency-Key au niveau du lot ; chaque élément reçoit sa propre idempotencyKey et un externalId qui le relie à votre enregistrement.
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 s’applique à chaque élément pour que vous ne répétiez pas product et edition 2000 fois ; tout champ fixé sur un élément remplace la valeur par défaut. La réponse est un statut multiple : un 207 global, avec un objet de résultat par élément dans le même ordre que celui de l’envoi.
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" }
]
}
Trois issues par élément, et la distinction est tout l’objectif :
created— une nouvelle licence a été frappée ;licenseIdest à vous pour le persister.duplicate— un élément avec cetteidempotencyKeyavait déjà été émis ; l’id de licence existant est renvoyé et rien de nouveau n’est frappé. C’est ce qui rend une relance sûre.failed— l’élément a été rejeté (un champ obligatoire manquant, unlicenseemal formé) ; unreasonet uncodedisent pourquoi. Les autres éléments ne sont pas affectés.
Un client de provisionnement qui se relance sans risque
L’assistant côté éditeur fait quatre choses : il découpe vos enregistrements en lots, envoie chaque lot, collecte les résultats par élément et réécrit les id de licence dans votre système de référence. Le découpage compte : une seule requête de 2000 éléments est beaucoup à maintenir ouverte, et quelques centaines par lot gardent chaque requête rapide tout en réduisant les allers-retours de deux ordres de grandeur.
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, // clé de jointure vers votre CRM
Licensee = s.Email,
IdempotencyKey = s.CrmRowId, // la même clé rend les relances sûres
}).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);
// Relancer tout le lot est sûr : les éléments créés reviennent en `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); // persister licenseId ou journaliser l'échec
}
return report;
}
}
Comme chaque élément porte une idempotencyKey dérivée d’un id d’enregistrement stable, relancer tout l’appel ProvisionAsync — après un plantage, un lot à moitié terminé, ou simplement parce qu’une réconciliation nocturne s’exécute à nouveau — ne duplique jamais. Les éléments déjà émis reviennent en duplicate avec leur id de licence d’origine ; seuls les enregistrements réellement nouveaux sont created. Vous obtenez le sous-ensemble en échec directement depuis report et pouvez ne renvoyer que ceux-là une fois l’enregistrement sous-jacent corrigé.
Gros volumes : le travail asynchrone
Au-delà de quelques centaines d’éléments, préférez la forme asynchrone pour ne pas maintenir une unique requête HTTP ouverte pendant que des milliers de licences sont frappées. Ajoutez "mode": "async" et le point de terminaison renvoie un identifiant de travail au lieu de résultats en ligne :
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 éléments */ ] }
HTTP/1.1 202 Accepted
{ "jobId": "job_b914f27c", "status": "pending", "total": 2000 }
Interrogez le travail jusqu’à ce qu’il se stabilise, puis lisez les mêmes results par élément que vous auriez obtenus de façon synchrone :
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, comme avant
Le travail est adressable par son id, si bien que l’interrogation survit à un redémarrage de votre processus de provisionnement : vous persistez le jobId, et si votre worker meurt, vous reprenez l’interrogation du même travail au lieu de réémettre. La Idempotency-Key au niveau du lot garantit que même en soumettant deux fois le même lot, vous obtenez le même travail au lieu d’en démarrer un second.
Côté client : rien de spécial
Tout ce qui précède produit des licences ordinaires : l’émission en masse est une commodité pour l’éditeur, pas un type de licence différent. Chaque poste provisionné se valide via le SDK exactement comme un poste émis individuellement, hors ligne contre la clé publique embarquée :
var client = KeyrightClient.Initialize(new KeyrightOptions
{
Product = "acme-suite",
PublicKeyBase64 = Embedded.PublicKey, // embarquée dans votre binaire ; ce n'est pas un secret
ServiceUrl = "https://licensing.example.com",
});
LicenseInfo info = client.Validate(); // hors ligne, ne lève jamais
if (!info.IsValid || !info.IsEnabled("acme.export"))
return Gate.Deny("L'export nécessite une licence active.");
L’utilisateur final ne sait jamais si son poste était l’un de deux ou l’un de deux mille. Cette séparation — en masse côté émission, vérification identique côté client — est ce qui vous permet d’intégrer un contrat entreprise en une seule opération réconciliable sans changer une ligne du code de contrôle que vos clients exécutent.
Débit, en bref
Deux limites pratiques façonnent la façon dont vous cadencez un grand déploiement. Gardez les tranches dans les basses centaines pour que chaque requête reste rapide et que le tableau de résultats par élément reste facile à manipuler. Et pilotez les lots avec une petite concurrence bornée plutôt que mille requêtes en parallèle : une courte file de deux ou trois lots en vol suffit à saturer le débit du service d’émission sans déclencher ses limites de taux. Quand un lot revient limité en taux, le renvoi avec gigue de votre pipeline de résilience le gère, et comme le lot est idempotent, le renvoi est exempt de doublons.
Voilà toute la forme du provisionnement en masse bien fait : un appel de lot idempotent par tranche, un résultat par élément que vous pouvez réconcilier avec vos enregistrements par externalId, un travail asynchrone pour les grands déploiements, et une relance toujours sûre parce que chaque élément connaît sa propre identité. Le contrat de 2000 postes devient une opération que vous pouvez exécuter, inspecter et réexécuter — pas une boucle fragile dont vous espérez qu’elle finira.
Essayez Nebula.NET
Renforcez votre code .NET en quelques minutes — commencez avec l'édition gratuite.