Dati del negozio per il bot

Il bot dell'IA nella chat può rispondere non solo in base alla base di conoscenza, ma anche con i dati del negozio in tempo reale: a che punto è l'ordine, qual è il numero di tracciamento, se un prodotto è disponibile, quanto costa la consegna, come restituire un acquisto. E, se lo consente, può annullare un ordine non pagato o inoltrare al negozio una richiesta di reso o di modifica della consegna. Per farlo, il negozio si collega al bot tramite il protocollo MCP (Model Context Protocol): il bot richiama gli strumenti del negozio e il negozio risponde con i dati.

Il negozio si può collegare con qualsiasi piano, mentre il bot, come tutta l'IA nella chat, funziona con un piano a pagamento: le risposte con i dati del negozio si pagano come le normali risposte dell'IA, dal saldo del progetto, vedi Pagamento.

Collegamento

Il modo più semplice è usare il nostro modulo per il negozio. Il modulo avvia da solo il server e lo collega al progetto quando si salvano le impostazioni:

La chiave segreta del modulo deve avere il permesso «Collegamento del server MCP del negozio al bot IA» (chats.manage). I permessi di una chiave non si possono modificare dopo la creazione: se la chiave del modulo non lo ha, crei nella sezione Chiavi API una nuova chiave con gli stessi permessi più questo e la indichi nelle impostazioni del modulo. I siti di uno stesso progetto si collegano una sola volta.

Un negozio proprio in PHP o Laravel si collega con il server pronto della libreria PHP e del pacchetto Laravel: allo sviluppatore resta solo da scrivere i gestori degli strumenti. Qualsiasi altro server che rispetta il contratto MCP del negozio si collega manualmente: in Chat → Impostazioni chat → Bot → Negozio (MCP) indichi l'indirizzo https://…, la chiave di accesso emessa dal negozio e un nome. Il contratto, con la descrizione di strumenti, errori e verifica del cliente, è nella sezione Per gli sviluppatori.

Nella sezione Negozio (MCP) si vede se il server funziona e quali strumenti il negozio ha consentito al bot. L'interruttore disattiva temporaneamente il server, il pulsante di aggiornamento lo verifica di nuovo e rilegge gli strumenti (la piattaforma lo fa anche da sola una volta al giorno).

Cosa può fare il bot

Cosa è consentito al bot lo decide il negozio, nelle impostazioni del modulo. Per impostazione predefinita è attiva solo la lettura:

Le azioni restano disattivate finché il negozio non le consente:

Le descrizioni degli strumenti per il modello le stabilisce la piattaforma, non il negozio, e il bot tratta le risposte del negozio come dati, non come istruzioni. Se la risposta del bot contiene prezzi, tempi o promesse che non compaiono nei dati del negozio, il controllo della risposta non la lascia arrivare al cliente.

Verifica del cliente

Gli ordini e le azioni su di essi sono disponibili solo per un cliente verificato: il bot non mostrerà l'ordine di un altro e non confermerà nemmeno che esiste. Il cliente si può verificare in due modi:

1. Accesso al sito. Se il cliente ha effettuato l'accesso al proprio account del negozio, il modulo passa al widget della chat un token firmato: il bot sa subito chi sta scrivendo.
2. Codice. Nelle app di messaggistica e per gli ospiti il bot chiede l'email indicata nel negozio, il negozio vi invia un codice di 6 cifre e il cliente lo scrive in chat. Il codice vale 10 minuti, con al massimo 5 codici all'ora per lo stesso indirizzo.

La verifica vale 24 ore. L'operatore la vede nella finestra della conversazione: «cliente confermato: ha effettuato l’accesso al sito» oppure «cliente confermato con un codice». Il token del cliente è conservato cifrato nella conversazione: né il modello né gli operatori lo vedono.

Azioni nel negozio

Il bot esegue un'azione solo dopo il consenso esplicito del cliente:

