PrestaNexus — Sincronizzazione Dolibarr ⇄ PrestaShop

Il ponte ERP / e-commerce completo e bidirezionale tra Dolibarr ERP/CRM e uno o più negozi PrestaShop.

1. Presentazione

PrestaNexus trasforma Dolibarr nel vero back office della vostra attività PrestaShop. Clienti, indirizzi, catalogo, combinazioni, giacenze, prezzi, ordini, fatture, pagamenti, note di credito e spedizioni vengono scambiati automaticamente tra le due applicazioni, nella direzione scelta per ogni tipo di dato.

Progettato per la produzione, il modulo si basa su un motore di sincronizzazione professionale: coda persistente, tentativi automatici, protezione da duplicati e cicli, gestione dei conflitti, simulazione prima dell'importazione e registro completo. Funziona senza alcuna modifica al nucleo di Dolibarr o di PrestaShop.

2. Punti di forza

• Sincronizzazione bidirezionale configurabile oggetto per oggetto: Dolibarr → PrestaShop, PrestaShop → Dolibarr o in entrambi i sensi.
• Fonte di riferimento per ogni tipo di dato: Dolibarr, PrestaShop, ultima modifica o convalida manuale.
• Multi-negozio: più negozi PrestaShop collegati contemporaneamente, ciascuno con chiave, lingua, valuta, magazzino, regole e associazioni propri.
• Nessun duplicato: ogni ordine, fattura, pagamento o nota di credito viene creato una sola volta, anche se l'evento arriva più volte.
• Tempo reale e pianificato: trigger Dolibarr, webhook PrestaShop firmati e attività CRON di recupero (sincronizzazione delta).
• Grandi volumi: elaborazione a lotti, paginazione e rilevamento delle modifiche tramite impronta, per centinaia di migliaia di prodotti, clienti e ordini.
• Sicurezza: chiavi API cifrate (AES-256-GCM), webhook HMAC, protezione CSRF, permessi utente dettagliati, segreti mascherati nei registri.
• Compatibilità multi-versione grazie a un'architettura ad adattatori per Dolibarr e PrestaShop.

3. Funzionalità in dettaglio

3.1 Connessione e multi-negozio

• Procedura guidata di connessione: URL, chiave Webservice, negozio e gruppo di negozi, lingua, valuta, magazzino, livello di prezzo, modalità di sincronizzazione.
• Pulsante «Verifica connessione»: versione di PrestaShop, adattatore utilizzato, nome del negozio, lingue, valute, multinegozio, volumi e permessi Webservice mancanti.
• Rilevazione automatica che precompila le associazioni: lingue, valute, imposte, corrieri, stati degli ordini e gruppi di clienti.
• Procedura guidata di prima sincronizzazione in 10 passaggi, dalla connessione all'importazione iniziale.

3.2 Catalogo

• Prodotti e servizi: riferimento, EAN, UPC, ISBN, MPN, nome, descrizioni, peso e dimensioni, costo, stato, categorie, marca, campi SEO e traduzioni.
• Combinazioni PrestaShop sincronizzate con le varianti Dolibarr: attributi, valori, riferimento, EAN, impatto su prezzo e peso.
• Categorie con albero completo e categoria principale.
• Marche e produttori, rappresentati in Dolibarr come categorie dedicate.
• Immagini principali e secondarie, con rilevamento dell'impronta per non inviare mai due volte la stessa immagine.
• Filtri: solo alcune categorie, solo prodotti attivi, per tipo di prodotto.

3.3 Giacenze

• Modalità Dolibarr principale, PrestaShop principale o bidirezionale.
• Giacenza reale o virtuale, calcolata su uno o più magazzini Dolibarr (più magazzini possono alimentare lo stesso negozio).
• Protezione anti-ciclo: una quantità inviata a PrestaShop non viene mai reimportata come nuova modifica.

3.4 Prezzi e imposte

