# 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…

- Pagina: <https://www.datafirefly.com/it/documentation/df-odoo-connector/>
- Lingua: it
- Aggiornato il: 2026-06-29
- Altre lingue: [fr](https://www.datafirefly.com/documentation/df-odoo-connector/index.md), [en](https://www.datafirefly.com/en/documentation/df-odoo-connector/index.md), [es](https://www.datafirefly.com/es/documentation/df-odoo-connector/index.md), [de](https://www.datafirefly.com/de/documentation/df-odoo-connector/index.md), [pl](https://www.datafirefly.com/pl/documentation/df-odoo-connector/index.md), [nl](https://www.datafirefly.com/nl/documentation/df-odoo-connector/index.md), [pt](https://www.datafirefly.com/pt/documentation/df-odoo-connector/index.md)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

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.

| Entità | Odoo → Shopware (pull) | Shopware → Odoo (push) |
| --- | --- | --- |
| Prodotti (product.template) | ✅ | ✅ |
| Magazzino (qty_available / free_qty) | ✅ | — |
| Categorie (product.category) | ✅ | ✅ |
| Clienti (res.partner) | — | ✅ con indirizzi figli |
| Ordini (sale.order) | — | ✅ con conferma e fattura opzionali |

## 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
```

**Nota** — L'installazione crea due tabelle: `df_odoo_mapping` (corrispondenze persistenti Shopware ↔ Odoo) e `df_odoo_log` (registro delle operazioni). Nessuna tabella esistente viene modificata.

## 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.

**Importante** — La chiave API viene mostrata una sola volta. Se la perdi, dovrai generarne una nuova. Salvala in un gestore di password prima di chiudere la finestra di dialogo.

## 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'è.

**Consiglio** — Il test di connessione può anche essere richiamato dalla console per scriptare un controllo:
`curl -X POST -H "Authorization: Bearer ADMIN_TOKEN" https://tuoshopware.com/api/_action/df-odoo/test-connection`

## 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.

**Rilevamento delle modifiche** — Prima di ogni scrittura, un hash SHA-1 del contenuto viene confrontato con quello memorizzato nel mapping. Se nulla è cambiato, la scrittura viene saltata e l'operazione viene registrata come `skipped`. Questo evita di sovraccaricare Odoo nei cron successivi.

## 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.

**qty_available vs free_qty** — `qty_available` riflette lo stock fisico presente in magazzino. `free_qty` sottrae le quantità già riservate su ordini non consegnati. _free_qty_ è generalmente preferibile per un sito e-commerce perché evita le sovravvendite.

## 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.

**Il checkout non viene mai bloccato** — Se Odoo non è raggiungibile, l'errore viene tracciato in `df_odoo_log` e l'ordine viene ritentato entro 10 minuti dall'attività pianificata `df_odoo.order_sync`, che scansiona gli ordini non mappati degli ultimi 7 giorni.

### 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

| Nome interno | Frequenza | Azione |
| --- | --- | --- |
| `df_odoo.product_sync` | 1 ora | Pull poi push prodotti secondo la direzione configurata. Il pull esamina solo i record modificati dalle -2h. |
| `df_odoo.stock_sync` | 15 minuti | Pull del magazzino da Odoo per tutti i prodotti già mappati. |
| `df_odoo.customer_sync` | 1 ora | Push dei clienti attivi non ancora mappati (max 100 per esecuzione). |
| `df_odoo.order_sync` | 10 minuti | Push degli ordini degli ultimi 7 giorni non ancora mappati (max 50 per esecuzione). |

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

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

**Worker Shopware** — Perché le attività pianificate si attivino automaticamente, il worker messenger di Shopware deve essere in esecuzione (cron `messenger:consume` o unit systemd). Verifica in _Impostazioni → Sistema → Coda_ che _scheduled_task_ sia consumata regolarmente.

## 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.

**Modalità debug** — Le operazioni _skipped_ vengono scritte nel registro solo quando la modalità debug è attivata nelle impostazioni. Da usare puntualmente per diagnosticare un comportamento, da disattivare in produzione per evitare di saturare la tabella.

### 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).

| Metodo | Endpoint | Parametri |
| --- | --- | --- |
| POST | `/api/_action/df-odoo/test-connection` | `salesChannelId` (opzionale) |
| POST | `/api/_action/df-odoo/sync/products` | `direction=pull\|push`, `salesChannelId` |
| POST | `/api/_action/df-odoo/sync/stock` | `salesChannelId` |
| POST | `/api/_action/df-odoo/sync/customers` | `salesChannelId` |
| POST | `/api/_action/df-odoo/sync/orders` | `salesChannelId`, `limit` (1-500) |
| POST | `/api/_action/df-odoo/sync/categories` | `direction=pull\|push` |
| GET | `/api/_action/df-odoo/stats` | — |
| GET | `/api/_action/df-odoo/logs` | `status`, `entityType`, `direction`, `page`, `perPage` |

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](https://www.datafirefly.com/contact/). 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.