# DataFirefly Odoo Connector: installatie- en configuratiegids

> Deze gids behandelt de installatie, de configuratie en het gebruik van de plugin DataFirefly Odoo Connector voor Shopware 6.6 en 6.7. Aan het einde synchroniseert uw shop producten, voorraad, klanten…

- Pagina: <https://www.datafirefly.com/nl/documentation/df-odoo-connector/>
- Taal: nl
- Bijgewerkt op: 2026-08-19
- Andere talen: [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), [it](https://www.datafirefly.com/it/documentation/df-odoo-connector/index.md), [pl](https://www.datafirefly.com/pl/documentation/df-odoo-connector/index.md), [pt](https://www.datafirefly.com/pt/documentation/df-odoo-connector/index.md)
- Index: <https://www.datafirefly.com/nl/documentation/llms.txt>

Deze gids behandelt de installatie, de configuratie en het gebruik van de plugin **DataFirefly Odoo Connector** voor Shopware 6.6 en 6.7. Aan het einde synchroniseert uw shop producten, voorraad, klanten en bestellingen met uw Odoo-instantie via native XML-RPC, zonder externe afhankelijkheid en zonder extra kosten voor een API van derden.

## Overzicht

De plugin bouwt een brug in twee richtingen tussen Shopware en Odoo door rechtstreeks het XML-RPC-protocol van Odoo te spreken (stabiel sinds versie 8). Geen module te installeren aan de kant van Odoo, geen betaalde middleware, geen tussenliggende SaaS.

| Entiteit | Odoo → Shopware (pull) | Shopware → Odoo (push) |
| --- | --- | --- |
| Producten (product.template) | ✅ | ✅ |
| Voorraad (qty_available / free_qty) | ✅ | — |
| Categorieën (product.category) | ✅ | ✅ |
| Klanten (res.partner) | — | ✅ met onderliggende adressen |
| Bestellingen (sale.order) | — | ✅ met optionele bevestiging en factuur |

## Vereisten

- **Shopware** 6.6.x of 6.7.x (alle minor versies).
- **PHP** 8.2, 8.3 of 8.4.
- **PHP-extensies**: curl, xml, simplexml (standaard aanwezig bij vrijwel elke hoster).
- **Odoo** 12, 13, 14, 15, 16, 17 of 18, Community of Enterprise. Odoo.sh, Odoo Online (SaaS) en zelfgehoste instanties werken identiek.
- Een Odoo-gebruiker die aan de API is gewijd (aanbevolen) met lees- en schrijfrechten op de gebruikte modellen (product.template, product.product, res.partner, sale.order, stock.warehouse, product.category, res.country, account.tax).

## Installatie

### Via upload in de administration

1. Download het archief `DfOdooConnector-v1.0.0.zip` vanuit uw klantaccount.
2. In de Shopware-administration: _Extensies → Mijn extensies → Extensie uploaden_.
3. Selecteer de ZIP en klik daarna op _Installeren_.
4. Activeer de extensie met de schakelaar.

### Via de SSH-console

```
cd /pad/naar/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
```

Hercompilatie van de administration om de Vue 3-module te laden:

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

**Let op**: de installatie maakt twee tabellen aan: `df_odoo_mapping` (blijvende koppelingen Shopware ↔ Odoo) en `df_odoo_log` (logboek van de bewerkingen). Er wordt geen enkele bestaande tabel gewijzigd.

## Configuratie aan de kant van Odoo

### Een specifieke gebruiker aanmaken

Het is sterk aan te raden een Odoo-gebruiker speciaal voor de integratie aan te maken in plaats van een persoonlijk beheerdersaccount te gebruiken. Zo kunt u de acties van de connector nauwkeurig controleren en zijn toegang los van andere accounts intrekken.

1. In Odoo: _Instellingen → Gebruikers en bedrijven → Gebruikers_.
2. Maak een gebruiker aan met bijvoorbeeld de naam `Shopware Bridge`.
3. Geef hem de vereiste rechten: Voorraad (gebruiker), Verkoop (beheerder van de documenten), Facturatie (gebruiker als u het aanmaken van facturen activeert) en Contacten (gebruiker).

### Een API-sleutel genereren

1. Log in Odoo in met die nieuwe gebruiker.
2. Klik rechtsboven op de avatar → _Voorkeuren_.
3. Tabblad _Account_ → _API-sleutels_ → _Nieuwe API-sleutel_.
4. Geef een beschrijvende naam (bijvoorbeeld `Shopware Connector`) en kopieer de gegenereerde waarde.

**Belangrijk**: de API-sleutel wordt maar één keer getoond. Raakt u hem kwijt, dan moet u een nieuwe genereren. Bewaar hem in een wachtwoordmanager voordat u het venster sluit.

## Configuratie aan de kant van Shopware

### De verbinding invullen

In de Shopware-administration: _Instellingen → Systeem → Plugins → Df Odoo → Instellingen_, of rechtstreeks via het zijmenu _Instellingen → Df Odoo → Instellingen_.

- **Odoo-URL**: de volledige URL van uw instantie zonder afsluitende schuine streep, bijvoorbeeld `https://mijnaccount.odoo.com`.
- **Naam van de database**: zichtbaar in de Odoo-URL na `?db=`, of via _Instellingen → Technisch → Database_.
- **Gebruiker**: de login van de specifieke gebruiker, meestal zijn e-mailadres.
- **Odoo API-sleutel**: de waarde die u in de vorige stap hebt gekopieerd.
- **Time-out**: standaard 30 seconden, in de meeste gevallen voldoende.

### De verbinding testen

Klik rechtsboven op de knop _Verbinding testen_. Als alles klopt, toont een groene melding de Odoo-versie en de gebruikersidentificatie (uid). Mislukt de verbinding, dan wordt de foutmelding van Odoo ongewijzigd getoond.

**Tip**: de verbindingstest kan ook vanaf de console worden aangeroepen om een controle te scripten:
`curl -X POST -H "Authorization: Bearer ADMIN_TOKEN" https://uwshopware.com/api/_action/df-odoo/test-connection`

## Synchronisatierichtingen

Elke entiteit heeft een eigen keuzelijst: _uitgeschakeld_, _Odoo → Shopware_ (pull), _Shopware → Odoo_ (push) of _tweerichtingsverkeer_. De standaardwaarden zijn:

- **Producten**: tweerichtingsverkeer
- **Voorraad**: Odoo → Shopware (Odoo is de bron van waarheid)
- **Klanten**: Shopware → Odoo
- **Bestellingen**: Shopware → Odoo
- **Categorieën**: uitgeschakeld (handmatig te activeren naargelang uw organisatie)

## Synchronisatie van de producten

### Koppelingsstrategieën

Er zijn drie strategieën instelbaar:

- **SKU** (aanbevolen): Shopware `productNumber` ↔ Odoo `default_code`.
- **Odoo-ID**: steunt uitsluitend op de blijvende koppelingstabel. Nuttig als uw SKU's vaak veranderen.
- **Barcode** (EAN): Shopware `ean` ↔ Odoo `barcode`. Vereist ingevulde EAN-codes aan beide kanten.

Eenmaal gekoppeld blijven twee producten aan elkaar verbonden via de tabel `df_odoo_mapping`, ook als de SKU daarna verandert.

### Pull vanuit Odoo

De geplande taak leest de `product.template`-records die sinds de vorige uitvoering zijn gewijzigd (veld `write_date`) en maakt de bijbehorende producten aan de Shopware-kant aan of werkt ze bij. De gesynchroniseerde velden zijn: naam, SKU, verkoopprijs, kostprijs, korte beschrijving, lange beschrijving, gewicht, volume, actieve status, categorie en belastingen.

### Push naar Odoo

De actieve hoofdproducten van Shopware (met `parentId = null`) worden naar Odoo gestuurd als `product.template` van het type _product_ (voorraadartikel). De varianten van Shopware worden onder hun bovenliggende product doorgegeven.

**Detectie van wijzigingen**: vóór elke schrijfactie wordt een SHA-1-hash van de inhoud vergeleken met de hash die in de koppeling is opgeslagen. Is er niets veranderd, dan wordt de schrijfactie overgeslagen en de bewerking als `skipped` gelogd. Zo raakt Odoo niet verzadigd bij opeenvolgende cronruns.

## Synchronisatie van de voorraad

De voorraad wordt altijd vanuit Odoo opgehaald (nooit omgekeerd). Elke 15 minuten leest de geplande taak de varianten `product.product` in batches van 100 per identificatie van het bovenliggende template, telt `qty_available` of `free_qty` op (globaal instelbaar) en werkt daarna het veld `stock` van elk Shopware-product in één DAL-query bij.

**qty_available versus free_qty**: `qty_available` weerspiegelt de fysieke voorraad in het magazijn. `free_qty` trekt de hoeveelheden af die al zijn gereserveerd voor nog niet geleverde bestellingen. _free_qty_ verdient meestal de voorkeur voor een webshop, omdat het oververkoop voorkomt.

## Synchronisatie van de categorieën

Standaard uitgeschakeld. Activeer die als uw categorieboom synchroon moet blijven met die van Odoo. De hiërarchie `parent_id` blijft aan beide kanten behouden. Net als bij producten voorkomt een hash van de inhoud onnodige schrijfacties.

## Synchronisatie van de klanten

Shopware-klanten worden als Odoo-`res.partner` doorgestuurd met:

- **Deduplicatie op e-mailadres**: vóór elke aanmaak wordt gezocht naar een bestaande partner met hetzelfde e-mailadres en `parent_id = false`. Bestaat die, dan wordt hij bijgewerkt in plaats van gedupliceerd.
- **company_type**: _company_ als het bedrijfsveld van het factuuradres is ingevuld, anders _person_.
- **Onderliggende adressen**: het standaard factuuradres wordt als onderliggende partner met `type='invoice'` aangemaakt, het bezorgadres als onderliggende partner met `type='delivery'`.
- **Intracommunautair btw-nummer**: overgenomen in het veld `vat` van de hoofdpartner.
- **Land en regio**: opgelost via de ISO-code met een geheugencache binnen de aanvraag.

## Synchronisatie van de bestellingen

### In realtime bij de checkout

Als de optie _Elke bestelling direct bij bevestiging doorsturen_ actief is, luistert een event subscriber naar `CheckoutOrderPlacedEvent` en stuurt hij de bestelling meteen na de afronding van de checkout naar Odoo. De klant wordt zo nodig in Odoo aangemaakt (via de klantsynchronisatie), waarna de bestelling als `sale.order` wordt aangemaakt met:

- `partner_id`, opgelost via de klantkoppeling.
- `order_line` in de tuple-syntaxis van Odoo: `[0, 0, {name, product_uom_qty, price_unit, product_id}]`.
- Een extra regel voor de verzendkosten als de `totalPrice` van de verzending groter is dan nul.
- `company_id`, `warehouse_id` en `pricelist_id` volgens de ingestelde standaardwaarden.

**De checkout wordt nooit geblokkeerd**: is Odoo onbereikbaar, dan wordt de fout in `df_odoo_log` vastgelegd en wordt de bestelling binnen 10 minuten opgepakt door de geplande taak `df_odoo.order_sync`, die de bestellingen van de laatste 7 dagen doorloopt die nog niet zijn gekoppeld.

### Statusfilter

Met het filter _Status van de bestellingen_ beperkt u welke bestellingen worden doorgestuurd:

- **Alle**: elke bevestigde bestelling wordt verstuurd (aanbevolen in B2C met directe betaling).
- **Alleen betaalde**: alleen bestellingen met de betaalstatus _paid_ worden doorgestuurd. Voorkomt dat verlaten winkelwagens met handmatige betaling worden doorgegeven.
- **Betaald of verzonden**: voegt aan de vorige de bestellingen toe die vóór de betaling zijn verzonden (B2B met betalingstermijn).

### Automatische bevestiging en facturatie

Twee opties bepalen wat er aan de kant van Odoo gebeurt zodra de bestelling is aangemaakt:

- **De bestelling bevestigen**: roept `action_confirm` aan op de `sale.order`, die dan direct naar de status _bevestigde bestelling_ gaat in plaats van _offerte_ te blijven.
- **De factuur aanmaken**: roept `_create_invoices` aan om meteen een gevalideerde factuur te genereren. De identificatie van de aangemaakte factuur wordt bewaard als koppeling van het type `invoice`.

## Meerdere sales channels

Alle instellingen van de plugin kunnen per verkoopkanaal worden overschreven. Bovenaan de pagina _Instellingen_ schakelt u met de native Shopware-kiezer tussen _Alle kanalen_ en een specifiek kanaal.

Typische toepassingen:

- Een B2C-kanaal dat naar een hoofd-Odoo doorstuurt en een B2B-kanaal dat naar een aparte Odoo doorstuurt.
- Een productiekanaal met de richting _push_ en een stagingkanaal met de richting _uitgeschakeld_.
- Verschillende Odoo-identificaties (warehouse, sales team, pricelist) per kanaal.

## Geplande taken

| Interne naam | Frequentie | Actie |
| --- | --- | --- |
| `df_odoo.product_sync` | 1 uur | Pull en daarna push van de producten volgens de ingestelde richting. De pull bekijkt alleen de records die sinds 2 uur geleden zijn gewijzigd. |
| `df_odoo.stock_sync` | 15 minuten | Pull van de voorraad uit Odoo voor alle al gekoppelde producten. |
| `df_odoo.customer_sync` | 1 uur | Push van de actieve klanten die nog niet gekoppeld zijn (maximaal 100 per uitvoering). |
| `df_odoo.order_sync` | 10 minuten | Push van de bestellingen van de laatste 7 dagen die nog niet gekoppeld zijn (maximaal 50 per uitvoering). |

Een taak vanaf de console geforceerd uitvoeren:

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

**Shopware-worker**: om de geplande taken automatisch te laten starten, moet de messenger-worker van Shopware draaien (cron `messenger:consume` of een systemd-taak). Controleer via _Instellingen → Systeem → Wachtrij_ of _scheduled_task_ regelmatig wordt verwerkt.

## Administratiemodule

Er verschijnt een sectie **Df Odoo** onder _Instellingen → Plugins_ met vier pagina's.

### Dashboard

Live tellers (actieve koppelingen per entiteit, activiteit van de laatste 24 uur per status), knoppen voor handmatige synchronisatie per entiteit (pull en push), statusbalk van de verbinding, lijst met recente fouten en snelkoppelingen naar de andere pagina's.

### Instellingen

Volledig formulier met een kiezer voor het verkoopkanaal. De knoppen _Verbinding testen_ en _Opslaan_ staan in de actiebalk.

### Logboek

Alle bewerkingen worden vastgelegd in `df_odoo_log` met hun status (_success_, _error_, _warning_, _skipped_), hun richting, de betrokken entiteit, de duur in milliseconden en de volledige melding. Combineerbare filters op status, entiteitstype en richting. Paginering aan serverzijde.

**Debugmodus**: de bewerkingen met status _skipped_ worden alleen in het logboek geschreven als de debugmodus in de instellingen actief is. Gebruik die af en toe om gedrag te onderzoeken en schakel hem in productie uit om de tabel niet te laten volstromen.

### Koppelingen

Leesweergave van de tabel `df_odoo_mapping` met zoekfunctie, filter op entiteitstype en sortering op de datum van de laatste synchronisatie. Handig om te controleren of een bepaald product wel aan de verwachte Odoo-ID is gekoppeld.

## Admin REST API

Alle endpoints vereisen standaard adminauthenticatie (Bearer token).

| Methode | Endpoint | Parameters |
| --- | --- | --- |
| POST | `/api/_action/df-odoo/test-connection` | `salesChannelId` (optioneel) |
| 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` |

Voorbeeld van een aanroep om een productpush te forceren:

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

## Tabellen en opgeslagen gegevens

De plugin maakt twee MySQL-tabellen aan:

- `df_odoo_mapping`: blijvende koppelingen (Shopware-identificatie ↔ Odoo-identificatie) met synchronisatiehash en optionele payload. Een regel is uniek op het paar (entiteitstype, Shopware-identificatie) en op (entiteitstype, Odoo-identificatie).
- `df_odoo_log`: logboek van de bewerkingen met status, duur, melding, payload en de identificatie van het verkoopkanaal.

Er wordt geen enkele standaardtabel van Shopware gewijzigd.

## Verwijderen

Vanuit de administration: _Extensies → Mijn extensies → Df Odoo → Verwijderen_.

Een dialoogvenster biedt twee opties:

- **Gebruikersgegevens behouden** aangevinkt: de tabellen `df_odoo_mapping` en `df_odoo_log` blijven bestaan, net als de systeeminstellingen. Handig bij een latere herinstallatie.
- **Gebruikersgegevens behouden** uitgevinkt: de twee tabellen worden bij het verwijderen gewist (DROP TABLE). De Odoo-instantie wordt nooit aangeraakt.

## Probleemoplossing

### "Odoo-configuratie onvolledig" bij de verbindingstest

Een van de vier verplichte velden (URL, database, gebruiker, API-sleutel) is leeg. Controleer of u vóór het opslaan het juiste verkoopkanaal hebt geselecteerd.

### "401 Unauthorized" of "access denied"

De API-sleutel is aan de kant van Odoo ingetrokken, of de gebruiker heeft niet de vereiste rechten op het aangesproken model. Genereer een nieuwe API-sleutel en controleer de Odoo-rechten van de gebruiker (met name _Voorraad → Gebruiker_ en _Verkoop → Beheerder van de documenten_).

### "Verbinding geweigerd" of time-out

De Odoo-URL is niet bereikbaar vanaf de Shopware-server. Controleer of de firewall uitgaande HTTPS-verbindingen naar het Odoo-domein toestaat. Verhoog de time-out als uw Odoo-instantie traag reageert.

### De producten synchroniseren niet

Bekijk het logboek (pagina _Logboek_) op regels met een fout. Activeer de debugmodus om ook de bewerkingen met status _skipped_ te loggen en zo te zien of de inhoudshash betekent dat er werkelijk niets verandert.

### De bestellingen vertrekken niet bij de checkout

Controleer of de optie _Elke bestelling direct bij bevestiging doorsturen_ is aangevinkt en of de richting _Bestellingen_ op _Shopware → Odoo_ staat. Staat het statusfilter op _Alleen betaalde_ en verloopt de betaling asynchroon, dan stuurt de geplande taak de bestelling enkele minuten na de incassering door.

## Bekende beperkingen

- De variantattributen van Odoo (`product.attribute`) worden nog niet automatisch gekoppeld. De varianten van Shopware worden als Odoo-hoofdproducten (`product.template`) doorgegeven. Handmatig in Odoo aangemaakte varianten blijven correct verbonden via hun bovenliggende template. Een native afhandeling staat gepland voor versie 1.1.
- Kortingen op bestelregels worden doorgegeven als een aangepaste `price_unit`, niet als een Odoo-`discount`.
- De betaal- en verzendmethodes van Shopware worden niet gekoppeld aan de `journal_id`-waarden van Odoo; de standaardwaarden van Odoo worden gebruikt.

## Support

Neem voor vragen contact op met het team van DataFirefly via het contactformulier op [datafirefly.com](https://www.datafirefly.com/nl/contact/). Voeg de export van het logboek toe (pagina _Logboek_ → exportknop volgt), of op zijn minst een schermafbeelding van de foutregel en de exacte versie van Shopware, PHP en Odoo.