Documentazione completa

Guida dettagliata all'installazione e configurazione del modulo Shopify Integration

Indice

1. Introduzione

Questa guida spiega passo dopo passo come configurare l'integrazione Shopify per Dolibarr. Dettagliamo esattamente dove trovare ogni valore necessario per la configurazione.

Cosa imparerete: Da dove provengono tutti i valori di configurazione e come ottenerli precisamente.

Novità della v2.0.24

Questa versione porta miglioramenti importanti per un'integrazione più fluida e automatizzata.

Nuove funzionalità

Import automatico degli ordini storici

Il sistema CRON può ora importare automaticamente i vostri ordini storici durante la prima sincronizzazione, creando automaticamente i clienti associati.

Auto-attivazione intelligente dei CRON

Le attività CRON si attivano automaticamente non appena le configurazioni di prodotti e ordini sono complete, e si disattivano se la configurazione diventa incompleta per evitare errori API.

Correzioni critiche

Problemi risolti:
  • Sincronizzazione manuale: Corretto il caso in cui l'interfaccia mostrava i prodotti ma non riusciva a sincronizzarli
  • Gestione dei servizi: I servizi sono ora correttamente identificati e sincronizzati come tali (requiresShipping: false)
  • Parametri unificati: Gestione coerente dei parametri tra le interfacce di ricerca e sincronizzazione
  • SKU con zeri iniziali: Conservazione corretta degli zeri iniziali nei riferimenti prodotti

Miglioramenti di sicurezza

Installazione sicura: Le attività CRON sono ora disattivate per default durante l'installazione per evitare chiamate API premature. Si attivano automaticamente una volta completata la configurazione.

2. Prerequisiti di sistema

Dolibarr & Server

Componente Versione richiesta Verifica
PHP 7.2.5 a 8.3.16 Menu Dolibarr → Home → Informazioni sistema
Dolibarr 19.0 a 21.x Menu Dolibarr → Home → Versione
Estensione cURL Attivata Menu Dolibarr → Home → Informazioni sistema → Estensioni PHP
Estensione JSON Attivata Menu Dolibarr → Home → Informazioni sistema → Estensioni PHP

Shopify

3. Installazione del modulo

Passaggio 1: Acquisto e download

  1. Acquistate il modulo su Dolistore
  2. Scaricate il file ZIP dal vostro account Dolistore
  3. Non decomprimete il file

Passaggio 2: Installazione in Dolibarr

  1. Accedete a Dolibarr come amministratore
  2. Andate in Home → Configurazione → Moduli/Applicazioni
  3. Cliccate su "Distribuisci/Installa modulo/applicazione esterna"
  4. Selezionate il vostro file ZIP scaricato
  5. Cliccate su "Invia file"
  6. Attivate il modulo nell'elenco dei moduli disponibili
Importante: Attivate questi moduli Dolibarr richiesti prima di continuare:
  • Prodotti/Servizi
  • Terze parti (Clienti/Fornitori)
  • Ordini clienti
  • Fatture clienti
  • Scorte
  • Spedizioni

4. Creazione dell'applicazione Shopify

Passaggio cruciale: Dovete creare un'applicazione privata in Shopify per ottenere le chiavi di accesso.

Passaggio 1: Accedere alle applicazioni

  1. Accedete alla vostra amministrazione Shopify
  2. Nel menu di sinistra, cliccate su "Apps"
  3. Cliccate su "Sviluppa app" (o "App and sales channel settings")
  4. Se è la vostra prima app, cliccate su "Consenti sviluppo di app personalizzate"

Passaggio 2: Creare l'applicazione

  1. Cliccate su "Crea un'app"
  2. Nome dell'app: Dolibarr Integration
  3. Email sviluppatore: la vostra email
  4. Cliccate su "Crea l'app"

Passaggio 3: Configurare i permessi

Cliccate su "Configura gli scope Admin API" e attivate questi permessi:

Scope Permesso Giustificazione
read_products Lettura Leggere i prodotti Shopify
write_products Scrittura Creare/modificare prodotti
read_orders Lettura Leggere gli ordini
write_orders Scrittura Modificare gli ordini
read_customers Lettura Leggere dati clienti
write_customers Scrittura Creare clienti
read_inventory Lettura Leggere le scorte
write_inventory Scrittura Aggiornare le scorte
read_locations Lettura Leggere le ubicazioni

Cliccate su "Salva" dopo aver selezionato tutti gli scope.

Passaggio 4: Installare l'applicazione

  1. Cliccate su "Installa l'app"
  2. Confermate l'installazione
  3. L'app è ora installata e potete recuperare i token

5. Configurazione Shopify - Dove trovare ogni valore

Ora che la vostra applicazione è creata, ecco esattamente dove recuperare ogni valore:

