Billing gère les abonnements, les paliers, les add-ons, les promotions et — surtout — les droits (entitlements) qui pilotent le gating de tous les modules. Il s'intègre à Stripe (checkout, portail, webhooks).
- Base URL — prod :
https://billing.puwapi.com· dev :http://localhost:5300 - Auth : JWT (souvent réservé aux rôles admin/owner).
Abonnement¶
Base : /api/subscription
| Méthode | Route | Rôle |
|---|---|---|
| GET | /api/subscription | Abonnement de l'organisation |
| POST | /api/subscription/change-plan | Changer de palier |
| POST | /api/subscription/start-trial | Démarrer l'essai gratuit |
| PUT | /api/subscription/trial-modules | Choisir les modules de l'essai |
| PUT | /api/subscription/{tenantId} | (admin) Modifier l'abonnement d'un tenant |
Droits (entitlements)¶
Base : /api/entitlements
| Méthode | Route | Rôle |
|---|---|---|
| GET | /api/entitlements | Droits (vue admin) |
| GET | /api/entitlements/me | Droits de mon organisation (consommé par le gating) |
| PUT | /api/entitlements/{tier} | (admin) Définir les droits d'un palier |
GET /api/entitlements/me est la réponse mise en cache dans Redis
(billing:entitlements:{tenantId}, TTL 5 min) et lue par chaque module pour son gating.
Voir Gating par module.
Plans, add-ons, promos¶
| Base | Méthodes | Rôle |
|---|---|---|
/api/plans | GET, PUT {tier}, GET /stripe-status | Catalogue des paliers |
/api/addons | GET, GET /all, POST, PUT {moduleKey}, DELETE {moduleKey} | Modules en add-on |
/api/promo | GET {code}, GET, PUT, DELETE {id} | Codes promotionnels |
Checkout (Stripe)¶
Base : /api/checkout
| Méthode | Route | Rôle |
|---|---|---|
| POST | /api/checkout/session | Session de paiement hébergée |
| POST | /api/checkout/embedded-session | Session embarquée |
| POST | /api/checkout/portal | Portail client Stripe (gérer l'abonnement) |
Webhooks & interne¶
POST /api/webhooks/stripe— webhook Stripe ([AllowAnonymous], signé). Invalide le cache de droits à chaque changement.GET /internal/subscriptions/trialing— liste interne des essais en cours.
Toute mutation d'abonnement (essai, upgrade, add-on, webhook Stripe) invalide la clé Redis de droits, ce qui propage le changement à toute la suite en ≤ 15 s.