NextShop Bridge – Shopify ⇄ Dolibarr: sincronizzazione, migrazione e controllo

Collegate i vostri negozi Shopify a Dolibarr, sincronizzate l'attività e-commerce in automatico e migrate lo storico mantenendo il pieno controllo. NextShop Bridge è un modulo professionale per Dolibarr pubblicato da NEXT GESTION. Riunisce in un unico strumento un connettore Shopify, un motore di sincronizzazione bidirezionale, un centro di importazione file, una procedura guidata di migrazione, un centro di riconciliazione e conflitti e una dashboard operativa.

Non un semplice esportatore di prodotti, ma una vera piattaforma commerce per aziende, system integrator e agenzie che vogliono fare di Dolibarr l'ERP/CRM centrale del proprio negozio online. Il modulo si basa esclusivamente sulla GraphQL Admin API di Shopify (versione di riferimento 2026-07), sui webhook firmati e sui meccanismi di estensione ufficiali di Dolibarr: trigger, hook, campi extra, processi pianificati, API REST e permessi. Nessun file nativo di Dolibarr viene modificato.

Perché NextShop Bridge?

• Più negozi su una sola istanza Dolibarr, ciascuno con dominio, valuta, versione API, abbinamento dei magazzini, coda e log propri.
• Direzione per oggetto: Shopify → Dolibarr, Dolibarr → Shopify, bidirezionale o disattivata, con fonte di verità configurabile fino al singolo campo.
• Un solo ordine Dolibarr per ogni ordine Shopify: idempotenza garantita dalla chiave ID Shopify + connessione, anche se il webhook arriva più volte o il file viene reimportato.
• Integrità finanziaria: gli importi vengono confrontati, non arrotondati; ogni differenza superiore alla tolleranza configurata viene segnalata. Interfaccia in 5 lingue: francese, inglese, tedesco, italiano e spagnolo.

Connessione e autenticazione

• Tre metodi: token di accesso di un'app installata, OAuth authorization code con verifica di state e HMAC, client credentials per i negozi della stessa organizzazione Shopify; i token in scadenza vengono rinnovati automaticamente.
• Test di connessione: negozio, stato, versione API effettivamente servita, valuta, fuso orario, piano, sedi, numero di prodotti, clienti e ordini, webhook attivi e scope concessi.
• Schermata «Permessi API Shopify»: per ogni ambito – clienti, prodotti, ordini, giacenze, evasioni, resi, sconti – indica se l'accesso è concesso e quale funzione risulterebbe limitata in assenza dello scope.
• Versioni API e segreti: 2026-07 predefinita, 2026-04 disponibile, 2026-10 dal rilascio, con verifica dell'intestazione di versione a ogni risposta. Token e segreti sono cifrati in AES-256-GCM, mascherati a video e mai scritti nei log.

Sincronizzazione bidirezionale per oggetto

L'amministratore definisce per ogni oggetto la direzione e la fonte di verità: Shopify principale, Dolibarr principale, ultima modifica o risoluzione manuale.

I cicli di sincronizzazione sono evitati grazie agli identificativi di correlazione, all'origine di ogni scrittura e a un hash dell'ultima sincronizzazione. Dopo la migrazione iniziale, la sincronizzazione delta tratta solo le modifiche reali. Nessuna cancellazione viene propagata per impostazione predefinita: ogni eliminazione va confermata singolarmente nel centro conflitti.

Clienti, prodotti e giacenze

