Risoluzione dei problemi tecnici

Primo passo in ogni caso: chiedi alla chat di eseguire ps_get_shop_info e ps_check_shop_health. Insieme riportano versioni, edizione e stato della licenza, le aree di scrittura (quali interruttori sono attivi e fino a quando), il livello dei dati dei clienti, i permessi mancanti del dipendente, i limiti orari residui e i moduli agganciati ai salvataggi. La scheda Registro delle connessioni (ultime 50) mostra ogni chiamata con IP, esito e ora.

Connessione

Il connettore non si collega da Claude o ChatGPT.

Controlla in quest'ordine:

1. L'indirizzo è https://your-shop.com/module/tellmyshop/mcp (con il login della chat senza token; con l'indirizzo con chiave del metodo precedente, con il token completo). L'endpoint rifiuta l'HTTP semplice (403).

2. Il connettore è attivo. Il passo 1 della scheda Inizio (Attiva il connettore) lo attiva; spento restituisce 503 «connector disabled».

3. «Verifica di nuovo la connessione» nel modulo funziona (token di prova, valido 2 minuti). Il test controlla anche il login della chat:

   • «L'hosting rimuove l'intestazione con il pass della chat (Authorization)»: il server o un proxy elimina l'intestazione Authorization. Chiedi all'hosting di inoltrarla. Se non è possibile, attiva Indirizzo con chiave (metodo precedente) in Chat collegate → Avanzate: come si collegano le chat e usa quell'indirizzo.
   • «La chat non troverà le impostazioni di login»: l'indirizzo /.well-known/ del negozio non risponde. Di solito aiuta attivare gli URL semplificati (Parametri Negozio → Traffico e SEO → URL semplificati). Se il negozio è in una sottocartella o l'hosting blocca gli indirizzi /.well-known/, usa l'indirizzo con chiave.

   Il test non rileva blocchi per paese o IP su un CDN; li mostra la prima vera chiamata della chat nel registro delle connessioni.

4. Niente davanti al negozio blocca i POST verso /module/tellmyshop/mcp: autenticazione di base, pagina di manutenzione, WAF, Cloudflare Bot Fight Mode o challenge gestite. Aggiungi una regola di esclusione solo per quel percorso.

5. L'elenco degli IP consentiti in Impostazioni: sicurezza, avvisi, limiti è vuoto, o contiene gli indirizzi della tua app di chat. Con ChatGPT lascialo vuoto: OpenAI non pubblica un elenco fisso di indirizzi. Per Claude la scheda delle impostazioni ha un pulsante che aggiunge gli indirizzi di Anthropic.

6. Negozio dietro Cloudflare o un altro proxy: attiva Negozio dietro proxy / Cloudflare e indica gli intervalli del proxy in Proxy fidati, altrimenti l'elenco IP vede l'IP del proxy.

7. In ChatGPT il negozio si aggiunge in Plugins come server MCP personalizzato con l'autenticazione OAuth.

403 Forbidden.

Cause probabili:

• Origin. Una richiesta con intestazione Origin è accettata solo da https://claude.ai, https://claude.com, https://chatgpt.com o https://chat.openai.com. Le richieste senza Origin passano. Uno strumento di test nel browser con un'altra Origin viene rifiutato.
• Elenco IP consentiti. L'IP non è nell'elenco.
• HTTP semplice.

503 Servizio non disponibile.

Il connettore è spento, oppure manca il dipendente del connettore (cancellato o reso SuperAdmin). Esegui di nuovo il passo 1 della scheda Inizio; crea l'account se manca.

429 Troppi tentativi falliti.

20 autenticazioni fallite da un IP in 10 minuti bloccano quell'IP finché la finestra non passa; il proprietario riceve un avviso. Causa tipica: un vecchio token ancora configurato nell'app di chat o in uno script di monitoraggio. Correggi il token, poi attendi 10 minuti.

401 dopo la rigenerazione di un token (indirizzo con chiave, metodo precedente).

Un nuovo token revoca subito quello vecchio. Aggiorna l'indirizzo con chiave in Claude o ChatGPT, o l'intestazione Authorization: Bearer nella configurazione di Claude Code / Claude Desktop.

Claude Code o Claude Desktop (locale) non si collega.

Con l'indirizzo con chiave (metodo precedente), usa --header "Authorization: Bearer <token>" invece di un token nell'URL. L'endpoint richiede HTTPS anche in locale (mkcert). Le richieste senza intestazione Origin passano. Se è impostato un elenco IP, aggiungi l'IP pubblico della macchina.

Errore di versione del protocollo.

Supportate: 2026-07-28, e 2025-11-25, 2025-06-18, 2025-03-26. Una versione non supportata restituisce 400 con l'elenco delle versioni accettate.

Il salvataggio non funziona

La chat legge e pianifica soltanto.

O la licenza non è attiva (Pro senza licenza attiva funziona come Free), oppure si tratta di TellMyShop Free, che non ha strumenti di scrittura. ps_get_shop_info dice quale (edizione audit o audit_free). Controlla la scheda Licenza e clicca Aggiorna.

