> ## Documentation Index > Fetch the complete documentation index at: https://docs.bookivox.com/llms.txt > Use this file to discover all available pages before exploring further. # Intégration : Stripe > Connectez votre compte Stripe à Bookivox pour consulter clients, factures, paiements et abonnements pendant l'appel. ## À quoi ça sert L'intégration **Stripe** permet à vos agents de **consulter votre compte Stripe** pendant l'appel : retrouver un client, vérifier une facture, lire le statut d'un paiement ou d'un abonnement. L'intégration est **en lecture seule** : elle ne crée, ne modifie et ne supprime rien. Elle répond aux questions du client sans jamais toucher à votre facturation. Comme pour les autres intégrations, vous branchez **votre compte** : Bookivox ne fournit ni identifiant, ni clé. ## Ce qu'il faut préparer | Élément | D'où il vient | Format attendu | | - | - | - | | **Clé secrète** | Stripe → Développeurs → Clés API | `sk_live_…`, `sk_test_…`, `rk_live_…` ou `rk_test_…` | | **Droits en lecture** | Réglages de la clé restreinte | Lecture sur Clients, Factures, Paiements, Abonnements, Produits | | **Compte Stripe actif** | Votre organisation | Un compte en règle, même sans mouvement récent | > [!NOTE] > > Préférez une **clé restreinte** (`rk_…`) : elle ne donne que les droits de > lecture listés ci-dessus. Une clé secrète standard (`sk_…`) fonctionne aussi, > mais ouvre plus de droits que nécessaire. ## Connecter Stripe **1. Créer la clé** Dans Stripe, ouvrez **Développeurs → Clés API → Créer une clé restreinte** et cochez la **lecture** sur Clients, Factures, Paiements, Abonnements et Produits. **2. Coller la clé** Dans **Intégrations → Stripe**, collez la clé dans le champ **Clé secrète**. **3. Cocher les actions** Sélectionnez les actions utiles. Chacune devient un **outil indépendant**. **4. Vérifier la connexion** Cliquez sur **Créer les outils**. Bookivox appelle `GET /v1/balance` : un bandeau **vert** confirme la connexion, une erreur est affichée sinon. Aucune donnée client n'est lue pendant ce test. **5. Attacher les outils** Rattachez les outils à un nœud agent. Ils s'exécutent **pendant l'appel**. ## Ce que l'agent peut faire | Action | Usage | Exemple de demande | | - | - | - | | **Lister les clients** (`list_customers`) | Retrouver un client par e-mail | « Quel est mon identifiant client ? » | | **Lister les factures** (`list_invoices`) | Montants, statuts, échéances | « Ma facture est-elle payée ? » | | **Lister les paiements** (`list_payment_intents`) | État des tentatives de paiement | « Mon paiement est-il passé ? » | | **Lister les abonnements** (`list_subscriptions`) | Contrats en cours et statuts | « Mon abonnement est-il actif ? » | | **Lister les débits** (`list_charges`) | Débits réels et montants | « Qu'avez-vous débité ce mois-ci ? » | | **Lister les produits** (`list_products`) | Catalogue et produits actifs | « Quels produits proposez-vous ? » | | **Lister les tarifs** (`list_prices`) | Montants, devises, périodicité | « Combien coûte la formule annuelle ? » | Chaque action accepte des **filtres facultatifs** qui partent en paramètres de requête, par exemple : ```json theme={null} { "customer": "cus_ABC123", "status": "open", "limit": 5 } ``` `limit` vaut 10 par défaut et 100 au maximum. `customer` et `status` ne sont renseignés que si l'agent les connaît. ## Cas d'usage | Cas d'usage | Ce que fait l'agent | Résultat pour le client | | - | - | - | | **Vérifier une facture** | L'agent liste les factures du client et lit le statut de la plus récente. | Le client sait immédiatement si sa facture est payée ou en attente. | | **Retrouver un abonnement** | L'agent liste les abonnements du client et donne la date de renouvellement. | Le client évite une résiliation ou un doublon. | | **Expliquer un échec de paiement** | L'agent lit les paiements en échec et leur motif. | Le client comprend quoi corriger sur sa carte. | | **Annoncer un tarif** | L'agent liste les tarifs actifs et donne le montant et la devise. | Le client obtient le prix exact, sans approximation. | ## Comment ça marche 1. Bookivox crée une **credential** de type `bearer_token` : la clé part dans l'en-tête `Authorization: Bearer `. 2. L'URL de base est figée sur `https://api.stripe.com` : aucun segment de chemin n'est construit depuis le modèle. 3. Les sept actions sont des **`GET`** : les filtres partent en **query params**, jamais dans un corps de requête. 4. Chaque action cochée devient un **outil `http_api`** avec `config.provider = "stripe"`, `config.operation` et un **timeout de 10 000 ms**. > [!WARNING] > > L'API Stripe n'accepte que du `application/x-www-form-urlencoded` pour les > écritures, alors que le moteur Bookivox envoie du **JSON**. C'est pourquoi cette > intégration ne propose **aucune création ni modification** : uniquement de la > lecture. ## Rédiger la description de l'outil ``` Utiliser cet outil uniquement quand le client demande l'état d'une facture, d'un paiement ou d'un abonnement. Lire le résultat et répondre avec le montant et le statut exacts, sans interpréter. ``` > [!WARNING] > > L'agent doit **lire** Stripe, jamais promettre une action de facturation. Si le > client demande un remboursement ou une résiliation, transférez l'appel. ## Sécurité | Risque | Ce que fait le preset | | - | - | | **Secrets exposés** | La clé vit dans une **credential** chiffrée, jamais dans un prompt. | | **Modification accidentelle** | Toutes les actions sont des `GET` : aucune écriture n'est possible. | | **Lecture de données client pendant le test** | La sonde `GET /v1/balance` ne lit que le solde du compte. | | **Détournement d'URL** | L'URL de base est figée sur le domaine Stripe. | | **Clé trop permissive** | Une **clé restreinte** en lecture seule suffit et est recommandée. | | **Erreur silencieuse** | La connexion est **testée avant validation** avec `GET /v1/balance`. | ## Ce qui est déconseillé | Usage | Pourquoi | | - | - | | **Clé secrète complète en production** | Une clé restreinte en lecture limite l'impact en cas de fuite. | | **Clé de test sur un compte réel** | `sk_test_` ne voit aucune donnée de production. | | **Créer un client ou une facture depuis l'appel** | Le preset est en lecture seule par conception. | | **Pagination complète** | Un outil d'agent traite **une** demande à la fois : gardez `limit` bas. | | **Tâches planifiées** | Un outil s'exécute **pendant l'appel**, pas en tâche de fond. | ## Limites et dépannage | Symptôme | Cause probable | Correction | | - | - | - | | Erreur `401` | Clé absente, révoquée ou mal recopiée. | Recréer la clé et la coller en entier, sans espace. | | Erreur `403` | La clé restreinte n'a pas le droit demandé. | Ajouter la lecture sur l'objet concerné. | | Erreur `429` | Trop de requêtes. | Espacer les appels ; Stripe applique ses propres quotas. | | Erreur `5xx` | Incident côté Stripe. | Réessayer plus tard. | | Résultat vide | Filtre trop restrictif ou mauvaise clé (`test` sur `live`). | Retirer les filtres, vérifier le mode de la clé. | | Le test de connexion échoue | La clé ne correspond pas au format attendu. | Elle doit commencer par `sk_live_`, `sk_test_`, `rk_live_` ou `rk_test_`. | > [card] [Intégrations](https://docs.bookivox.com/integrations/overview.md) > > Toutes les intégrations et les catégories d'outils. > [card] [API HTTP](https://docs.bookivox.com/integrations/http-api.md) > > Comprendre les outils HTTP : paramètres, presets, credentials. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.