Guide d’intégration
Du catalogue aux droits d’accès.
Un parcours serveur à serveur, du premier produit à un droit appliqué, une consommation contrôlée et un changement d’offre confirmé. Les exemples utilisent l’API HTTP existante de sayAllow.
Demandez l’accès à la console et configurez un produit. SAYALLOW_URL désigne l’URL publique de l’API de votre environnement, préfixe de gateway compris. SAYALLOW_PRODUCT_KEY désigne votre clé produit, conservée dans les secrets du backend.
Si votre gateway APIM exige une clé d’abonnement, ajoutez aussi le header Ocp-Apim-Subscription-Key. Il ne remplace pas la clé produit.
Le catalogue
Configurez ce que votre produit vend.
Dans la console, créez votre produit, ses offres et les fonctionnalités qu’elles incluent. Choisissez une offre gratuite ou une offre payante, ses cycles de facturation, ses sièges et ses quotas. Les prix ne sont pas codés en dur dans le produit.
Pour les paiements, configurez Stripe pour ce produit. Le Checkout hébergé et le portail de facturation passent par Stripe ; votre application ne collecte pas les données de carte.
curl "$SAYALLOW_URL/product/plans" -H "x-clavis-product-key: $SAYALLOW_PRODUCT_KEY"Le nom historique du header x-clavis-product-key reste le contrat HTTP actuel.
Le client
Reliez une organisation à votre compte client.
L’organisation représente l’équipe, l’espace de travail ou l’entité facturée. Créez-la une fois et conservez son identifiant dans votre base. Votre backend choisit cette organisation à partir de la session authentifiée.
POST /product/organizations
Content-Type: application/json
x-clavis-product-key: <server-side product key>
{
"name": "Atelier Studio",
"email": "billing@example.com"
}Ne transmettez pas votre clé produit au navigateur. Le navigateur appelle votre backend, qui vérifie le compte et transmet la demande à sayAllow.
L’activation
Choisissez le parcours de l’offre.
Offre gratuite : activation directe
Une offre kind: free s’active depuis le backend sans Stripe ni Checkout. La même activation est idempotente ; une autre souscription courante peut produire une réponse 409.
POST /product/organizations/<organization UUID>/subscriptions
Content-Type: application/json
x-clavis-product-key: <server-side product key>
{ "planId": "<free plan UUID>", "seatCount": 1 }Offre payante : Checkout hébergé
Choisissez un plan renvoyé par le catalogue. La création du Checkout renvoie une url Stripe hébergée et un sessionId. Redirigez le client vers cette url.
POST /product/checkout
Content-Type: application/json
x-clavis-product-key: <server-side product key>
{
"organizationId": "<organization UUID>",
"planId": "<paid plan UUID>",
"billingCycle": "monthly",
"seatCount": 5,
"successUrl": "https://app.example.com/billing/success",
"cancelUrl": "https://app.example.com/billing"
}Votre backend fixe les URLs de retour sur les origines autorisées de votre propre produit. Un retour sur successUrl ne prouve pas encore le paiement : affichez un état en attente et relisez la souscription.
La décision d’accès
Vérifiez un droit. Appliquez la réponse.
Après activation, votre backend demande si son organisation peut utiliser export:pdf. Une fonctionnalité de l’offre est reconnue depuis la licence de sa souscription ; aucun droit manuel supplémentaire n’est nécessaire.
GET /product/organizations/<organization UUID>/entitlements/export%3Apdf
x-clavis-product-key: <server-side product key>
HTTP 200
{ "capability": "export:pdf", "granted": true }Votre backend traduit granted: false en refus de cette action. Il traite séparément une indisponibilité de l’API : une erreur réseau ou un 5xx ne devient pas une confirmation de droit. La décision d’exécuter l’action reste dans votre application.
Les droits sont additifs : un droit manuel ou un pack actif peut aussi accorder la capacité. Révoquer une source ne supprime pas une autre source valide. La liste GET …/entitlements décrit l’historique des attributions ; utilisez la vérification par capacité pour connaître le droit effectif.
Pour la source abonnement, cette réponse booléenne exige une souscription et une licence utilisables en écriture. Une licence en grâce avec lecture seule n’accorde pas le droit par ce chemin. Les installations sur site utilisent le contrat de licence détaillé, sa signature, son expiration et son indicateur read_only pour appliquer leur propre mode dégradé.
La consommation prépayée
Débitez une fois. Reconnaissez une limite.
Lisez GET /product/organizations/{id}/credits : balance.available contient le solde utilisable. Ce solde est distinct des droits fonctionnels et des quotas du plan. Un simple contrôle du solde ne réserve pas les crédits ; le débit atomique est le point qui confirme ou refuse la consommation.
POST /product/organizations/<organization UUID>/usage
Content-Type: application/json
x-clavis-product-key: <server-side product key>
{
"action": "export.pdf",
"credits": 1,
"reference": "export-job-2026-001"
}
HTTP 201
{ "id": "<event UUID>", "credits": 1, "reference": "export-job-2026-001" }Créez la référence depuis l’identifiant durable de votre opération, avant le premier appel. Réutilisez-la après un timeout : la même organisation, référence et les mêmes termes facturables renvoient le même événement sans redébit, même pour des requêtes concurrentes. Une référence réutilisée avec une action, un service ou un coût différent renvoie 409.
L’acteur et les métadonnées du premier événement sont conservés lors d’une reprise. Sans reference, chaque appel est une nouvelle consommation : les anciens clients restent compatibles, mais ne bénéficient pas de cette garantie de reprise.
HTTP 402
{
"code": "insufficient_credits",
"message": "Not enough credits for this action",
"required": 1,
"available": 0,
"missing": 1
}Sur 402, n’exécutez pas l’action payante et proposez une recharge. Pour un traitement externe, conservez dans votre application une opération durable avec la même référence : le débit idempotent ne rend pas automatiquement idempotent votre export, votre worker ou un autre fournisseur.
POST /product/packs/<active pack code>/checkout
Content-Type: application/json
x-clavis-product-key: <server-side product key>
{
"organizationId": "<organization UUID>",
"quantity": 1,
"successUrl": "https://app.example.com/credits/success",
"cancelUrl": "https://app.example.com/credits"
}Listez les packs disponibles avec GET /product/packs. Après confirmation du paiement, sayAllow crédite le compte ; relisez le solde puis reprenez l’opération refusée. Un 402 n’a pas consommé sa référence. Ne créditez pas le compte depuis la page de retour du paiement.
L’usage facturé après consommation
Déclarez l’usage mesuré séparément.
Sur une souscription payante, configurez d’abord le compteur et son prix dans la console. Cette opération enregistre une quantité entière positive pour le compteur de facturation ; elle ne débite pas le solde prépayé et ne bloque pas automatiquement à un quota de plan.
POST /product/organizations/<organization UUID>/usage/metered
Content-Type: application/json
x-clavis-product-key: <server-side product key>
{
"metricKey": "api_calls",
"value": 3,
"reference": "request-2026-001"
}La référence est obligatoire. Le même compteur, la même référence et la même valeur retrouvent l’événement ; une autre valeur renvoie 409. Un plan Free est refusé sur ce parcours. Pour une limite bloquante dans l’exemple ci-dessous, nous utilisons le solde de crédits.
pending et sending indiquent une transmission en cours ; submitted indique que le fournisseur a accepté l’événement pour traitement asynchrone. blocked demande une vérification de configuration. La facture Stripe finale reste à rapprocher : submitted ne prouve pas à lui seul le montant facturé.
Le changement d’offre
Gardez Free jusqu’à la confirmation.
Créez un Checkout pour le plan payant avec la même organizationId. Tant que l’activation payante n’est pas confirmée, la souscription Free reste courante et une fonctionnalité réservée à l’offre payante, comme export:batch, reste refusée. Une reprise du même Checkout conserve l’intention d’upgrade.
Après le callback ou le retour du client, relisez les souscriptions puis le droit effectif. Le transfert confirmé doit remplacer Free et accorder la fonctionnalité payante. Un état pending reste en attente ; une URL de succès ne remplace jamais cette confirmation.
Changer de plan ne recharge pas automatiquement les crédits. Une recharge est un achat de pack distinct. Le scénario vérifie volontairement que le solde épuisé reste à zéro après l’upgrade : changer d’offre et acheter des crédits sont deux opérations différentes.
Le parcours exécutable
Rejouez le scénario avec votre produit de test.
Ce script Node 22 n’installe aucun SDK. Il appelle la vraie API depuis votre machine ou votre backend, conserve les identifiants de reprise dans un fichier local et ne stocke ni clé produit ni clé de licence. Il crée une organisation dédiée au test.
- Dans la console, créez demo-free (type Free) et demo-pro (payant), avec des limites de sièges compatibles. Associez le plan payant au prix Stripe de test et au cycle choisis.
- Définissez export:pdf parmi les fonctionnalités des deux plans ; ajoutez export:batch uniquement à demo-pro. Créez ces droits avant la souscription : modifier ensuite le plan ne réécrit pas les licences déjà émises.
- Utilisez la clé de ce produit et l’URL de son environnement de test. Ajoutez SAYALLOW_APIM_SUBSCRIPTION_KEY si votre gateway la demande. Aucun accès à la base ni à Kubernetes n’est nécessaire pour exécuter ce script.
curl --fail --output access-journey.mjs https://sayallow.com/examples/access-journey.mjs
export SAYALLOW_URL="<API base URL including gateway prefix>"
export SAYALLOW_PRODUCT_KEY="<test product key>"
node access-journey.mjs start --state /tmp/sayallow-journey.jsonLe script affiche organizationId. Dans Clients, ouvrez cette organisation puis ajustez son solde de +3 crédits avec une note d’essai. C’est une attribution de test par un opérateur, distincte d’un paiement. Relancez ensuite le script avec le même fichier d’état.
node access-journey.mjs credits --state /tmp/sayallow-journey.jsonLe résultat attend un seul débit au rejeu, un 409 si la référence change de coût, un solde final de zéro et un 402 sans découvert sur la consommation suivante. Le script conserve ses références après une interruption.
node access-journey.mjs upgrade --state /tmp/sayallow-journey.json --success-url https://app.example.com/billing/success --cancel-url https://app.example.com/billing
# After the provider confirms the test payment:
node access-journey.mjs verify --state /tmp/sayallow-journey.jsonRemplacez les URLs de retour par les origines autorisées de votre application. Ouvrez checkoutUrl et terminez le paiement de test chez le fournisseur. verify ne réussit qu’après activation effective, avec export:batch accordé et Free remplacé. Les crédits restent séparés.
Les clés de plan et de fonctionnalité sont modifiables avec --free-plan, --paid-plan, --capability et --paid-capability. Le résultat mesure le temps de ce parcours depuis start, pas la préparation de votre compte ni un délai d’intégration garanti.
La synchronisation
Recevez les événements. Relisez la vérité.
Configurez dans la console l’URL de callback de votre backend et son secret de signature. sayAllow transmet notamment subscription.updated et subscription.deleted après les événements du fournisseur de paiement.
- Vérifiez X-Clavis-Signature sur les octets bruts du corps avec votre secret de callback, avant de traiter le JSON.
- Rendez le traitement idempotent sur event.id et ne supposez pas que les callbacks arrivent dans l’ordre.
- Stockez l’événement et répondez rapidement en 2xx. Une livraison échouée peut être réessayée.
- Relisez GET /product/organizations/{id}/subscriptions au retour du Checkout et après un événement. Un statut pending ne doit pas ouvrir de droits payants.
Pour permettre au client de gérer sa facturation, créez une session avec POST /product/billing-portal en fournissant organizationId et returnUrl, puis redirigez-le vers l’URL reçue.
Prêt à configurer votre premier produit ?
La console rassemble le catalogue, les organisations et leur facturation.
Ouvrir la consoleUne question d’intégration ?