Sincronizzazione affidabile e tracciabile tra Dolibarr ERP/CRM e WordPress/WooCommerce

DoliCommerce Bridge: sincronizzazione Dolibarr ⇄ WooCommerce affidabile, tracciabile e sotto il vostro controllo

Gestite la vostra azienda con Dolibarr ERP/CRM e vendete online con WordPress e WooCommerce? Allora conoscete bene il dilemma: ridigitare a mano ordini, giacenze e prezzi, oppure affidarsi a uno script fragile che nessuno osa toccare. DoliCommerce Bridge, il modulo Dolibarr sviluppato da NextGestion, sostituisce entrambe le soluzioni con un motore di sincronizzazione strutturato e verificabile, che vive interamente all'interno di Dolibarr.

Clienti, prodotti, varianti, stock, prezzi, ordini, fatture, pagamenti, rimborsi e spedizioni circolano tra Dolibarr e WooCommerce attraverso una coda sicura, con le direzioni e le fonti di verità che decidete voi.

Presentazione del modulo

DoliCommerce Bridge collega un'entità Dolibarr a un numero illimitato di negozi WooCommerce. Ogni connessione dispone di credenziali, perimetro del catalogo, magazzini, valuta, lingua, livello di prezzo, mappature, regole, coda, registri, webhook e pianificazioni propri.

Il modulo dialoga con WooCommerce tramite l'API REST ufficiale v3 (wc/v3), con WordPress tramite l'API wp/v2 e riceve i webhook WooCommerce firmati. Non è necessario installare alcun plugin WordPress e nessun file del core di Dolibarr, WordPress o WooCommerce viene modificato.

Ogni modifica, che provenga da un trigger Dolibarr, da un webhook, da un delta pianificato o da un clic nell'interfaccia, diventa un job in una coda persistente. Un worker eseguito dai processi pianificati di Dolibarr elabora la coda con tentativi ripetuti, backoff esponenziale, limitatore di frequenza e circuit breaker per connessione. Nessuna chiamata remota avviene mentre un utente salva una scheda Dolibarr o mentre WooCommerce consegna un webhook: nessuno dei due sistemi rallenta l'altro.

Vantaggi chiave

• Basta ridigitare gli ordini. Gli ordini WooCommerce pagati arrivano in Dolibarr con righe, imposte, spese di spedizione, fattura e pagamento secondo le vostre regole.
• Vendete solo ciò che avete. I movimenti di magazzino Dolibarr vengono inviati al negozio in pochi minuti, con scorta di sicurezza se necessario.
• Una contabilità pulita. Le chiavi di idempotenza impediscono i duplicati, la verifica degli importi impedisce le discrepanze silenziose, i rimborsi diventano note di credito.
• Siete voi a decidere chi comanda. Direzioni e fonti di verità si impostano per famiglia e per campo, senza scelte imposte dallo strumento.
• Resistente agli imprevisti reali. Negozio non raggiungibile, credenziali scadute, webhook perso, CRON fermo: i job attendono, vengono ritentati o finiscono in una dead letter queue da correggere e rilanciare.
• Visibilità totale. Dashboard, metriche di salute, identificativi di correlazione nei registri, controlli diagnostici e report per sito.
• Pronto per più negozi. Un solo Dolibarr, più siti WooCommerce, ciascuno con la propria configurazione.
• Messa in produzione sicura. La procedura guidata termina con una simulazione che mostra esattamente cosa verrebbe creato, aggiornato o messo in conflitto.

Funzionalità dettagliate

Clienti e soggetti terzi

• Clienti WooCommerce ⇄ soggetti terzi Dolibarr, con contatti di fatturazione e di spedizione.
• Deduplicazione per ID remoto, e-mail, riferimento e partita IVA; le corrispondenze ambigue non vengono mai selezionate automaticamente.
• Ordini degli ospiti: un soggetto terzo per e-mail (chiave hash) oppure un soggetto terzo generico.
• Rilevamento B2B quando il campo azienda è compilato; mappatura dei ruoli WordPress verso tipo di soggetto terzo, gruppo, livello di prezzo e categoria.

Catalogo e varianti

