DataFirefly Odoo Connector — guida all’installazione e alla configurazione

Questa guida copre l’installazione, la configurazione e l’utilizzo quotidiano del plugin DataFirefly Odoo Connector per Shopware 6.6 e 6.7. Alla fine, il tuo store sincronizzerà prodotti, magazzino, clienti e ordini con la tua istanza Odoo tramite XML-RPC nativo, senza alcuna dipendenza esterna e senza sovrapprezzo per API di terze parti.

Panoramica

Il plugin costruisce un ponte bidirezionale tra Shopware e Odoo parlando direttamente il protocollo XML-RPC di Odoo (stabile dalla versione 8). Nessun modulo da installare sul lato Odoo, nessun middleware a pagamento, nessun SaaS intermediario.

Requisiti

• Shopware 6.6.x o 6.7.x (tutte le versioni minori).
• PHP 8.2, 8.3 o 8.4.
• Estensioni PHP: curl, xml, simplexml (presenti per default sulla quasi totalità degli hosting).
• Odoo 12, 13, 14, 15, 16, 17 o 18, Community o Enterprise. Odoo.sh, Odoo Online (SaaS) e istanze self-hosted funzionano allo stesso modo.
• Un utente Odoo dedicato all’API (consigliato) con diritti di lettura/scrittura sui modelli utilizzati (product.template, product.product, res.partner, sale.order, stock.warehouse, product.category, res.country, account.tax).

Installazione

Tramite upload nell’amministrazione

1. Scarica DfOdooConnector-v1.0.0.zip dal tuo account cliente.
2. Nell’amministrazione Shopware: Estensioni → Le mie estensioni → Carica estensione.
3. Seleziona lo ZIP e clicca su Installa.
4. Attiva l’estensione tramite l’interruttore.

Tramite console SSH

cd /percorso/a/shopware
cp DfOdooConnector-v1.0.0.zip custom/plugins/
cd custom/plugins && unzip DfOdooConnector-v1.0.0.zip
sudo -u www-data setsid php bin/console plugin:refresh
sudo -u www-data setsid php bin/console plugin:install --activate DfOdooConnector
sudo -u www-data setsid php bin/console cache:clear

Ricompila l’amministrazione per caricare il modulo Vue 3:

sudo -u www-data setsid php bin/build-administration.sh

Configurazione lato Odoo

Creare un utente dedicato

Si consiglia vivamente di creare un utente Odoo dedicato all’integrazione invece di usare un account amministratore personale. Questo facilita l’audit delle azioni del connettore e permette di revocarne l’accesso indipendentemente.

1. In Odoo: Impostazioni → Utenti e aziende → Utenti.
2. Crea un utente chiamato per esempio Shopware Bridge.
3. Assegnagli i diritti necessari: Inventario (utente), Vendite (amministratore), Fatturazione (utente se attivi la creazione fattura), Contatti (utente).

Generare una chiave API

1. Accedi a Odoo con questo nuovo utente.
2. Clicca sull’avatar in alto a destra → Preferenze.
3. Scheda Account → Chiavi API → Nuova chiave API.
4. Dalle un nome descrittivo (per esempio Shopware Connector) e copia il valore generato.

Configurazione lato Shopware

Compilare la connessione

Nell’amministrazione Shopware: Impostazioni → Sistema → Plugin → Df Odoo → Impostazioni, oppure dal menu laterale Impostazioni → Df Odoo → Impostazioni.

• URL Odoo: URL completo della tua istanza senza slash finale, per esempio https://miaccount.odoo.com.
• Nome del database: visibile nell’URL di Odoo dopo ?db=, o in Impostazioni → Tecnico → Database.
• Utente: login dell’utente dedicato, di solito il suo indirizzo email.
• Chiave API Odoo: valore copiato al passaggio precedente.
• Timeout: 30 secondi per default, sufficiente nella maggior parte dei casi.

Testare la connessione

Clicca su Prova connessione in alto a destra. Se tutto è corretto, una notifica verde mostrerà la versione di Odoo e l’identificativo utente (uid). Se la connessione fallisce, il messaggio di errore restituito da Odoo viene mostrato così com’è.

Direzioni di sincronizzazione

Ogni entità ha il proprio selettore: disattivato, Odoo → Shopware (pull), Shopware → Odoo (push), o bidirezionale. I valori di default sono:

• Prodotti: bidirezionale
• Magazzino: Odoo → Shopware (Odoo è la fonte di verità)
• Clienti: Shopware → Odoo
• Ordini: Shopware → Odoo
• Categorie: disattivato (attivare manualmente secondo la tua organizzazione)

Sincronizzazione dei prodotti

Strategie di corrispondenza

