Risoluzione dei problemi tecnici: Correggere gli errori di connessione

La maggior parte degli errori di connessione tra Lexiik e il vostro negozio e-commerce deriva da problemi di autenticazione, permessi o configurazione del server. Questa guida vi aiuta a diagnosticare e risolvere i problemi più comuni.

I 5 errori più comuni

Ecco gli errori che incontriamo più frequentemente durante la connessione di un negozio. Ogni errore ha una soluzione semplice.

Errore 403: Accesso negato (Forbidden)

Causa principale: La chiave API non ha i permessi necessari per leggere o scrivere i dati dei prodotti.

Soluzioni per piattaforma

Shopify

1. Shopify Admin > Impostazioni > App e canali di vendita
2. Trovate "Lexiik" e cliccate su "Gestisci"
3. Verificate che i permessi includano: read_products, write_products, read_files, write_files
4. Se i permessi sono errati, disinstallate e reinstallate l'applicazione

WooCommerce

1. WordPress Admin > WooCommerce > Impostazioni > Avanzate > Chiavi REST API
2. Trovate la chiave utilizzata da Lexiik
3. Verificate che i permessi siano: Lettura/Scrittura (non solo "Lettura")
4. Se necessario, generate una nuova chiave con i permessi corretti

PrestaShop

1. Back-office PrestaShop > Parametri avanzati > Webservice
2. Modificate la chiave API utilizzata da Lexiik
3. Spuntate tutti i permessi per: products, categories, images, stock_availables
4. Salvate e riprovate

Errore 500: Errore interno del server

Causa principale: Problema lato server del vostro negozio (PHP, database, memoria insufficiente).

Diagnosi passo per passo

1. Controllate i log degli errori PHP
   • WooCommerce: wp-content/debug.log
   • PrestaShop: var/logs/
2. Verificate la configurazione PHP
   • memory_limit: minimo 256M (consigliato: 512M)
   • max_execution_time: minimo 300 secondi
   • upload_max_filesize: minimo 64M
3. Testate manualmente l'API — Utilizzate uno strumento come Postman o curl per testare direttamente l'endpoint API del vostro negozio
4. Verificate la connessione al database — Un database saturo o disconnesso può causare errori 500 intermittenti

Errore 401: Non autorizzato (Unauthorized)

Causa principale: La chiave API è errata, scaduta o formattata in modo errato.

Checklist di risoluzione

• Verificate che non ci siano spazi prima o dopo la chiave API (errore frequente durante il copia e incolla)
• Assicuratevi di utilizzare l'ultima chiave generata (se ne avete create più di una, solo la più recente è valida)
• Verificate che la chiave non sia stata revocata nelle impostazioni del vostro negozio
• Per PrestaShop, verificate che il webservice sia attivato (Parametri avanzati > Webservice > Sì)
• Testate la chiave API con una chiamata curl per validarne il funzionamento

Errore di timeout (tempo di attesa superato)

Causa principale: Il vostro server è troppo lento o sovraccarico per elaborare le richieste API nel tempo concesso.

Soluzioni

• 1. Ottimizzate il database — Un catalogo con 50.000+ prodotti con tabelle non indicizzate può causare timeout. Pulite i log e ottimizzate le tabelle MySQL.
• 2. Disattivate temporaneamente i plugin pesanti — Su WooCommerce, alcuni plugin di cache o sicurezza (Wordfence, All In One Security) possono rallentare le richieste API. Provate a disattivarli temporaneamente.
• 3. Migrate al Lexiik Bridge — Il Lexiik Bridge utilizza webhook asincroni che non causano mai timeout, a differenza dell'API standard.
• 4. Aggiornate il vostro hosting — Un VPS o un hosting dedicato offrirà prestazioni migliori rispetto a un hosting condiviso di base.

Errore SSL/TLS (certificato non valido)

Causa principale: Il vostro negozio non ha un certificato SSL valido, oppure è scaduto.

Risoluzione

