Documentazione - Integrazione Shopify per Dolibarr ERP CRM

0. Ottenere una licenza

Passo 1: Installare l'app Doli2Shop

Accedi a doli2shop.ptitetete.org/shopify-app/ e installa l'applicazione nel tuo negozio Shopify.

Passo 2: Scegliere il tuo abbonamento

Annuale (consigliato): 250€ IVA esclusa/anno - Risparmia 50€
Mensile: 25€ IVA esclusa/mese - Senza impegno

Già cliente DoliStore?
Scegli "Ho già una licenza" e inserisci il tuo numero di serie (SI-XXXX-XXXX-XXXX) per continuare a utilizzare la tua licenza esistente fino alla sua scadenza.

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	18.0 a 22.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

Negozio Shopify attivo (piano Basic o superiore)
Accesso amministratore al negozio
Capacità di creare applicazioni private

3. Installazione del modulo

Passaggio 1: Acquisto e download

Acquistate il modulo su Dolistore
Scaricate il file ZIP dal vostro account Dolistore
Non decomprimete il file

Passaggio 2: Installazione in Dolibarr

Accedete a Dolibarr come amministratore
Andate in Home → Configurazione → Moduli/Applicazioni
Cliccate su "Distribuisci/Installa modulo/applicazione esterna"
Selezionate il vostro file ZIP scaricato
Cliccate su "Invia file"
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. Installazione dell'applicazione Doli2Shop in Shopify

Connessione semplificata e sicura: Dalla versione 2.0, il modulo utilizza un'applicazione Shopify Partner ufficiale per una connessione OAuth 2.0 sicura. Non è più necessario creare un'applicazione privata manualmente.

Perché un'applicazione Shopify?

L'utilizzo di un'applicazione Shopify Partner ufficiale offre numerosi vantaggi:

🔒 Sicurezza OAuth 2.0: Non è più necessario copiare/incollare chiavi API sensibili. La connessione è stabilita in modo sicuro tramite il protocollo OAuth 2.0 standard del settore.
✅ Conformità Shopify: L'applicazione rispetta tutte le linee guida di sicurezza di Shopify ed è approvata ufficialmente.
⚡ Installazione semplificata: 3 clic per connettere il vostro negozio invece di configurare manualmente un'applicazione privata.
🔄 Aggiornamenti automatici: I permessi API sono gestiti automaticamente con ogni aggiornamento del modulo.
📦 Tutti i permessi inclusi: L'applicazione richiede automaticamente i permessi necessari (prodotti, ordini, clienti, inventario, ubicazioni, evasioni).

Passaggi per l'installazione

Passaggio 1: Accedere all'App Store Shopify

Accedete alla vostra amministrazione Shopify
Cliccate su "Apps" nel menu di sinistra
Cercate "Doli2Shop - ERP Integration" nello store
Oppure accedete direttamente tramite il link: Doli2Shop su Shopify App Store

Passaggio 2: Installare l'applicazione

Cliccate su "Aggiungi app"
Controllate i permessi richiesti (sono tutti necessari per la sincronizzazione completa)
Cliccate su "Installa app"

Passaggio 3: Connettere il vostro Dolibarr

Dopo l'installazione, sarete reindirizzati alla pagina di configurazione
Inserite l'URL del vostro Dolibarr (es: https://vostrodominio.com/dolibarr)
L'applicazione stabilirà automaticamente la connessione sicura
Le credenziali sono trasmesse in modo sicuro al vostro modulo Dolibarr

Prerequisito: Il vostro Dolibarr deve essere accessibile tramite HTTPS da Internet affinché la connessione OAuth funzioni.

Video tutorial

Guardate il nostro tutorial video per una guida passo passo:

Guardare il video di installazione

Permessi richiesti dall'applicazione

L'applicazione Doli2Shop richiede automaticamente i seguenti permessi durante l'installazione:

Permesso	Utilizzo
`read_products` / `write_products`	Sincronizzazione dei prodotti tra Dolibarr e Shopify
`read_orders` / `write_orders`	Importazione degli ordini Shopify in Dolibarr
`read_customers` / `write_customers`	Creazione e sincronizzazione dei clienti
`read_inventory` / `write_inventory`	Gestione delle scorte in tempo reale
`read_locations`	Gestione delle ubicazioni di magazzino
`read_fulfillments` / `write_fulfillments`	Gestione delle spedizioni

Installazione completata! Una volta l'applicazione installata, le credenziali sono automaticamente configurate nel vostro modulo Dolibarr. Potete procedere direttamente alla configurazione delle opzioni di sincronizzazione.

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

In Shopify Admin, andate in Impostazioni → Ubicazioni
Cliccate sulla vostra ubicazione principale (generalmente quella con il vostro indirizzo)
L'ID si trova nell'URL: .../locations/123456789
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"

Menu → Prodotti/Servizi → Nuovo prodotto/servizio
Tipo: Servizio
Riferimento: SPEDIZIONE
Etichetta: Spese di spedizione
Prezzo: 0 (sarà calcolato automaticamente)
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

Attiva l'importazione storica e opzionalmente definisci un intervallo di date
Il sistema elabora automaticamente gli ordini in lotti di 10-50 secondo la tua configurazione
Se interrotto dal limite di tempo, l'importazione riprende automaticamente al prossimo CRON
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

Menu → Strumenti → Attività programmate
Cercate le attività "ShopifyIntegration"
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

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

2. Disattivare il modulo corrente

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

3. Installare la nuova versione

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

4. Riattivare il modulo

Una volta completata l'installazione, cercate "Shopify Integration"
Cliccate su "Attiva" (pulsante verde)
Verificate che il numero di versione mostrato corrisponda alla nuova versione
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"