• Prodotti semplici, servizi (come prodotti virtuali), prodotti variabili e variazioni, tramite il modulo Varianti o in modalità "prodotti separati".
• Albero delle categorie, tag prodotto (come categorie Dolibarr sotto la radice "WooCommerce Tags"), attributi globali e termini.
• Immagini principali, di galleria e di variazione, con hash SHA-256 per evitare nuovi invii e download protetto in importazione.
• Peso e dimensioni con conversione automatica delle unità; codici a barre EAN/GTIN (global_unique_id, WooCommerce 9.2 o superiore).
• Dati di prodotti raggruppati, esterni, scaricabili, upsell e cross-sell conservati nei metadati di mappatura.
• Gestione configurabile dei prodotti eliminati: mai una cancellazione automatica in Dolibarr.

Stock multi-magazzino e prezzi

• Invio delle giacenze con modalità magazzino singolo, somma dei magazzini o personalizzata (coefficiente e scorta di sicurezza).
• La ricezione dello stock da WooCommerce genera un vero movimento di magazzino in Dolibarr.
• Prezzi di listino con base IVA esclusa o inclusa secondo l'impostazione fiscale di WooCommerce.
• Prezzi in offerta tramite il campo extra dcb_sale_price o un livello di prezzo dedicato.
• Prezzi per ruolo tramite l'adattatore di un plugin B2B rilevato.

Ordini, fatture, pagamenti e rimborsi

• Importazione degli ordini via webhook più delta ogni 5 minuti, filtrata per stato e data minima.
• Righe con prodotti, variazioni, SKU, quantità, prezzi unitari, imposte, sconti, spese di spedizione, commissioni e coupon.
• Mappatura configurabile degli stati d'ordine in entrambe le direzioni.
• Creazione automatica della fattura secondo un evento scelto: creazione, pagamento, in lavorazione, completato, spedito o mai.
• Pagamenti derivati dall'ordine: data di pagamento, ID transazione, gateway associato a tipo di pagamento e conto bancario.
• Rimborsi totali o parziali (quantità, spedizione, commissioni, imposte, motivo) trasformati in note di credito, con reintegro opzionale dello stock.
• Valuta e importi originali conservati, con applicazione del tasso multivaluta di Dolibarr.
• Protezione finanziaria: chiavi di idempotenza e confronto dei totali (tolleranza predefinita 0,02); ogni scostamento apre un conflitto finanziario e un avviso. Nessun rimborso bancario reale viene mai attivato automaticamente.

Spedizioni e tracking

• La convalida o la chiusura di una spedizione Dolibarr completa l'ordine WooCommerce quando tutto è stato spedito.
• Numero di tracking inviato a Shipment Tracking, Advanced Shipment Tracking oppure a un metadato generico con nota all'ordine.
• Mappatura dei metodi di spedizione per istanza di zona verso i metodi di spedizione Dolibarr.

Imposte e coupon

• Aliquote e classi di imposta WooCommerce importate come suggerimenti di mappatura verso le aliquote IVA Dolibarr.
• Coupon applicati riportati come sconto sulle righe con nota; definizioni dei coupon conservate in una tabella specchio.

Corrispondenze e fonti di verità

• Direzione per famiglia: Dolibarr verso WooCommerce, WooCommerce verso Dolibarr, bidirezionale, solo manuale o disattivata.
• Fonte di verità per campo: Dolibarr, WooCommerce, il più recente o sempre manuale. Impostazioni predefinite: Dolibarr governa catalogo, stock e prezzi; WooCommerce governa clienti e ordini.
• Fusione a tre vie a livello di campo rispetto all'ultimo stato sincronizzato.
• Motore di regole (SE condizioni ALLORA azioni) e mappature modificabili: stati, imposte, pagamenti, spedizioni, magazzini, campi, ruoli.
• Scheda "WordPress / WooCommerce" sulle schede prodotto, soggetto terzo, ordine e fattura, con il pulsante "Sincronizza ora".

Centro conflitti

Quando entrambi i lati modificano lo stesso oggetto e la fonte di verità non permette di decidere, la differenza arriva nel Centro conflitti: un utente autorizzato mantiene il valore Dolibarr, mantiene il valore WooCommerce oppure ignora la differenza. I conflitti finanziari vengono segnalati allo stesso modo, invece di essere convalidati in silenzio.

Coda, retry, webhook e CRON