Tre strategie configurabili:

• SKU (consigliata): Shopware productNumber ↔ Odoo default_code.
• ID Odoo: si basa solo sulla tabella di mapping persistente. Utile se le tue SKU sono volatili.
• Codice a barre (EAN): Shopware ean ↔ Odoo barcode. Richiede EAN su entrambi i lati.

Una volta collegati, due prodotti restano accoppiati tramite la tabella df_odoo_mapping, anche se la SKU cambia in seguito.

Pull da Odoo

L’attività pianificata legge i product.template modificati dall’ultima esecuzione (campo write_date) e crea o aggiorna i prodotti Shopware corrispondenti. I campi sincronizzati sono: nome, SKU, prezzo di vendita, prezzo di costo, descrizione breve, descrizione lunga, peso, volume, stato attivo, categoria, imposte.

Push verso Odoo

I prodotti master attivi di Shopware (con parentId = null) vengono inviati a Odoo come product.template di tipo product (articolo immagazzinabile). Le varianti Shopware vengono raggruppate sotto il loro prodotto padre.

Sincronizzazione del magazzino

Il magazzino è sempre tirato da Odoo (mai il contrario). Ogni 15 minuti, l’attività pianificata legge le varianti product.product in lotti di 100 per id template padre, aggrega qty_available o free_qty (configurabile globalmente) e aggiorna il campo stock di ogni prodotto Shopware in un’unica richiesta DAL.

Sincronizzazione delle categorie

Disattivata per default. Attivala se il tuo albero di categorie deve rimanere sincrono con quello di Odoo. La gerarchia parent_id viene preservata su entrambi i lati. Come per i prodotti, un hash di contenuto evita scritture inutili.

Sincronizzazione dei clienti

I clienti Shopware vengono inviati come res.partner Odoo con:

• Deduplicazione tramite email: prima di ogni creazione, viene cercato un partner esistente con la stessa email e parent_id = false. Se esiste, viene aggiornato invece che duplicato.
• company_type: company se il campo azienda dell’indirizzo di fatturazione è compilato, person altrimenti.
• Indirizzi figli: l’indirizzo di fatturazione predefinito viene creato come partner figlio con type='invoice', l’indirizzo di spedizione come partner figlio con type='delivery'.
• Partita IVA intracomunitaria: riportata sul campo vat del partner principale.
• Nazione e regione: risolti per codice ISO con cache in memoria per richiesta.

Sincronizzazione degli ordini

In tempo reale al checkout

Se l’opzione Inviare ogni ordine alla conferma è attivata, un event subscriber ascolta CheckoutOrderPlacedEvent e invia l’ordine a Odoo immediatamente dopo la finalizzazione del checkout. Il cliente viene creato in Odoo se necessario (tramite la sincronizzazione clienti), poi l’ordine viene creato come sale.order con:

• partner_id risolto tramite il mapping cliente.
• order_line in sintassi tuple di Odoo: [0, 0, {name, product_uom_qty, price_unit, product_id}].
• Una riga aggiuntiva per le spese di spedizione se il totalPrice dello shipping è maggiore di zero.
• company_id, warehouse_id, pricelist_id secondo i valori predefiniti configurati.

Filtro di stato

L’impostazione Filtro di stato degli ordini restringe quali ordini vengono inviati:

• Tutti: ogni ordine confermato viene inviato (consigliato in B2C con pagamento immediato).
• Solo pagati: solo gli ordini con stato di pagamento paid vengono inviati. Evita che carrelli abbandonati con pagamento manuale sporchino Odoo.
• Pagati o spediti: aggiunge anche gli ordini spediti prima del pagamento (B2B con dilazione).

Conferma e fattura automatiche

Due opzioni controllano cosa succede lato Odoo una volta creato l’ordine:

• Confermare l’ordine: chiama action_confirm sul sale.order, che passa direttamente allo stato ordine confermato invece di restare come preventivo.
• Creare la fattura: chiama _create_invoices per generare immediatamente una fattura validata. L’ID della fattura creata viene memorizzato come mapping di tipo invoice.

Multi canale di vendita

Tutte le impostazioni del plugin possono essere sovrascritte per canale di vendita. In alto nella pagina Impostazioni, il selettore nativo di Shopware permette di alternare tra Tutti i canali e un canale specifico.

Casi d’uso tipici:

• Un canale B2C che invia a un Odoo principale e un canale B2B che invia a un Odoo distinto.
• Un canale di produzione con direzione push e un canale di staging con direzione disattivata.
• Diversi ID Odoo (warehouse, sales team, pricelist) secondo il canale.

Attività pianificate

Forzare l’esecuzione di un’attività dalla console:

