Données de la boutique pour le bot

Le bot de l'IA dans le chat peut répondre non seulement à partir de la base de connaissances, mais aussi avec les données en direct de la boutique : où en est la commande, quel est le numéro de suivi, le produit est-il en stock, combien coûte la livraison, comment retourner un achat. Et si vous l'autorisez, il peut annuler une commande non payée ou transmettre à la boutique une demande de retour ou de modification de la livraison. Pour cela, la boutique se connecte au bot via le protocole MCP (Model Context Protocol) : le bot appelle les outils de la boutique, qui lui répond avec ses données.

La boutique peut se connecter avec n'importe quel forfait, mais le bot, comme toute l'IA du chat, fonctionne avec un forfait payant : les réponses utilisant les données de la boutique se paient comme les autres réponses de l'IA, sur le solde du projet : voir Paiement.

Connexion

Le plus simple est de passer par notre module pour la boutique. Le module démarre lui-même le serveur et le connecte au projet à l'enregistrement des réglages :

La clé secrète du module doit disposer de l'autorisation « Connexion du serveur MCP de la boutique au bot IA » (chats.manage). Les autorisations d'une clé ne peuvent pas être modifiées après sa création : si la clé du module ne l'a pas, créez dans la section Clés API une nouvelle clé avec les mêmes autorisations plus celle-ci et indiquez-la dans les réglages du module. Les sites d'un même projet ne se connectent qu'une fois.

Une boutique sur mesure en PHP ou Laravel se connecte avec le serveur prêt à l'emploi de la bibliothèque PHP et du paquet Laravel : il ne reste au développeur qu'à écrire les gestionnaires des outils. Tout autre serveur qui respecte le contrat MCP de la boutique se connecte manuellement : dans Chats → Réglages du chat → Bot → Boutique (MCP), indiquez l'adresse https://…, la clé d'accès émise par la boutique et un nom. Le contrat, avec la description des outils, des erreurs et de la vérification du client, figure dans la section Pour les développeurs.

