L'endpoint POST /v1/billing/portal-link génère une URL de session Stripe Billing Portal associée au client Stripe du workspace courant. Une fois redirigé vers cette URL, l'utilisateur peut consulter ses factures PDF, mettre à jour sa carte bancaire ou résilier son abonnement, sans avoir à se réauthentifier auprès de Stripe. Le lien expire après quelques minutes : générez-le à la demande, ne le mettez pas en cache. Si le workspace n'a jamais souscrit d'abonnement payant (aucun stripe_customer_id), l'endpoint retourne une erreur not_found plutôt que de renvoyer une URL invalide.
/v1/billing/portal-linkCrée une session Stripe Billing Portal et retourne son URL de redirection./v1/billing/subscriptionRécupère le plan actuel, le statut et les identifiants Stripe du workspace (utile pour vérifier qu'un customer_id existe avant d'appeler portal-link).Authentification
Cet endpoint requiert une clé API avec le scope billing:read. Transmettez-la dans l'en-tête Authorization au format Bearer. Les clés de test commencent par cof_test_…, les clés de production par cof_live_…. Utilisez cof_sandbox_… dans les environnements d'intégration isolés.
Corps de la requête
Le corps est minimal : il sert surtout à préciser l'URL de retour après la session Stripe. Le tableau ci-dessous détaille les champs acceptés.
| Champ | Type | Requis | Description |
|---|---|---|---|
| return_url | string | Non | URL vers laquelle Stripe redirigera l'utilisateur après fermeture du portail. Doit commencer par https://. Par défaut : https://billing.coffrify.com?pane=inv. |
| flow | string | Non | Deep-link optionnel. Seule valeur acceptée : "payment_method". Ouvre directement l'écran de mise à jour du moyen de paiement dans le portail Stripe. Sans ce champ, le portail s'ouvre sur la page par défaut (liste des factures). |
Exemple d'appel
L'exemple ci-dessous crée une session de portail et récupère son URL de redirection. À exécuter côté serveur. Choisissez votre langage.
Réponse
En cas de succès, l'API retourne un objet JSON avec l'URL de session et l'identifiant Stripe du client.
| Champ | Type | Description |
|---|---|---|
url | string | URL de session Stripe Billing Portal. Valide quelques minutes seulement. Redirigez immédiatement l'utilisateur. |
customer_id | string | Identifiant Stripe du client (cus_…) associé au workspace. Utile pour des appels Stripe directs côté serveur. |
Erreurs
Les erreurs surviennent surtout quand le workspace n'a pas encore de client Stripe, ou quand le scope billing:read manque. Le tableau ci-dessous indique la résolution.
| Code HTTP | Code d'erreur | Quand | Résolution |
|---|---|---|---|
| 400 | validation_error | Le champ flow contient une valeur autre que "payment_method", ou return_url ne commence pas par https://. | Corrigez la valeur du champ incriminé. |
| 401 | invalid_api_key | La clé API est absente, malformée ou révoquée. | Vérifiez que vous transmettez bien Authorization: Bearer cof_live_… (ou cof_test_…). |
| 403 | scope_missing | La clé API ne possède pas le scope billing:read. | Créez ou mettez à jour une clé API avec le scope billing:read depuis la console Coffrify. |
| 404 | not_found | Le workspace n'a pas de stripe_customer_id : l'utilisateur n'a jamais souscrit d'abonnement payant. | Redirigez l'utilisateur vers POST /v1/billing/checkout-link pour initier un abonnement Pro ou Ultra. |
| 429 | rate_limited | Quota de requêtes par minute dépassé pour ce workspace. | Attendez la durée indiquée dans l'en-tête Retry-After avant de relancer. |
| 500 | internal_error | Stripe n'est pas configuré côté serveur (STRIPE_SECRET_KEY absente) ou la création de session a échoué. | Réessayez. Si l'erreur persiste, contactez le support Coffrify avec le request_id retourné. |
Bonnes pratiques
Voir aussi
- Générer un lien de paiement Stripe Checkout
- Consulter l'abonnement et le plan actuel
- Recommandation de plan selon l'usage
- Référence : Authentification et scopes
- Référence : Erreurs API
- Référence : Rate limiting