• Prezzo al netto delle imposte come riferimento, livelli di prezzo Dolibarr, prezzi specifici per cliente.
• Associazione delle regole fiscali PrestaShop alle aliquote IVA Dolibarr per paese, senza mai creare aliquote duplicate.
• Calcoli decimali esatti senza errori di arrotondamento, supporto multivaluta.

3.5 Clienti, contatti e indirizzi

• Creazione automatica dei soggetti terzi Dolibarr a partire dai clienti PrestaShop, privati e aziende (ragione sociale, numero di registro, partita IVA).
• Strategie anti-duplicati: ID esterno, e-mail, partita IVA, numero di registro, riferimento; i casi ambigui vengono segnalati invece di creare un duplicato.
• Indirizzi di fatturazione e di consegna sincronizzati con i contatti Dolibarr.
• Opzione per creare automaticamente un account PrestaShop per ogni nuovo cliente Dolibarr.

3.6 Ordini e stati

• Importazione automatica degli ordini PrestaShop: cliente, indirizzi, righe e combinazioni, sconti, spese di spedizione, confezione regalo, messaggio, metodo di pagamento, corriere e valuta.
• Controllo dei totali: ogni differenza tra PrestaShop e Dolibarr viene segnalata nella nota dell'ordine.
• Prodotti sconosciuti: riga libera, importazione del prodotto o blocco con errore, a scelta.
• Schermata di associazione degli stati: ogni stato PrestaShop attiva un'azione Dolibarr (convalida, annulla, chiudi…) e ogni evento Dolibarr può aggiornare lo stato PrestaShop.

3.7 Fatture, pagamenti e note di credito

• Fattura Dolibarr creata automaticamente secondo la regola scelta: ordine convalidato, pagamento accettato, ordine spedito o consegnato.
• Importazione dei pagamenti con associazione dei metodi di pagamento (Stripe, PayPal, bonifico, contrassegno…) e del conto bancario; nessun pagamento viene registrato due volte né oltre l'importo residuo.
• Note di credito PrestaShop importate come note di credito Dolibarr, con reintegro facoltativo della giacenza.

3.8 Spedizioni e tracciamento

La convalida di una spedizione in Dolibarr aggiorna l'ordine PrestaShop: numero di tracciamento, corriere e stato «Spedito», con invio facoltativo dell'e-mail al cliente.

3.9 Associazioni e regole di business

• Associazione dei valori: stati, metodi di pagamento, imposte, corrieri, magazzini, lingue, valute, gruppi di clienti.
• Editor di associazione dei campi: extrafield Dolibarr ⇄ campi PrestaShop, con conversione testo, numero, data, booleano, elenco o JSON.
• Motore di regole senza codice, ad esempio: «se il negozio è Francia e l'ordine supera 500 €, assegna il commerciale X».

3.10 Affidabilità e prestazioni

• Coda persistente: nessuna sincronizzazione pesante viene eseguita durante una richiesta web.
• Tentativi automatici con attesa esponenziale; un'operazione non riuscita non viene mai persa e può essere rilanciata.
• Attività isolate: un errore su un prodotto non interrompe mai la sincronizzazione degli altri.
• Idempotenza, rilevamento delle modifiche tramite impronta, sincronizzazione delta.
• Centro conflitti: valore Dolibarr, valore PrestaShop e valore precedente affiancati, risoluzione con un clic.
• Limitazione della frequenza e interruttore di sicurezza per non sovraccaricare mai il negozio; ripresa graduale dopo un'interruzione.
• Modalità simulazione: numero di elementi da creare, aggiornare, invariati, in conflitto o in errore, senza modificare alcun dato.

3.11 Monitoraggio

Commerce Sync Control Center — schermata reale del modulo in Dolibarr 23.0.4.

• Commerce Sync Control Center: indicatori chiave, grafici a 30 giorni, attività recente, ultimi errori e attività pianificate.
• Sincronizzazione manuale per tipo di oggetto, cronologia dei lotti, coda, registri filtrabili ed esportabili in CSV.
• Schede PrestaShop nelle schede prodotto, soggetto terzo, ordine e fattura.
• Report: fatturato, carrello medio, nuovi clienti, prodotti più venduti, esaurimenti, tassi di annullamento e di rimborso.
• Diagnostica, monitor di stato e console di amministrazione.