«Writing in the … area is off. Nothing was saved.»

Vendite, Tema, Moduli e Manutenzione salvano solo mentre il loro interruttore è attivo nella scheda Salvataggio per area. Vendite resta attivo finché non lo spegni; Tema e Moduli per 24 ore; Manutenzione per 3 ore. Un interruttore che scade a metà conversazione smette subito di salvare. L'anteprima continua a funzionare, quindi la chat può mostrare il piano prima che tu attivi l'interruttore. Dalla 2.7.0 non esiste più un connettore di servizio separato: un solo indirizzo copre tutte le aree.

Tema, Moduli o Manutenzione non si attivano.

Attivarli richiede una conferma spuntata e un backup del database completato. In un negozio grande il backup avviene a parti: tieni la pagina aperta o clicca Completa il backup. Senza spazio libero su disco pari a circa il doppio del database, questi interruttori restano spenti; Contenuti, Catalogo e Vendite continuano a funzionare.

ps_restore_file_backup rifiutato.

Il ripristino richiede l'interruttore della zona del file: Tema per i file del tema, Moduli per i file dei moduli, Manutenzione per gli altri file del negozio. La scheda Backup dei file del pannello ripristina senza interruttore, con i permessi del dipendente stesso.

Lo strumento di assistenza clienti rifiuta.

ps_customer_service rifiuta finché il livello dei dati dei clienti è Disattivato. Imposta Pseudonimizzato o Accesso completo (temporaneo) nella scheda Dati dei clienti (GDPR).

Mancano gli strumenti del blog.

I 5 strumenti del blog vengono registrati solo quando viene rilevato SmartBlog. Altri moduli blog non sono supportati. ps_check_shop_health segnala «nessun blog» come informazione.

Limiti

Limite raggiunto.

Valori iniziali all'ora: 300 chiamate, 150 scritture, 20 scritture di file (intervalli 10–2000, 1–500, 1–200), impostati in Impostazioni: sicurezza, avvisi, limiti. Una scrittura con un gruppo fino a 50 elementi conta come una, e il limite di scrittura viene controllato prima del salvataggio, quindi un gruppo non si ferma mai a metà. Dividi i lavori grandi su più ore o alza i limiti per la durata del lavoro; ps_check_capacity verifica prima un lavoro pianificato.

Gruppo rifiutato con un errore di limite.

Limiti per chiamata, per esempio: ps_update_product_content 50, ps_update_category_content 20, ps_update_image_legends 100, ps_set_product_categories 200, ps_update_prices 100, ps_update_stock 100, ps_manage_combinations 100, ps_set_product_redirect 100, ps_translate_catalog_items 200, ps_manage_redirects 100, ps_db_query 200 righe, ps_db_execute 1000 righe salvate. Tabella completa: Specifica §11.1.

Scritture

change_token scaduto, già usato o non corrispondente.

Il token è un HMAC di strumento, argomenti e hash dello stato «prima», valido 30 minuti, monouso. Ripeti con argomenti identici o crea una nuova anteprima.

Esecuzione bloccata: i dati sono cambiati dopo l'anteprima.

Lo stato «prima» non corrisponde più, per esempio per una modifica nel back office, un'importazione o un modulo di feed. Crea una nuova anteprima.

Il risultato elenca modifiche fuori dall'anteprima.

La registrazione delle righe ha visto, durante la scrittura, righe modificate che l'anteprima non mostrava, di solito dall'hook di un altro modulo. La chat le mostra al proprietario e chiede cosa fare; non le ripristina da sola. Annullare l'operazione riporta tutte le righe registrate allo stato precedente.

Modifica del prezzo rifiutata.

ps_update_prices rifiuta il prezzo 0 e le variazioni oltre il 30% senza allow_big_change. ps_manage_specific_prices e ps_manage_catalog_price_rules richiedono allow_big_change oltre il 90% di sconto (avviso oltre il 50%). La chat imposta il flag solo dopo che il commerciante ha approvato una modifica di quella entità.

Regola carrello creata ma non attiva / impossibile da cancellare.

ps_manage_cart_rules crea le regole inattive per scelta; usa action=set_active. Non esiste un'azione di cancellazione; disattivala. Una regola senza codice richiede auto_apply.

Errore di validazione al salvataggio.

ObjectWriter valida ogni campo con le regole della classe (validateField, isCleanHtml, lunghezze). I nomi dei prodotti non possono contenere <>;=#{} e hanno un massimo di 128 caratteri. Il messaggio indica il campo.

Un altro modulo non reagisce alla modifica.

ObjectWriter chiama update(), che attiva actionObject<Class>Update* (e actionProductSave / actionProductUpdate per i prodotti). I moduli che ascoltano solo gli hook dei moduli del back office non vedono la modifica. ps_check_shop_health li elenca.

Permesso negato.