• Clienti B2C: a scelta un soggetto terzo per cliente oppure un soggetto terzo generico con un contatto per cliente; vengono ripresi ID Shopify, nome, e-mail, telefono, azienda, lingua, stato, tag, note e indirizzi. Gli ordini ospite seguono le stesse regole; il consenso marketing è registrato solo se l'opzione è attiva e i duplicati sono individuati tramite ID Shopify, e-mail e telefono.
• Clienti B2B (Companies): importati come soggetti terzi con contatti e indirizzi, quando il negozio dispone di questa funzionalità Shopify (secondo l'abbonamento) e dello scope corrispondente.
• Prodotti, collezioni e immagini: ID, handle, titolo, descrizione, fornitore, tipo di prodotto, stato, tag, collezioni, immagini, SEO e metafield. Le collezioni diventano categorie Dolibarr, i tag un campo extra dedicato. Le immagini arrivano come documenti del prodotto, con rilevamento dei duplicati per ID, URL e hash SHA-256 e download consentito solo dagli host Shopify.
• Varianti e opzioni: con il modulo Varianti attivo vengono creati il prodotto padre e le combinazioni di attributi, altrimenti ogni variante diventa un prodotto vendibile con lo SKU come riferimento. SKU, codice a barre, opzioni, prezzo, prezzo barrato, peso e giacenza sono gestiti a livello di variante.
• Giacenze e magazzini: ogni sede Shopify viene associata a un magazzino Dolibarr (una sede = un magazzino, più sedi sommate o regola per sede). Le quantità disponibili sono importate con movimenti di rettifica; in esportazione vengono verificate la quantità precedente e la chiave di idempotenza e ogni discrepanza è segnalata come conflitto di giacenza anziché sovrascritta.

Ordini, fatture, pagamenti e rimborsi

• Ordini: nome e numero, data, cliente o ospite, indirizzi, valuta, righe di prodotti e varianti, sconti con la loro origine, imposte, spese di spedizione, costi aggiuntivi, note, tag e stati finanziario, di evasione e dell'ordine.
• Fatture: il flusso è ordine Shopify → ordine Dolibarr → fattura Dolibarr, con momento configurabile (alla creazione, al pagamento, alla spedizione o manualmente). Il modulo non inventa alcuna «fattura Shopify».
• Pagamenti: importazione delle transazioni Shopify con ID, gateway, importo, valuta, stato e tipo. Solo vendite e catture riuscite generano un pagamento Dolibarr; autorizzazioni e annullamenti sono tracciati senza scritture contabili. Un abbinamento aperto dei gateway (Shopify Payments, PayPal, Stripe, carta, bonifico, contrassegno…) assegna modalità di pagamento e conti bancari.
• Rimborsi: righe, quantità, importi, imposte, spedizione rimborsata e transazioni. Una nota di credito Dolibarr viene creata se la regola lo prevede e la corrispondenza è affidabile; in caso contrario si apre un conflitto da decidere manualmente.
• Controllo dell'integrità finanziaria: subtotale, sconti, spedizione, imposte, totale, pagato e rimborsato vengono confrontati; ogni differenza oltre la tolleranza genera un conflitto finanziario visibile con la causa probabile.

Resi, spedizioni, imposte e valute

• Resi: reso, righe, quantità, stato, rimborso collegato e rientro a magazzino vengono monitorati. Il modulo distingue rigorosamente reso, rimborso e annullamento: un reso senza rimborso non genera mai una nota di credito.
• Evasioni e tracciamento: importate come spedizioni Dolibarr con il modulo Spedizioni attivo; alla convalida di una spedizione l'evasione viene creata in Shopify (quantità, corriere, numero e URL di tracciamento) e il tracking viene poi aggiornato. Le modalità di spedizione Dolibarr sono abbinate alle società di tracciamento Shopify.
• Imposte e sconti: le righe imposta Shopify sono abbinate alle aliquote IVA di Dolibarr per titolo, aliquota e paese, con controllo dello scarto; gli sconti conservano la propria origine e i codici sconto restano archiviati e consultabili.
• Multivaluta e metafield: valuta e importo originali sono sempre conservati e il tasso di cambio registrato quando disponibile o con il modulo Multivaluta attivo. I metafield sono mappati in modo tipizzato sui campi extra, nelle due direzioni.

Webhook e affidabilità operativa

• Webhook firmati: verifica HMAC-SHA256 sul corpo grezzo, rifiuto degli eventi non autentici, protezione dal replay e deduplicazione. Sono sottoscritti ordini, pagamenti, rimborsi, resi, evasioni, clienti, prodotti, giacenze, sedi, operazioni bulk, disinstallazione dell'app, aggiornamento degli scope e richieste GDPR.
• Coda con priorità (pagamenti per primi), nuovi tentativi automatici dopo 1 min, 5 min, 15 min e 1 h, poi dead-letter queue con rimessa in coda manuale.
• Rate limiting basato sul costo delle query GraphQL e circuit breaker quando Shopify non è raggiungibile: la coda viene conservata e l'elaborazione riprende progressivamente, senza perdita di dati. Le operazioni bulk trattano i grandi volumi in JSONL letto in streaming, con monitoraggio e ripresa.

Import Center per CSV, Excel e ZIP

• Caricamento con trascinamento di file CSV, TXT, XLS, XLSX e ZIP, esportati da Shopify o rielaborati in un foglio di calcolo.
• Ispettore file: estensione, tipo MIME, codifica (UTF-8, UTF-16, Windows-1252, ISO-8859-1/15), separatore, numero di righe e colonne, intestazioni, formati di date e decimali, valute, valori vuoti, duplicati ed errori.
• Rilevamento automatico del tipo con punteggio di affidabilità: clienti, prodotti, varianti, giacenze, ordini e transazioni. Un prodotto distribuito su più righe resta un solo prodotto e le righe di uno stesso ordine vengono raggruppate.
• Mappatura visuale «colonna → campo Dolibarr» con abbinamento automatico, manuale, colonna ignorata, valore costante e concatenazione; modelli riutilizzabili e trasformazioni quali trim, sostituzione, espressioni regolari, suddivisione, conversione di date e decimali, valore predefinito, dizionario e pulizia dell'HTML.
• Dry run prima di ogni importazione reale: righe da creare, da modificare, già presenti, conflitti ed errori, senza una sola scrittura. L'idempotenza è garantita da riferimento del lotto, UUID e hash del file e di ogni riga; il lettore XLSX integrato lavora in streaming senza mai eseguire formule e la protezione copre archivi malevoli e iniezione di formule CSV.

Procedura guidata di migrazione in 16 passi

La procedura accompagna dall'analisi dei prerequisiti al report finale: prerequisiti, negozio, scope, fonte (API o file), periodo, backup, abbinamenti, catalogo, clienti, giacenze, ordini, pagamenti, rimborsi, evasioni, riconciliazione e report.

• Recupero dello storico: tutti i dati accessibili, ultimi 12 o 24 mesi oppure periodo personalizzato; gli ordini sono caricati con un'operazione bulk filtrata per data di creazione. Oltre i 60 giorni Shopify richiede lo scope read_all_orders, da richiedere a Shopify: se manca, il modulo lo segnala chiaramente e resta possibile importare l'esportazione CSV degli ordini.
• Pagina «Pronti a lasciare Shopify?»: grado di completezza per ambito e anomalie residue. Misura la completezza tecnica e non afferma mai che il negozio possa essere chiuso automaticamente.
• Checklist di passaggio e report di migrazione in PDF: negozio, periodo, volumi, errori, avvisi, conflitti, differenze e stato finale.

Riconciliazione, conflitti e pilotaggio

• Centro di riconciliazione per clienti, prodotti, varianti, giacenze, ordini, importi, pagamenti, rimborsi ed evasioni, ad esempio: «Ordine #12580 — Shopify 1.250,00 € / Dolibarr 1.249,98 € — differenza e causa probabile». La riconciliazione completa pianificata individua oggetti mancanti, abbinamenti interrotti, pagamenti orfani ed evasioni incoerenti.
• Centro conflitti: oggetto, campo, valori dei due sistemi, date e origine; azioni «mantieni Shopify», «mantieni Dolibarr», «ultima modifica», «ignora», «crea regola». Una tabella dei dati non equivalenti documenta fonte, limite e alternativa.
• Shopify Commerce Sync Center, nei colori NEXT GESTION: negozi, clienti, prodotti, ordini, fatturato sincronizzato, pagamenti, rimborsi, evasioni, differenze di giacenza, coda, errori, conflitti e tasso di successo, con grafici integrati senza servizi esterni.
• Report su attività, vendite, ordini, clienti, prodotti, giacenze, pagamenti, rimborsi, spedizioni, sincronizzazioni e migrazione, esportabili in CSV, Excel (XLSX) e PDF. Completano il quadro i log (data, negozio, oggetto, ID Dolibarr e Shopify, direzione, azione, stato, durata; da DEBUG a CRITICAL), il centro di diagnostica e i dati dimostrativi, generati ed eliminati senza toccare i dati reali.

Sicurezza, GDPR e prestazioni

• Protezione CSRF, escaping sistematico dell'output contro l'XSS, query SQL protette, validazione degli input e protezione SSRF: vengono contattati solo i domini *.myshopify.com e gli host Shopify autorizzati. Gli upload sono controllati per tipo, dimensione, archivi e percorsi e conservati fuori dalla radice web; i segreti sono cifrati, mascherati ed esclusi dai log.
• GDPR: gestione delle richieste Shopify customers/data_request, customers/redact e shop/redact con esportazione, anonimizzazione, cancellazione controllata e cronologia delle richieste. 17 permessi Dolibarr distinti, dalla configurazione all'amministrazione.
• Prestazioni: GraphQL, operazioni bulk, paginazione a cursore, elaborazione a lotti, lettura dei file in streaming, indici SQL e sincronizzazione delta. Misure effettuate con file di test: lettura di 100.000 righe (20.000 prodotti) in circa 1,6 s con 4 MB di memoria di picco; ispezione e preparazione dello stesso volume in meno di 4 s con meno di 32 MB su Dolibarr 24.0.1 e 18.0.10. Le prestazioni reali dipendono dal server e dai limiti dell'API Shopify.

Verità tecnica: test e limiti

I test sono stati eseguiti con dati simulati: fixture, risposte GraphQL simulate e un server HTTP Shopify simulato. Alla data di questa descrizione non è stato effettuato alcun test su un negozio Shopify reale; tutti i risultati sono qualificati «TESTED WITH FIXTURES».

• Ambienti testati: Dolibarr 24.0.1, 22.0.5 e 18.0.10 con MySQL 8.4 e PHP 8.1 o 8.3 – test unitari e di integrazione, collaudo HTTP di tutte le pagine del modulo, ciclo di disattivazione e riattivazione senza perdita di dati.
• Dolibarr da 17 a 23 (escluse le versioni testate): probabilmente compatibili, non testate direttamente. Le versioni precedenti alla 17 sono rifiutate. PostgreSQL e MariaDB non sono testati: alcune query sono specifiche di MySQL.
• Storico oltre 60 giorni: richiede lo scope read_all_orders da richiedere a Shopify. Il B2B dipende dall'abbonamento Shopify e dagli scope corrispondenti.
• Non supportati: invio delle immagini Dolibarr verso Shopify, creazione di fatture, pagamenti o rimborsi lato Shopify, Shopify Markets, gift card, abbonamenti, carrelli abbandonati, REST Admin API e webhook tramite EventBridge o Pub/Sub.
• Parzialmente supportati: resi (monitoraggio e tracciabilità, senza nota di credito né movimento di magazzino generato dal reso), codici sconto (archiviazione consultabile), imposte su più giurisdizioni (riga all'aliquota più vicina con controllo dello scarto), collezioni automatiche (appartenenza calcolata da Shopify e importata in sola lettura) e metaobject (archiviazione JSON).
• Altri limiti: le modifiche agli ordini non vengono riportate su Shopify, dove è possibile creare solo bozze d'ordine; i prodotti con più di tre opzioni o 2.048 varianti non vengono inviati; i file JSON e JSONL non sono importabili e il formato XLS è limitato al BIFF8.

Il modulo non afferma mai di essere compatibile con tutte le versioni di Dolibarr e non promette mai la chiusura automatica del vostro negozio Shopify. I dettagli sono nel file COMPATIBILITY.md fornito con il modulo.

Compatibilità

Installazione e avvio

1. Prerequisiti: Dolibarr con i moduli Soggetti terzi, Prodotti e Ordini attivi, le estensioni PHP cURL, OpenSSL e ZipArchive e HTTPS per ricevere i webhook.
2. Impostazioni → Moduli → Distribuisci un modulo esterno, quindi caricare lo ZIP e attivare «NextShop Bridge»: tabelle, campi extra, modelli, permessi, menu e processi pianificati vengono creati automaticamente.
3. Assegnare i permessi, attivare il modulo Processi pianificati (cron), creare l'app Shopify con gli scope necessari, registrare il negozio, testare la connessione e sottoscrivere i webhook.
4. Configurare gli abbinamenti – direzioni, imposte, gateway, stati, corrieri, sedi e magazzini – e la regola di creazione delle fatture, quindi iniziare con un dry run.

Gli aggiornamenti del modulo applicano migrazioni SQL versionate e solo additive: nessun dato viene distrutto.

Fornitura e assistenza

Vengono forniti il modulo installabile (ZIP) con interfaccia in cinque lingue, il README, la guida alla migrazione, la matrice di compatibilità e di sincronizzazione, la documentazione tecnica e il manuale di formazione. NEXT GESTION offre assistenza, installazione, configurazione, formazione e sviluppi su misura: www.nextgestion.com.

NextShop Bridge — Copyright © NEXT GESTION — www.nextgestion.com — Tutti i diritti riservati.

Shopify è un marchio di Shopify Inc. Dolibarr è un marchio dell'associazione Dolibarr. Questi nomi sono citati solo per indicare la compatibilità; NextShop Bridge non è pubblicato né approvato da Shopify Inc. o dall'associazione Dolibarr.

Demo del modulo NextShop Bridge
Login : demo
Password : demo