sudo -u www-data setsid php bin/console scheduled-task:run-single df_odoo.product_sync

Modulo di amministrazione

Una sezione Df Odoo appare in Impostazioni → Plugin con quattro pagine.

Cruscotto

Contatori live (corrispondenze attive per entità, attività delle ultime 24h per stato), pulsanti di sincronizzazione manuale per entità (pull e push), banner di stato della connessione, lista degli errori recenti e scorciatoie verso le altre pagine.

Impostazioni

Modulo completo con selettore di canale di vendita. Pulsanti Prova connessione e Salva nella barra delle azioni.

Log

Ogni operazione è registrata in df_odoo_log con il suo stato (success, error, warning, skipped), direzione, entità, durata in millisecondi e messaggio completo. Filtri combinabili per stato, tipo di entità e direzione. Paginazione lato server.

Corrispondenze

Vista di sola lettura sulla tabella df_odoo_mapping con ricerca, filtro per tipo di entità e ordinamento per data dell’ultima sincronizzazione. Comoda per verificare che un dato prodotto sia mappato all’ID Odoo atteso.

API REST di amministrazione

Tutti gli endpoint richiedono autenticazione admin standard (Bearer token).

Esempio di chiamata per forzare un push prodotti:

curl -X POST 
  -H "Authorization: Bearer ADMIN_TOKEN" 
  -d "direction=push" 
  https://tuoshopware.com/api/_action/df-odoo/sync/products

Tabelle e dati memorizzati

Il plugin crea due tabelle MySQL:

• df_odoo_mapping — corrispondenze persistenti (id Shopware ↔ id Odoo) con hash di sincronizzazione e payload opzionale. Una riga è unica per (tipo di entità, id Shopware) e per (tipo di entità, id Odoo).
• df_odoo_log — registro delle operazioni con stato, durata, messaggio, payload, id del canale di vendita.

Nessuna tabella standard di Shopware viene modificata.

Disinstallazione

Dall’amministrazione: Estensioni → Le mie estensioni → Df Odoo → Disinstalla.

Una finestra di dialogo offre due opzioni:

• Conservare i dati utente selezionato: le tabelle df_odoo_mapping e df_odoo_log vengono preservate, così come le impostazioni di sistema. Comodo per una reinstallazione successiva.
• Conservare i dati utente deselezionato: entrambe le tabelle vengono eliminate (DROP TABLE) alla disinstallazione. L’istanza Odoo non viene mai toccata.

Risoluzione dei problemi

«Configurazione Odoo incompleta» al test di connessione

Uno dei quattro campi obbligatori (URL, database, utente, chiave API) è vuoto. Verifica di aver selezionato il canale di vendita corretto prima di salvare.

«401 Unauthorized» o «access denied»

La chiave API è stata revocata lato Odoo, o l’utente non ha i diritti necessari sul modello target. Rigenera una chiave API e verifica i diritti Odoo dell’utente (in particolare Inventario → Utente e Vendite → Amministratore).

«Connessione rifiutata» o timeout

L’URL Odoo non è raggiungibile dal server Shopware. Verifica che il firewall autorizzi le connessioni in uscita HTTPS verso il dominio Odoo. Aumenta il timeout se la tua istanza Odoo è lenta a rispondere.

I prodotti non si sincronizzano

Verifica il registro (pagina Log) per voci in errore. Attiva la modalità debug per tracciare anche le operazioni skipped e identificare se l’hash di contenuto fa sì che nulla cambi davvero.

Gli ordini non partono al checkout

Verifica che l’opzione Inviare ogni ordine alla conferma sia attivata e che la direzione Ordini sia su Shopware → Odoo. Se il filtro di stato è su Solo pagati e il pagamento è asincrono, è l’attività pianificata che invia l’ordine pochi minuti dopo l’incasso.

Limitazioni note

• Gli attributi di varianti Odoo (product.attribute) non sono ancora mappati automaticamente. Le varianti Shopware vengono raggruppate come prodotti padre Odoo (product.template). Le varianti Odoo create manualmente restano correttamente collegate tramite il loro template padre. Una gestione nativa è prevista nella versione 1.1.
• Gli sconti di riga d’ordine vengono riportati come price_unit rettificato, non come il campo discount di Odoo.
• I metodi di pagamento e spedizione di Shopware non vengono mappati sui journal_id di Odoo — si usano i valori di default di Odoo.

Supporto

Per qualsiasi domanda, contatta il team DataFirefly tramite il modulo di contatto su datafirefly.com. Allega l’esportazione del registro (pagina Log → pulsante di esportazione in arrivo) o almeno uno screenshot della riga in errore, con la versione esatta di Shopware, PHP e Odoo.