• Coda persistente con priorità, accorpamento, dead letter queue, modifica del payload e rimessa in coda.
• Backoff esponenziale con jitter, limitatore di frequenza, circuit breaker e recupero dei job bloccati.
• Cinque barriere anti-loop e operazioni finanziarie eseguite una sola volta.
• Ricevitore di webhook firmati con registrazione e riparazione automatiche; deduplicazione tramite Delivery-ID.
• Delta pianificati (5 minuti per gli ordini, 10 per lo stock) e riconciliazione notturna di oggetti mancanti, mappature interrotte e scostamenti di stock, prezzi e importi.

Dashboard, registri, diagnostica e reportistica

• Dashboard con metriche di salute e notifiche; registri dettagliati con identificativi di correlazione e mascheramento GDPR.
• Pagina di diagnostica con quindici gruppi di controlli.
• Reportistica multi-sito con esportazioni e sincronizzazione massiva.

Procedura guidata di prima sincronizzazione e simulazione

Una procedura guidata in 14 passaggi accompagna la messa in servizio: connessione, parametri generali, direzioni e fonti di verità, mappature di stati, imposte, pagamenti e spedizioni, magazzini, filtri e regole, abbinamento dei dati esistenti. La simulazione (dry-run) non scrive nulla, né in Dolibarr né in WooCommerce né nelle tabelle di mappatura, e riporta per ogni oggetto: creazione, aggiornamento, invariato, conflitto o ignorato.

Multi-negozio