1. Il bot descrive cosa farà (numero dell'ordine, articoli) e chiede conferma.
2. Il cliente acconsente in chat, ad esempio «sì, annulli pure».
3. Un modello di valutazione a parte verifica che il cliente abbia acconsentito proprio a quell'azione. Una domanda, un dubbio o un'altra richiesta non sono un consenso.
4. Il negozio esegue l'azione; una nuova chiamata della stessa azione non la ripete.

Nei messaggi compare la riga «Il bot ha eseguito nel negozio: …» con il risultato e, nel registro attività del progetto, la voce «Azione del bot nel negozio». La bozza dell'operatore usa i dati del negozio solo in lettura: le azioni le esegue l'operatore stesso, nel negozio.

Per gli sviluppatori

Si può collegare un server proprio, se rispetta la versione 1 del contratto MCP del negozio. Per PHP e Laravel il contratto è già implementato: la classe StoreMcp\Server della libreria PHP e la rotta POST /onetrace/mcp del pacchetto Laravel; resta solo da scrivere i gestori degli strumenti.

Trasporto. MCP Streamable HTTP, versione del protocollo 2025-06-18: un solo indirizzo, richieste POST con JSON-RPC 2.0, risposta in JSON oppure come flusso text/event-stream con una sola risposta. L'indirizzo è solo https:// su un IP pubblico, senza reindirizzamenti. La risposta deve arrivare entro 10 secondi e non superare 256 KB. La piattaforma chiama initialize, notifications/initialized, tools/list e tools/call; l'intestazione Mcp-Session-Id è supportata, ma non obbligatoria.

Accesso. Ogni richiesta contiene Authorization: Bearer <chiave>; la chiave la crea il negozio ed è lunga almeno 32 caratteri casuali. A una richiesta senza chiave o con una chiave diversa si risponde 401.

Contrassegno del contratto. Nella risposta a initialize il server dichiara capabilities.experimental["onetrace/store"] = { "version": 1 }: senza questo contrassegno il server non viene collegato.

Strumenti. I nomi sono esattamente quelli della tabella; tools/list restituisce solo quelli consentiti dal titolare. Ognuno ha l'annotazione readOnlyHint: true (lettura) o destructiveHint: true (azione) e _meta["onetrace/auth"]: customer richiede un cliente verificato, none no. Il risultato è structuredContent, con lo stesso JSON come testo in content[0].text. Gli importi hanno la forma { "amount": 1250.5, "currency": "RUB" }, le date sono in ISO 8601.

Lo stato dell'ordine è uno tra pending, processing, on_hold, shipped, delivered, completed, cancelled, refunded, failed. Per l'ordine di un altro cliente la risposta è not_found, come se non esistesse.

Cliente. Il token customer_token lo emette e lo verifica il negozio, con una durata massima di 24 ore. Il codice di conferma lo invia il negozio stesso, che risponde allo stesso modo sia che il cliente esista sia che non esista; il codice ha 6 cifre, vale 10 minuti, con al massimo 5 tentativi e 5 codici all'ora per indirizzo. Per un cliente che ha effettuato l'accesso, la pagina passa il token al tracker: cdp.chatCustomer('…').

Contesto della chiamata in params._meta: onetrace/customer_token, onetrace/language (lingua della conversazione), onetrace/conversation e, per le azioni, onetrace/confirmed: true e onetrace/idempotency_key. Il server rifiuta un'azione senza onetrace/confirmed; una ripetizione con la stessa chiave di idempotenza restituisce lo stesso risultato senza ripetere l'azione.

Errori: isError: true e structuredContent: { "error": "<codice>", "message": "<testo per il cliente>" }:

Collegamento dal modulo. Il modulo registra il proprio server con una chiave segreta con il permesso chats.manage: PUT /api/v1/chat/store-mcp con url, key, name, platform collega o aggiorna il server, DELETE /api/v1/chat/store-mcp con url lo scollega.