La section Boutique (MCP) indique si le serveur fonctionne et quels outils la boutique a autorisés pour le bot. L'interrupteur désactive temporairement le serveur ; le bouton d'actualisation le vérifie de nouveau et relit les outils (la plateforme le fait aussi d'elle-même une fois par jour).

Ce que le bot peut faire

C'est la boutique qui décide de ce qui est autorisé au bot, dans les réglages du module. Par défaut, seule la lecture est activée :

Les actions restent désactivées tant que la boutique ne les autorise pas :

Les descriptions des outils destinées au modèle sont fixées par la plateforme, et non par la boutique, et le bot traite les réponses de la boutique comme des données, jamais comme des instructions. Si la réponse du bot contient des prix, des délais ou des promesses absents des données de la boutique, le contrôle de la réponse ne la laisse pas partir vers le client.

Vérification du client

Les commandes et les actions sur celles-ci ne sont accessibles qu'à un client vérifié : le bot ne montrera pas la commande de quelqu'un d'autre et ne confirmera même pas qu'elle existe. Le client peut être vérifié de deux façons :

1. Connexion sur le site. Si le client est connecté à son compte de la boutique, le module transmet au widget du chat un jeton signé : le bot sait tout de suite qui écrit.
2. Code. Dans les messageries et pour les visiteurs non connectés, le bot demande l'e-mail indiqué dans la boutique ; la boutique y envoie un code à 6 chiffres, que le client saisit dans le chat. Le code est valable 10 minutes, avec au plus 5 codes par heure pour une même adresse.

La vérification reste valable 24 heures. L'opérateur la voit dans la fenêtre de la conversation : « client confirmé : connecté sur le site » ou « client confirmé par un code ». Le jeton du client est conservé chiffré dans la conversation ; ni le modèle ni les opérateurs ne le voient.

Actions dans la boutique

Le bot n'effectue une action qu'après l'accord explicite du client :

1. Le bot décrit ce qu'il va faire (numéro de commande, articles) et demande confirmation.
2. Le client donne son accord dans le chat, par exemple « oui, annulez ».
3. Un modèle d'évaluation distinct vérifie que le client a bien accepté cette action précise. Une question, un doute ou une autre demande ne valent pas accord.
4. La boutique effectue l'action ; un nouvel appel de la même action ne la répète pas.

Dans les échanges apparaît la ligne « Le bot a effectué dans la boutique : … » avec le résultat, et dans le journal d'audit du projet, l'entrée « Action du bot dans la boutique ». Le brouillon de l'opérateur n'utilise les données de la boutique qu'en lecture : les actions, l'opérateur les effectue lui-même dans la boutique.

Pour les développeurs

Votre propre serveur peut être connecté s'il respecte la version 1 du contrat MCP de la boutique. Pour PHP et Laravel, le contrat est déjà implémenté : la classe StoreMcp\Server de la bibliothèque PHP et la route POST /onetrace/mcp du paquet Laravel ; il ne reste qu'à écrire les gestionnaires des outils.

Transport. MCP Streamable HTTP, version du protocole 2025-06-18 : une seule adresse, des requêtes POST en JSON-RPC 2.0, une réponse en JSON ou un flux text/event-stream contenant une seule réponse. L'adresse est uniquement en https:// sur une IP publique, sans redirection. La réponse doit arriver en 10 secondes au plus et ne pas dépasser 256 Ko. La plateforme appelle initialize, notifications/initialized, tools/list et tools/call ; l'en-tête Mcp-Session-Id est pris en charge, mais pas obligatoire.

Accès. Chaque requête porte Authorization: Bearer <clé> ; la clé est créée par la boutique et compte au moins 32 caractères aléatoires. Une requête sans clé ou avec une autre clé reçoit la réponse 401.

Marqueur du contrat. Dans la réponse à initialize, le serveur déclare capabilities.experimental["onetrace/store"] = { "version": 1 } ; sans ce marqueur, le serveur n'est pas connecté.

Outils. Les noms sont exactement ceux du tableau ; tools/list ne renvoie que ceux autorisés par le propriétaire. Chacun porte l'annotation readOnlyHint: true (lecture) ou destructiveHint: true (action) et _meta["onetrace/auth"] : customer exige un client vérifié, none non. Le résultat est structuredContent, avec le même JSON sous forme de texte dans content[0].text. Les montants sont au format { "amount": 1250.5, "currency": "RUB" }, les dates en ISO 8601.

Le statut de commande est l'une des valeurs pending, processing, on_hold, shipped, delivered, completed, cancelled, refunded, failed. Pour la commande d'un autre client, la réponse est not_found, comme si elle n'existait pas.

Client. Le jeton customer_token est émis et vérifié par la boutique, pour une durée de 24 heures au plus. La boutique envoie elle-même le code de confirmation et répond de la même façon que le client existe ou non ; le code compte 6 chiffres, vaut 10 minutes, avec 5 tentatives au plus et 5 codes par heure au plus pour une même adresse. Pour un client connecté, la page transmet le jeton au traceur : cdp.chatCustomer('…').

Contexte de l'appel dans params._meta : onetrace/customer_token, onetrace/language (langue de la conversation), onetrace/conversation, et pour les actions onetrace/confirmed: true et onetrace/idempotency_key. Le serveur refuse une action sans onetrace/confirmed ; une répétition avec la même clé d'idempotence renvoie le même résultat sans refaire l'action.

Erreurs : isError: true et structuredContent: { "error": "<code>", "message": "<texte pour le client>" } :

Connexion depuis un module. Le module enregistre son serveur avec une clé secrète disposant de l'autorisation chats.manage : PUT /api/v1/chat/store-mcp avec url, key, name, platform connecte ou met à jour le serveur, DELETE /api/v1/chat/store-mcp avec url le déconnecte.