ExecutionContext::requirePermissions controlla il dipendente del connettore per scheda e azione. Dalla 2.7.0 il profilo creato dal passo 1 riceve i permessi di tutte le aree; se il profilo è stato modificato a mano, ps_get_shop_info elenca cosa manca. Su alcune versioni di PrestaShop i moduli ignorano i salvataggi di un dipendente senza il permesso di «visualizzare» i moduli; la scheda Inizio offre una correzione con un clic.

Annullamento rifiutato.

ps_revert_change non può annullare: la creazione di un tema figlio, l'installazione, l'aggiornamento o la disinstallazione di un modulo, DDL, immagini cancellate, un prodotto creato già presente in un ordine, cambi di URL (usa un nuovo ps_change_url), modifiche ai file (usa i backup dei file). Annullare una modifica di Vendite, Tema, Moduli o Manutenzione richiede quell'interruttore; la scheda Cronologia delle modifiche e annullamento può annullare qualsiasi cosa con i permessi del dipendente collegato. Le voci cifrate della cronologia richiedono il file della chiave.

URL

Cambio di URL bloccato.

ps_change_url rifiuta quando il reindirizzamento canonico è 302 (Parametri negozio > Traffico & SEO, imposta 301), la modalità sviluppatore è attiva (_PS_MODE_DEV_) o un modulo sovrascrive le rotte (UrlGuard; ps_check_shop_health lo nomina). I cambi di URL del blog richiedono «Reindirizzamenti 301 per il blog» attivo nelle impostazioni.

Reindirizzamento rifiutato da ps_manage_redirects.

L'anteprima accetta solo origini che oggi restituiscono 404 o 410 e destinazioni che restituiscono 200 sul dominio del negozio. Catene e cicli sono bloccati. Fino a 100 elementi per add, 100 ID per disable/enable; origine fino a 1.024 caratteri, URL di destinazione fino a 2.048. Non c'è cancellazione: usa disable, oppure annulla dalla cronologia delle modifiche.

File, tema e cache

Modifica non visibile dopo una scrittura nel tema.

Esegui ps_clear_cache (ambito smarty; all svuota anche la cache Symfony). Svuota separatamente i moduli di cache a pagina intera e la cache della CDN.

Errore di validazione Smarty.

Sono ammessi solo tag e modificatori in whitelist, poi una compilazione di prova; {php}, {include_php} e l'accesso statico alle classi vengono rifiutati. Non è stato salvato nulla.

«search must appear exactly once».

Usa un frammento più lungo o scrivi l'intero file con content.

Accesso al file negato.

I percorsi devono essere relativi, senza .., risolversi dentro la zona (realpath) e avere un'estensione di testo. Sempre negati: parameters.php/yml, settings.inc.php, .env*, chiavi e certificati, dump SQL, archivi e .bak, .git, var/logs, upload, download, la directory privata del modulo e il modulo stesso.

Scrittura di un file PHP rifiutata.

Il controllo della sintassi (token_get_all(TOKEN_PARSE)) ha trovato un errore di parsing. Gli errori di esecuzione (per esempio una funzione non definita) non vengono rilevati: per questo ogni scrittura PHP ha un backup ed esiste la chiave di emergenza.

Ripristino dopo una modifica che rompe il negozio.

ps_list_file_backups, poi ps_restore_file_backup (prima salva la versione attuale), poi ps_clear_cache. Se il back office non funziona: apri l'indirizzo di emergenza e inserisci la chiave di emergenza; ripristina i file modificati dal connettore e spegne Manutenzione, ma non tocca il database. Per il database usa i backup del database del modulo (scheda Salvataggio per area, Scarica, poi importa con i tuoi strumenti abituali).

SQL (Manutenzione)

Query rifiutata.

Una sola istruzione, senza commenti che nascondono contenuto. Mai accessibili: tabelle di dipendenti, sessioni, accessi e profili, configuration (usa ps_config), tabelle del webservice e delle API, tabelle del connettore. Mai modificabili: imposte, collegamenti dei moduli di pagamento, ordini, stati, pagamenti, fatture. Operazioni su file e utenti MySQL bloccate. Tabelle con dati personali solo al livello dei dati dei clienti pseudo (mascherato) o full.

ps_db_execute annullato (rollback).

Sono cambiate più righe di quelle dichiarate, oppure servirebbe il backup di più di 1000 righe. Restringi il WHERE o dividi la modifica.

Cosa è cambiato dalla 2.6

Segnalare un problema

Invia a [email protected]: dominio, versioni di PrestaShop e PHP, versione del modulo, pacchetto (Pro o Free), app di chat (Claude o ChatGPT), nome dello strumento, testo esatto dell'errore, ora. Invia solo il prefisso del token, mai il token completo.

---

PrestaShop è un marchio registrato di PrestaShop SA. Claude è un marchio di Anthropic. ChatGPT è un marchio di OpenAI. TellMyShop non è affiliato a nessuna di queste società.