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

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

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.

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.

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.

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.

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.

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

Een taak vanaf de console geforceerd uitvoeren:

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

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.

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

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