Campo Dolibarr Dove trovare il valore in Shopify Formato esatto Esempio
Nome host negozio Shopify * URL del vostro negozio (barra degli indirizzi) mionegozio.myshopify.com
(SENZA https://)		 negozio-test.myshopify.com
Token di accesso Shopify * Apps → Sviluppa app → [La vostra app] → Token di accesso API → "Admin API access token" shpat_xxxxxxxxxxxxxxxxxxxxxxxx shpat_1a2b3c4d5e6f7g8h9i0j
Chiave API Shopify * Apps → Sviluppa app → [La vostra app] → Credenziali API → "API key" Stringa alfanumerica abc123def456ghi789
Chiave segreta API Shopify * Apps → Sviluppa app → [La vostra app] → Credenziali API → "API secret key" Stringa alfanumerica segreta shpss_xyz789abc123def456
ID ubicazione Shopify * Impostazioni → Ubicazioni → Copiate l'ID della vostra ubicazione principale Numero intero 123456789
Venditore Shopify Nome del vostro brand/azienda (opzionale) Testo libero Il Mio Negozio
Attenzione ai formati:
  • Nome host: SENZA "https://" all'inizio
  • Token di accesso: Inizia generalmente con "shpat_"
  • Chiave segreta: Inizia generalmente con "shpss_"
  • ID ubicazione: Solo numeri, nessun testo

Come recuperare l'ID ubicazione

  1. In Shopify Admin, andate in Impostazioni → Ubicazioni
  2. Cliccate sulla vostra ubicazione principale (generalmente quella con il vostro indirizzo)
  3. L'ID si trova nell'URL: .../locations/123456789
  4. Copiate solo i numeri: 123456789

6. Configurazione Dolibarr - Parametri automatici e manuali

Campo Come ottenere il valore Note
Chiave API Dolibarr * Generata automaticamente dal modulo Se non ne avete una: Menu → Utenti & Gruppi → [Il vostro utente] → Tab API → Genera
URL host Dolibarr * Rilevato automaticamente Es: https://vostrodominio.com/dolibarr
Categoria prodotti Dolibarr * Menu → Prodotti/Servizi → Categorie → Selezionate la vostra categoria Solo i prodotti di questa categoria saranno sincronizzati

Parametri di sincronizzazione

Parametro Valore raccomandato Spiegazione
Massimo ordini per sync 10 Limita il numero di ordini elaborati ogni volta
Prodotti per ciclo cron 10 Numero di prodotti aggiornati per ciclo automatico

7. Configurazione sincronizzazione prodotti

Opzioni di sincronizzazione disponibili

Opzione Descrizione Raccomandazione
Sincronizza prezzi Invia i prezzi Dolibarr a Shopify Attivato - Essenziale per e-commerce
Livello prezzo (se multiprice) Quale livello prezzo Dolibarr utilizzare Livello 1 generalmente
Sincronizza descrizioni Invia le descrizioni prodotti Attivato - Importante per SEO
Sincronizza immagini Invia le immagini prodotti Attivato - Indispensabile
Sincronizza scorte Aggiorna le quantità in scorta Attivato - Evita la sovravendita
Utilizza scorta virtuale Scorta reale - ordini + ordini fornitori Attivato - Più preciso
Suggerimento: Attivate tutte le opzioni per una sincronizzazione completa. Potrete disattivarle individualmente più tardi se necessario.

8. Configurazione sincronizzazione ordini

Parametri richiesti

Campo Dove configurarlo in Dolibarr Esempio
Prefisso ordini Testo libero (es: SHOP-) SHOP-
Origine ordine Menu → Configurazione → Dizionari → Origine delle proposte commerciali/ordini Internet
Condizioni di pagamento Menu → Configurazione → Dizionari → Condizioni di pagamento Pagamento alla consegna
Metodo spedizione predefinito Menu → Configurazione → Dizionari → Mezzi di trasporto Corriere
Prodotto per spese di spedizione Menu → Prodotti/Servizi → Creare un servizio "Spese di spedizione" Servizio con rif SHIP001
Magazzino predefinito Menu → Scorte → Magazzini Il vostro magazzino principale
Conto bancario Menu → Banca → Conti finanziari Il vostro conto principale

Creare il prodotto "Spese di spedizione"

  1. Menu → Prodotti/Servizi → Nuovo prodotto/servizio
  2. Tipo: Servizio
  3. Riferimento: SPEDIZIONE
  4. Etichetta: Spese di spedizione
  5. Prezzo: 0 (sarà calcolato automaticamente)
  6. Cliccate su Crea

8.1. Importazione ordini storici v2.0.24

Importa automaticamente tutti i tuoi ordini Shopify precedenti durante la prima configurazione del modulo.

Nuova funzione: L'importazione storica ora utilizza la paginazione intelligente per elaborare migliaia di ordini senza limitazione e riprende automaticamente se interrotta.

Campi di configurazione

Campo Descrizione
Abilitare importazione storica Consente l'importazione automatica degli ordini Shopify precedenti durante la prossima esecuzione CRON. Si deseleziona automaticamente dopo un'importazione riuscita per evitare duplicati.
Data inizio importazione Data da cui importare ordini storici (lasciare vuoto per importare dall'inizio)
Data fine importazione Data fino a cui importare ordini storici (lasciare vuoto per importare fino ad oggi)
Importazione storica completata Indica se l'importazione storica è stata eseguita. Una volta completata, verranno importati solo i nuovi ordini

Come funziona

  1. Attiva l'importazione storica e opzionalmente definisci un intervallo di date
  2. Il sistema elabora automaticamente gli ordini in lotti di 10-50 secondo la tua configurazione
  3. Se interrotto dal limite di tempo, l'importazione riprende automaticamente al prossimo CRON
  4. Una volta completato, l'importazione si disattiva automaticamente per evitare duplicati
Paginazione automatica: Il sistema attraversa automaticamente tutte le pagine di ordini disponibili, anche su cataloghi grandi.
Per importazioni iniziali voluminose: Monitora i log di Dolibarr per seguire i progressi.

9. Configurazione attività automatiche (Cron)

Importante: Le attività cron sono disattivate di default per sicurezza. Dovete attivarle manualmente.

Attività da configurare

Attività Frequenza raccommandata Descrizione
Sincronizzazione prodotti Ogni ora Aggiorna prodotti e scorte
Importazione ordini Ogni 15 minuti Recupera i nuovi ordini Shopify

Attivazione delle attività cron

  1. Menu → Strumenti → Attività programmate
  2. Cercate le attività "ShopifyIntegration"
  3. Per ogni attività:
    • Cliccate su Modifica
    • Attivate "Stato: Attivato"
    • Configurate la frequenza
    • Cliccate su Modifica
Test: Potete testare un'attività cliccando sul pulsante "Esegui ora" accanto a ogni attività.

10. Aggiornamento del modulo

Come aggiornare il modulo Shopify Integration a una nuova versione dal DoliStore.

Importante: La procedura di disattivazione/riattivazione è obbligatoria affinché gli script di aggiornamento SQL vengano eseguiti correttamente.

Procedura di aggiornamento

1. Scaricare la nuova versione

  1. Andate al DoliStore
  2. Accedete con il vostro account
  3. Scaricate l'ultima versione del modulo (file ZIP)
  4. Salvate il file ZIP sul vostro computer

2. Disattivare il modulo corrente

  1. In Dolibarr: Menu → Configurazione → Moduli/Applicazioni
  2. Cercate "Shopify Integration"
  3. Cliccate su "Disattiva" (pulsante rosso)
  4. Confermate la disattivazione

3. Installare la nuova versione

  1. Rimanete in Menu → Configurazione → Moduli/Applicazioni
  2. Cliccate su "Distribuire/Installare modulo esterno"
  3. Cliccate su "Sfoglia" e selezionate il file ZIP scaricato
  4. Cliccate su "Invia file"
  5. Seguite le istruzioni di installazione

4. Riattivare il modulo

  1. Una volta completata l'installazione, cercate "Shopify Integration"
  2. Cliccate su "Attiva" (pulsante verde)
  3. Verificate che il numero di versione mostrato corrisponda alla nuova versione
  4. Gli script SQL di aggiornamento vengono eseguiti automaticamente durante la riattivazione
Verifica:
  • Il numero di versione mostrato nell'elenco dei moduli deve corrispondere alla nuova versione
  • Controllate i log di Dolibarr per assicurarvi che gli script SQL siano stati eseguiti senza errori
  • Testate le funzionalità principali (sincronizzazione manuale, configurazione)

Metodo alternativo: Via scheda DoliStore

Alternativa rapida: Potete anche provare la scheda "Moduli disponibili da DoliStore" che a volte consente aggiornamenti automatici diretti, ma il metodo sopra è più affidabile.
In caso di problemi: Ripristinate il backup della cartella precedente e contattate il supporto. Non lasciate mai il modulo in uno stato parzialmente aggiornato.

11. Risoluzione problemi comuni

Errori di connessione Shopify

Errore: "Connection failed" o "Access denied"
Causa: Informazioni API errate
Soluzione:
  • Verificate il nome host (senza https://)
  • Rigenerate il token di accesso Shopify
  • Verificate che l'app sia ben installata
  • Controllate tutti gli scope necessari

Prodotti non sincronizzati

Errore: "Nessun prodotto sincronizzato"
Causa: Problema di categoria o stato
Soluzione:
  • Verificate che i vostri prodotti siano nella categoria corretta
  • Stato prodotto = "In vendita"
  • Prodotto non archiviato

Ordini non importati

Errore: "No orders found"
Causa: Configurazione incompleta
Soluzione:
  • Completate tutti i campi obbligatori della scheda "Ordini"
  • Verificate che il conto bancario esista
  • Create il prodotto "Spese di spedizione"

Dove trovare i log

Menu → Strumenti → Log Dolibarr Cercate: "ShopifyIntegration"

Supporto tecnico

Se non riuscite a risolvere il vostro problema:

🎉 Congratulazioni!

La vostra integrazione Shopify-Dolibarr è ora configurata. Potete testare la sincronizzazione tramite l'interfaccia di sincronizzazione manuale.

Torna alla home Valuta il modulo