1. Verificate il vostro certificato SSL — Usate SSL Labs per testare la validità del certificato
2. Installate un certificato gratuito — Let's Encrypt offre certificati SSL gratuiti e rinnovabili automaticamente. La maggior parte dei provider di hosting (cPanel, Plesk) offre l'installazione con un clic.
3. Forzate HTTPS nel vostro CMS
   • Shopify: Automatico (gestito da Shopify)
   • WooCommerce: Impostazioni > Generali > Indirizzo WordPress e Indirizzo sito (usate https://)
   • PrestaShop: Negozio > Impostazioni negozio > Abilita SSL (Sì)

Gestione delle chiavi API

Le chiavi API sono le "password" che consentono a Lexiik di accedere al vostro negozio. Ecco le best practice di gestione.

Generare una nuova chiave API

Shopify

1. Shopify Admin > Impostazioni > App e canali di vendita
2. Cliccate su "Sviluppa app" (in fondo)
3. Create un'app privata con gli scope: read_products, write_products, read_files, write_files
4. Copiate l'Admin API access token

WooCommerce

1. WordPress Admin > WooCommerce > Impostazioni > Avanzate > Chiavi REST API
2. Cliccate su "Aggiungi chiave"
3. Descrizione: "Lexiik Bridge"
4. Utente: Il vostro account admin
5. Permessi: Lettura/Scrittura
6. Generate la chiave e copiate la Consumer key e il Consumer secret

PrestaShop

1. Back-office PrestaShop > Parametri avanzati > Webservice
2. Attivate il webservice se non è già stato fatto
3. Cliccate su "Aggiungi nuova chiave"
4. Descrizione chiave: "Lexiik Bridge"
5. Spuntate tutti i permessi (o almeno: products, categories, images, stock_availables)
6. Cliccate su "Salva" e copiate la chiave generata

Proteggere le vostre chiavi API

• Non condividete mai pubblicamente le vostre chiavi API (GitHub, forum, screenshot)
• Rinnovate le vostre chiavi ogni 6 mesi per misura di sicurezza
• Eliminate le chiavi inutilizzate per ridurre la superficie di attacco
• Create una chiave dedicata per servizio (una per Lexiik, una per un altro strumento, ecc.)
• Documentate l'uso di ogni chiave con una descrizione chiara

Problemi di permessi di scrittura

Alcuni errori si verificano quando Lexiik non ha i permessi di scrittura su determinati file o cartelle del vostro server.

Errore durante il caricamento delle immagini

Causa: La cartella di upload non ha i permessi di scrittura corretti.

Soluzione (tramite SSH o FTP)

chmod -R 755 /path/to/wordpress/wp-content/uploads/

chmod -R 755 /path/to/prestashop/img/

Verifica dei permessi

Ecco i permessi raccomandati per ogni piattaforma:

Strumenti di diagnosi

Lexiik offre diversi strumenti integrati per diagnosticare i problemi di connessione.

Test di connessione integrato

Nella dashboard di Lexiik, andate su Connessioni > Testa la connessione. Questo strumento esegue una serie di verifiche automatiche:

• Validità della chiave API
• Permessi di lettura/scrittura
• Tempo di risposta del server
• Certificato SSL
• Compatibilità della versione della piattaforma

Log di sincronizzazione

Ogni tentativo di sincronizzazione viene registrato nei log. Per accedervi:

1. Dashboard Lexiik > Connessioni
2. Cliccate sui 3 punti accanto al vostro negozio
3. Selezionate "Visualizza log"

I log indicano:

• Data e ora di ogni sincronizzazione
• Stato (riuscita o fallita)
• Durata della sincronizzazione
• Numero di prodotti elaborati
• Messaggi di errore dettagliati in caso di fallimento

Modalità debug

Per gli sviluppatori, il Lexiik Bridge offre una modalità debug che registra tutti i dettagli tecnici.

Attivare la modalità debug

Nel modulo Lexiik Bridge del vostro negozio:

1. Aprite la configurazione del modulo
2. Attivate l'opzione "Modalità debug"
3. Eseguite una sincronizzazione
4. Consultate il file di log generato (posizione indicata nella configurazione)

Casi particolari e hosting specifici

Alcuni provider di hosting o configurazioni server richiedono aggiustamenti specifici.

Hosting condiviso

Gli hosting condivisi (OVH, O2Switch, Ionos, ecc.) impongono talvolta delle restrizioni.

• Problema: Webhook bloccati dal firewall
  Soluzione: Aggiungete gli IP di Lexiik alla whitelist (disponibili in Impostazioni > Integrazioni)
• Problema: Limite di richieste API al minuto
  Soluzione: Il Lexiik Bridge gestisce automaticamente il rate limiting. Se usate l'API standard, migrate verso il Bridge.
• Problema: PHP memory_limit troppo basso (128M)
  Soluzione: Contattate il vostro provider di hosting per aumentarlo a 256M minimo. Oppure aggiungete in wp-config.php: define('WP_MEMORY_LIMIT', '256M');

Siti dietro Cloudflare

Se il vostro negozio usa Cloudflare, alcune regole di sicurezza possono bloccare i webhook di Lexiik.

Configurazione Cloudflare consigliata

1. Cloudflare Dashboard > Firewall Rules
2. Create una regola di eccezione per gli URL: /wp-json/lexiik/* (WooCommerce) o /api/lexiik/* (PrestaShop)
3. Azione: Allow (consenti)
4. In Security Level, impostate "Medium" invece di "High" per questi URL

Web Application Firewall (WAF)

I WAF come Sucuri, Wordfence o ModSecurity possono bloccare le richieste API.

• Wordfence (WordPress): Andate in Wordfence > Firewall > Rate Limiting > Aggiungete l'IP di Lexiik alla whitelist
• Sucuri: Create una regola di eccezione per gli endpoint /wp-json/lexiik/ o /api/lexiik/
• ModSecurity: Aggiungete una regola di eccezione nel file .htaccess o contattate il vostro provider di hosting

Ottenere ulteriore assistenza

Se non trovate una soluzione in questa guida, il team di supporto Lexiik è qui per aiutarvi.

Contattare il supporto

• Chat dal vivo: Disponibile 7 giorni su 7 nella dashboard Lexiik (angolo in basso a destra)
• Email: [email protected] (risposta entro 2 ore in media)
• Telefono: Solo per i piani Pro ed Expert (numero disponibile nella vostra area clienti)
• Documentazione tecnica: docs.lexiik.com

Risorse complementari

• Guida alla connessione del negozio
• Confronto Bridge vs API standard
• Avviare il primo audit SEO