• Negozi WooCommerce illimitati per entità Dolibarr, compatibile con la multi-società.
• Autenticazione HTTP Basic (HTTPS), chiavi in query string (HTTPS, per server che rimuovono l'intestazione Authorization) oppure OAuth 1.0a (HTTP semplice, sconsigliato).
• Test di connessione con rilevamento delle capacità: versioni WordPress/WooCommerce, HTTPS, permalink, valuta, imposte, gestione dello stock, HPOS, stati d'ordine, gateway di pagamento, metodi di spedizione, plugin rilevati.
• Stato della connessione Attiva, In pausa o Disattivata: la pausa rinvia i job senza perderli.

Sicurezza e GDPR

• Segreti cifrati con AES-256-GCM tramite una chiave derivata dall'identificativo univoco dell'istanza Dolibarr (mai salvata nel database), mascherati a schermo e mai registrati nei log.
• Dati personali mascherati nei registri per impostazione predefinita; registri eliminati dopo 90 giorni e job completati dopo 14 giorni.
• Clienti ospiti raggruppati tramite e-mail con hash.
• Diritti Dolibarr dedicati: configurazione, connessioni, famiglie di sincronizzazione, registri, conflitti, coda, mappature, reportistica.

Riepilogo delle sincronizzazioni

Abbreviazioni: REST = API WooCommerce wc/v3; WP = API WordPress wp/v2; WH = webhook WooCommerce; TRG = trigger Dolibarr; CRON = processi pianificati. Le direzioni sono configurabili per famiglia e per connessione.

Requisiti

• Dolibarr 17.0 o superiore.
• PHP da 7.4 a 8.4 con le estensioni curl, json, openssl e mbstring.
• MySQL o MariaDB.
• WordPress con WooCommerce e la sua API REST v3; HTTPS fortemente consigliato.
• WordPress 5.6 o superiore per le password per le applicazioni (caricamento media, utenti WordPress); WooCommerce 9.2 o superiore per i codici GTIN nativi.
• Una chiave API WooCommerce il cui proprietario abbia diritti di gestore del negozio o amministratore.
• Moduli Dolibarr: Soggetti terzi e Prodotti; secondo l'uso Magazzini, Ordini, Fatture, Spedizioni, Varianti, Multivaluta, Categorie, Banca e Processi pianificati (obbligatorio per il worker), con un crontab di sistema eseguito ogni minuto.

Installazione

1. Copiate la cartella dolicommercebridge in htdocs/custom/ oppure distribuite l'archivio da Home → Impostazioni → Moduli → Distribuisci modulo esterno.
2. Attivate DoliCommerce Bridge, il modulo Processi pianificati e i moduli Dolibarr necessari.
3. Assegnate i diritti del modulo agli utenti interessati in Utenti e gruppi.
4. Aggiungete la riga del crontab di sistema che richiama scripts/cron/cron_run_jobs.php ogni minuto.
5. In WooCommerce create una chiave API in lettura/scrittura e, se serve il caricamento delle immagini, una password per le applicazioni WordPress.
6. Aprite il menu Commerce Sync, avviate la procedura guidata e testate la connessione.
7. Configurate direzioni, mappature, magazzini e regole, quindi eseguite la simulazione.
8. Passate in produzione: la procedura guidata mette in coda l'importazione/esportazione iniziale, registra i webhook e attiva la connessione.
9. Convalidate tutto su una copia di staging prima di collegare il negozio di produzione.

Compatibilità: trasparenza totale

La versione 1.0 è coperta da una suite di test automatizzati eseguita su PHP 8.3 con SQLite, doppioni in memoria di Dolibarr e WooCommerce e un trasporto HTTP simulato. Nessun test di esecuzione è stato effettuato su un'installazione reale di Dolibarr, WordPress o WooCommerce.

• Dolibarr 17 – 22 e PHP 7.4 – 8.4: supportati per progettazione, non testati su istanze reali. Dolibarr inferiore alla 17: non compatibile.
• WooCommerce 8.x / 9.x con API REST v3, con o senza HPOS: probabilmente compatibile tramite gli endpoint standard. API legacy v1/v2: non compatibili.
• Plugin di tracking, SEO (Yoast, Rank Math), traduzione (WPML, Polylang) e B2B: adattatori basati sul rilevamento, non testati.
• PrestaShop, Shopify, Magento: non compatibili nella 1.0.

Vi consigliamo vivamente un collaudo completo in ambiente di staging prima della messa in produzione.

Lingue dell'interfaccia

Francese, inglese, spagnolo, tedesco e italiano.

Contenuto del pacchetto

• Il modulo Dolibarr DoliCommerce Bridge 1.0 (licenza GPL v3 o successiva).
• La documentazione tecnica e utente, inclusa la matrice di sincronizzazione.
• Un manuale di formazione.

Domande frequenti

Devo installare un plugin su WordPress?

No. Il modulo utilizza l'API REST standard di WooCommerce v3, l'API REST di WordPress e i webhook WooCommerce. Basta creare una chiave API e, per le immagini, una password per le applicazioni.

La sincronizzazione è in tempo reale?

Quasi in tempo reale. Webhook e trigger Dolibarr mettono subito i job in coda e il worker gira ogni minuto; i delta pianificati recuperano ciò che un webhook avesse perso.

Posso collegare più negozi a un solo Dolibarr?

Sì. Ogni connessione ha credenziali, perimetro, magazzini, valuta, lingua, livello di prezzo, mappature, regole, coda, registri e webhook propri.

Un webhook ripetuto può creare una fattura o un pagamento doppio?

No. Ordini, fatture, pagamenti, rimborsi, note di credito e spedizioni usano chiavi di idempotenza e le consegne dei webhook sono deduplicate.

Il modulo rimborsa automaticamente i miei clienti?

No. Un rimborso WooCommerce diventa una nota di credito Dolibarr. Un rimborso reale tramite gateway è disattivato per impostazione predefinita e richiede una configurazione esplicita.

Come viene gestito lo stock con più magazzini Dolibarr?

WooCommerce ha un solo stock per prodotto: scegliete un magazzino singolo, la somma dei magazzini o una mappatura personalizzata con coefficienti e scorta di sicurezza.

Cosa succede se il negozio non è raggiungibile o la chiave API scade?

Gli errori di rete e 5xx vengono ritentati con backoff esponenziale e il circuit breaker sospende le chiamate. Le credenziali non valide (401/403) inviano i job nella dead letter queue con un avviso critico.

Il modulo è stato testato su negozi reali?

Non ancora: la versione 1.0 è verificata da test automatizzati. Consultate la sezione Compatibilità e convalidate prima su una copia di staging.

Supporto NextGestion

DoliCommerce Bridge è pubblicato e supportato da NextGestion, specialista delle soluzioni Dolibarr. Per domande, assistenza all'installazione o accompagnamento nella messa in produzione, visitate https://www.nextgestion.com.

Demo del modulo DoliCommerce Bridge (WordPress / WooCommerce)
Login : demo
Password : demo