Bookivox Documentation

À 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

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

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.

Coller la clé

Dans Intégrations → Stripe, collez la clé dans le champ Clé secrète.

Cocher les actions

Sélectionnez les actions utiles. Chacune devient un outil indépendant.

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.

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 :

{
  "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

Bookivox crée une credential de type bearer_token : la clé part dans l’en-tête Authorization: Bearer <clé>.
L’URL de base est figée sur https://api.stripe.com : aucun segment de chemin n’est construit depuis le modèle.
Les sept actions sont des GET : les filtres partent en query params, jamais dans un corps de requête.
Chaque action cochée devient un outil http_api avec config.provider = "stripe", config.operation et un timeout de 10 000 ms.

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.

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_`.

Intégrations

Toutes les intégrations et les catégories d’outils.

API HTTP

Comprendre les outils HTTP : paramètres, presets, credentials.

Prise en main

LABS

Construire

Préparer

Piloter

Revendeur (White-label)

Intégration : Stripe

À quoi ça sert

Ce qu’il faut préparer

Connecter Stripe

Ce que l’agent peut faire

Cas d’usage

Comment ça marche

Rédiger la description de l’outil

Sécurité

Ce qui est déconseillé

Limites et dépannage

Intégrations

API HTTP

​À quoi ça sert

​Ce qu’il faut préparer

​Connecter Stripe

​Ce que l’agent peut faire

​Cas d’usage

​Comment ça marche

​Rédiger la description de l’outil

​Sécurité

​Ce qui est déconseillé

​Limites et dépannage

Intégrations

API HTTP

À quoi ça sert

Ce qu’il faut préparer

Connecter Stripe

Ce que l’agent peut faire

Cas d’usage

Comment ça marche

Rédiger la description de l’outil

Sécurité

Ce qui est déconseillé

Limites et dépannage