Guide d’intégration
Du catalogue aux droits d’accès.
Du brouillon commercial à une offre active, puis du Checkout confirmé aux droits de votre produit. Les parcours Free, crédits et Plans historiques restent expliqués séparément. 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, enregistrez votre application dans Products, puis configurez ses Plans sources dans Catalog. Un Plan Free permet une activation directe. Un Plan payant à prix fixe peut être copié dans le brouillon indépendant d’une offre commerciale. Votre application lit les conditions depuis l’API.
Dans Payments, configurez le compte Stripe du tenant et associez le Plan payant à un prix compatible. 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.
Préparer, publier, activer
Une offre possède son propre brouillon.
Une application peut proposer plusieurs offres commerciales, chacune avec un code stable et son historique. Le Plan sert de point de départ ; une fois copié, le brouillon appartient à l’offre. Le modifier ne change ni le Plan partagé, ni les révisions publiées, ni les engagements déjà acceptés.
- Dans la console, ouvrez Products, votre application, puis Manage offers. Créez une offre avec un nom et un code unique pour cette application.
- Avec Prepare a revision, copiez un Plan payant à prix fixe dans le brouillon. Configurez ses droits, quotas, sièges, essai et grâce, puis utilisez Save draft. Le prix, la devise, le cycle et la référence de prix viennent de la copie initiale du Plan.
- Prévisualisez les conditions enregistrées, puis publiez la version. La publication vérifie atomiquement la version du brouillon ; une modification concurrente renvoie 409. La console conserve vos éditions locales et demande un rechargement explicite.
- Activez ensuite la révision voulue. Publier ne l’active pas : une seule version peut être active par offre. Désactivez une version active avant de la retirer ; le retrait est irréversible et conserve l’historique.
Administrateurs et membres du tenant peuvent gérer les offres ; les lecteurs peuvent consulter l’historique. L’enregistrement d’une application et la gestion de ses clés serveur restent réservés aux administrateurs. La session Hanko et le tenant sélectionné déterminent les permissions. Une offre publiée mais inactive n’est pas proposée aux nouvelles souscriptions.
Ouvrir les applications dans la console (EN)
Ce parcours CommercialOffer prend en charge le prix fixe, les droits, les quotas, les sièges autorisés, l’essai récurrent et la grâce. Il ne prend pas en charge les prix par siège supplémentaires, les coupons, la facturation mesurée ou un essai sur un achat ponctuel. Les Plans historiques, les compteurs et les packs de crédits gardent leurs parcours séparés.
L’acceptation d’avenants contractuels, l’extension de ce profil aux autres modèles tarifaires et les méthodes SDK dédiées à offerCode restent des évolutions futures. Elles ne sont pas présentées ici comme disponibles.
L’intégration serveur
Résolvez les offres actives par leur code.
Depuis le backend de votre application, listez GET /product/offers ou résolvez GET /product/offers/{code}. La réponse expose code, name, version et terms : prix, devise, cycle, droits, quotas et politiques publiées. Elle ne nécessite ni identifiant de révision codé dans votre application, ni clé Admin.
curl "$SAYALLOW_URL/product/offers" \
-H "x-clavis-product-key: $SAYALLOW_PRODUCT_KEY"
# Resolve one active offer by its stable code:
curl "$SAYALLOW_URL/product/offers/professional" \
-H "x-clavis-product-key: $SAYALLOW_PRODUCT_KEY"Seules les offres ayant une révision active et non retirée sont listées. Un code sans version active renvoie 404 : affichez une indisponibilité et rechargez les offres, plutôt que de choisir un autre tarif silencieusement. La clé produit limite les réponses à son application et à son tenant.
Pour démarrer le Checkout ci-dessous, envoyez offerCode. sayAllow résout la version active et fige ses conditions dans un engagement persistant. Une activation ultérieure ne réécrit pas ce Checkout ; le fournisseur doit confirmer le paiement ou l’essai autorisé avant tout droit payant.
Les exemples de ce parcours utilisent HTTP directement. Les SDK existants conservent leurs méthodes historiques ; ne supposez pas qu’ils exposent déjà ces nouvelles opérations.
Créer le Checkout avec offerCodeLe 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.
Le démarrage du parcours
Activez Free ou ouvrez le Checkout d’une offre.
Plan Free : activation directe
Un Plan 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 active : Checkout hébergé par code
Choisissez un code renvoyé par GET /product/offers. Le backend transmet organizationId, offerCode et ses URLs de retour ; il ne fournit ni prix ni revisionId. La création 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>",
"offerCode": "professional",
"successUrl": "https://app.example.com/billing/success",
"cancelUrl": "https://app.example.com/billing"
}Compatibilité : le parcours historique POST /product/checkout avec planId reste disponible. Il ne remplace pas le parcours offerCode ci-dessus et ne garantit pas les mêmes conditions commerciales immuables.
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. Les Plans Free et les engagements CommercialOffer à prix fixe sont refusés sur ce parcours. Utilisez la configuration de compteurs des Plans historiques. 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 l’offre payante active avec offerCode et la même organizationId. Le scénario exécutable plus bas conserve le sélecteur historique planId. 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 historique par Plan avec votre produit de test.
Ce script démontre le parcours historique Free → planId et les crédits. Pour les offres commerciales versionnées, suivez le parcours HTTP offerCode présenté plus haut ; les méthodes SDK correspondantes ne sont pas encore disponibles.
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. Le parcours historique planId peut encore relire des politiques du Plan ; utilisez les offres publiées décrites plus haut pour figer les conditions acceptées.
- 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 les factures, moyens de paiement et opérations autorisées, créez une session POST /product/billing-portal avec organizationId et returnUrl. Pour un engagement offerCode, un changement de prix ou de Plan exige une nouvelle décision contractuelle ; cette acceptation d’avenant n’est pas encore disponible.
Prêt à configurer votre premier produit ?
La console rassemble le catalogue, les organisations et leur facturation.
Ouvrir la console (EN)Une question d’intégration ?