3.12 Sicurezza e GDPR

• 12 permessi Dolibarr distinti: lettura, amministrazione, sincronizzazione per ambito, registri, conflitti, rilanci, associazioni, pulizia.
• Le cancellazioni non vengono mai propagate per impostazione predefinita: si privilegiano archiviazione o disattivazione.
• Esportazione e anonimizzazione dei dati di sincronizzazione di un cliente; notifiche agli amministratori (e-mail, agenda, webhook).

4. Matrice di sincronizzazione

La direzione di ogni oggetto si imposta negozio per negozio. «—» indica un'operazione non consentita dalle API (ad esempio, il Webservice PrestaShop non permette di creare una fattura).

5. Requisiti

• Dolibarr 17 o superiore, PHP 7.1 o superiore con le estensioni curl, openssl, json, dom, simplexml e mbstring.
• Moduli Dolibarr: Soggetti terzi, Prodotti, Ordini, Fatture e Attività pianificate; facoltativi: Magazzino, Varianti, Multivaluta, Banche.
• PrestaShop da 1.6.1 a 9.x con Webservice attivo e chiave API con i permessi necessari; HTTPS consigliato.
• Per il tempo reale: il modulo complementare PrestaShop «nxwebhook» fornito.

6. Installazione

• In Dolibarr: Home → Impostazioni → Moduli → Distribuisci/installa un modulo esterno, quindi caricare il file prestanexus-1.0.zip.
• Attivare il modulo PrestaNexus nell'elenco dei moduli.
• In PrestaShop: attivare il Webservice e creare una chiave API con i permessi indicati nel manuale.
• In Dolibarr: PrestaShop → Configurazione → Connessioni → Nuova connessione, quindi «Verifica connessione».
• Avviare la procedura guidata di prima sincronizzazione (associazioni, simulazione, importazione iniziale).
• Verificare che le attività pianificate di Dolibarr vengano eseguite (crontab di sistema) e, per il tempo reale, installare il modulo complementare nxwebhook.

7. Compatibilità

Il codice è fornito con 469 test automatici (motore, API, servizi di business). La matrice dettagliata si trova in docs/TEST_MATRIX.md.

8. Limitazioni note

• Le password dei clienti non possono essere trasferite: il cliente utilizza «password dimenticata».
• I resi merce di PrestaShop non sono esposti dal Webservice: vengono gestiti tramite le note di credito.
• La giacenza dei prodotti gestiti per lotto o numero di serie non può essere corretta da PrestaShop.
• Le regole di prezzo del catalogo e i codici promozionali non hanno equivalente in Dolibarr: vengono importati come sconti sugli ordini.

9. Domande frequenti

Il modulo modifica Dolibarr o PrestaShop?

No. Utilizza esclusivamente meccanismi ufficiali: modulo, trigger, hook, Webservice e un modulo complementare PrestaShop standard.

Un ordine può essere importato due volte?

No. Ogni ordine è identificato in modo univoco; lo stesso evento ricevuto più volte non crea mai un duplicato.

Cosa succede se il negozio non è disponibile?

Le attività restano in coda, l'interruttore di sicurezza sospende le chiamate e poi riprende gradualmente, senza perdite né duplicati.

Posso fare una prova prima di importare i dati?

Sì, la modalità simulazione mostra cosa verrebbe creato, aggiornato o in conflitto senza modificare nulla.

Posso collegare più negozi?

Sì, senza limiti, ciascuno con la propria configurazione.

10. Editore e assistenza

NEXT GESTION — www.nextgestion.com — contact@nextgestion.com

Distribuito con licenza GPL v3 o successiva. Documentazione completa in francese e inglese inclusa (manuale PDF).

Demo del modulo PrestaNexus
Login : demo
Password : demo