🚨 Permessi Shopify mancanti - CRITICO

Sintoma: Gli ordini non si sincronizzano da diversi giorni, il CRON restituisce un errore (-1)
Causa: Permessi WRITE mancanti nella vostra applicazione Shopify
Diagnosi rapida:

Andate in Menu ShopifyIntegration → Configurazione → Diagnostico di sistema
Osservate la sezione "Shopify API Permissions"
Se vedete righe con status: "error" → Permessi mancanti!

📝 Permessi richiesti (9 minimi)

Permesso	Tipo	Richiesto	Funzione
`read_products`	READ	✅ SÌ	Leggere prodotti
`write_products`	WRITE	✅ SÌ	Creare/modificare prodotti
`read_inventory`	READ	✅ SÌ	Leggere scorte
`write_inventory`	WRITE	✅ SÌ	Aggiornare scorte
`read_orders`	READ	✅ SÌ	Leggere ordini
`write_orders`	WRITE	✅ SÌ	Modificare ordini
`read_customers`	READ	✅ SÌ	Leggere clienti
`write_customers`	WRITE	✅ SÌ	Creare clienti
`read_locations`	READ	✅ SÌ	Leggere ubicazioni
`write_publications`	WRITE	⚠️ Raccomandato	Pubblicare su canali vendita
`write_files`	WRITE	⚠️ Raccomandato	Sincronizzare immagini

🔧 Procedura di correzione passo dopo passo

Accedere alla vostra applicazione Shopify:
- Shopify Admin → Settings → Apps and sales channels
- Cliccate su "Develop apps"
- Selezionate la vostra applicazione Dolibarr
Modificare i permessi:
- Tab "Configuration"
- Sezione "Admin API access scopes" → Cliccate su "Edit"
Attivare TUTTI i permessi mancanti (vedere tabella sopra)
Salvare e reinstallare:
- Cliccate su "Save"
- ⚠️ IMPORTANTE: Cliccate su "Reinstall app" per attivare i nuovi scopes
Recuperare il nuovo token:
- Tab "API credentials"
- Sezione "Admin API access token"
- Cliccate su "Reveal token once" e copiatelo
- ⚠️ Non potrete vederlo di nuovo dopo!
Aggiornare Dolibarr:
- Menu ShopifyIntegration → Configurazione → Setup
- Campo "Shopify Access Token" → Incollate il nuovo token
- Cliccate su "Salva"
Verificare la correzione:
- Menu ShopifyIntegration → Configurazione → Diagnostico di sistema
- Tutti i permessi devono mostrare status: "ok"
- Testate una sincronizzazione manuale degli ordini

⚠️ Errore comune: Avere solo i permessi READ NON è sufficiente! Il modulo ha assolutamente bisogno dei permessi WRITE per funzionare correttamente (creare prodotti, aggiornare scorte, aggiungere note agli ordini, ecc.).

Documentazione completa: Per ulteriori dettagli, consultate la guida tecnica completa in /docs/troubleshooting/SHOPIFY_PERMISSIONS_EN.md della vostra installazione.

Problemi endpoint API Dolibarr

Errore: "Endpoint non trovato (404)" o "Bad Request (400)"
Cause possibili:

Modulo API/Servizi Web disabilitato: Menu → Configurazione → Moduli → Cercare "API" → Abilitare
Versione Dolibarr troppo vecchia: Alcuni endpoint richiedono Dolibarr 14+
Permessi utente insufficienti: L'utente API deve avere diritti completi
File di test mancante: Per documents/download, questo è normale se non esiste logo aziendale

Configurare permessi utente API

Menu → Configurazione → Utenti e Gruppi
Cliccate sul vostro utente API
Scheda "Permessi"
Accordate questi permessi minimi:

✅ API: Accesso completo alle API
✅ Documenti: Leggere documenti
✅ Prodotti/Servizi: Leggere prodotti
✅ Terze parti: Leggere/creare clienti
✅ Ordini: Leggere/creare ordini

Cliccate "Salva"

Nota importante: L'errore 404 su "documents/download" è normale se non esiste logo aziendale. Questo non influenza la sincronizzazione Shopify.

Esplorare e testare l'API Dolibarr

Dolibarr fornisce un esploratore API integrato per testare e documentare tutti gli endpoint disponibili:

URL esploratore: https://vostrodominio.com/dolibarr/api/index.php/explorer
Documentazione Swagger: https://vostrodominio.com/dolibarr/api/index.php/explorer/swagger.json?DOLAPIKEY=vostra_chiave_api
Sostituite vostrodominio.com/dolibarr con il vostro URL reale di Dolibarr
Sostituite vostra_chiave_api con la vostra chiave API utente

Questo strumento vi permette di:

✅ Testare tutti gli endpoint API dal vivo
✅ Vedere la documentazione completa per ogni endpoint
✅ Verificare i parametri richiesti e opzionali
✅ Diagnosticare i problemi API direttamente

Parametri API critici secondo documentazione Swagger:

GET /documents: Parametro modulepart obbligatorio (es.: product, company, user)
GET /documents/download: Parametro modulepart obbligatorio + original_file opzionale
GET /status: Endpoint di base (non documentato in Swagger ma funzionale)

Nota: Gli errori 400 (Bad Request) indicano generalmente parametri mancanti o non validi.

Dove trovare i log

Menu → Strumenti → Log Dolibarr Cercate: "ShopifyIntegration"

Supporto tecnico

Se non riuscite a risolvere il vostro problema:

Email: doli2shop@ptitetete.com
Tempo di risposta: 24-48h lavorative
Informazioni da fornire:

Versione Dolibarr
Versione del modulo
Messaggio di errore esatto
Screenshot della configurazione

Indice