Shopware Integratie Instellen

Deze handleiding beschrijft hoe je een Shopware 6.6.5.0 (of hoger) instantie koppelt aan Order Fox voor het importeren van producten/klanten en het exporteren van bestellingen.

Opmerking: De theoretische minimumversie is Shopware 6.3.5.0 (toen het Integratie- & ACL-systeem werd gestabiliseerd), maar dit is niet getest. Alleen Shopware 6.6.5.0 en hoger zijn geverifieerd.

1. Shopware Integratiegegevens

Vraag een integratie aan of maak er een aan in Shopware Admin onder Instellingen > Systeem > Integraties om een Client ID (Access Key ID) en Client Secret (Secret Access Key) te verkrijgen.

Een Administrator-integratie heeft de voorkeur. Als dit niet mogelijk is, schakel dan de volgende rechten in het ACL-raster van de integratie in:

Sectie	Rij	Bekijken	Bewerken	Aanmaken	Verwijderen
Catalogussen	Producten	x
Catalogussen	Eigenschappen	x
Klanten	Klanten	x	x
Bestellingen	Bestellingen	x	x	x
Overig	Verkoopkanalen	x

Er zijn geen aanvullende rechten nodig — de rol "Aanmaken" bij Bestellingen bevat intern al api_proxy_switch-customer.

---

2. Een OAuth-integratie aanmaken

Maak een integratie van het type OAuth aan met de volgende instellingen:

Veld	Waarde
Label	Shopware
Webservice URL	Je Shopware-domein, bijv. https://shopware.example.com (zonder /api-achtervoegsel)
Token URL	Volledig OAuth-token-endpoint, bijv. https://shopware.example.com/api/oauth/token
Client ID	Je Shopware Integration Access Key ID
Client Secret	Je Shopware Integration Secret Access Key
Scope	(leeg laten)

De webservice-URL moet alleen het basisdomein zijn (tot en met het TLD). De token-URL moet het volledige /api/oauth/token-pad bevatten.

---

3. Importprofielen

Importprofielen halen gegevens op uit Shopware naar Order Fox. Elk profiel richt zich op een specifiek Shopware API-zoekeindpunt.

Producten

Maak een importprofiel aan met de volgende configuratie:

Veld	Waarde
Naam	Products
Integratie	De hierboven aangemaakte Shopware OAuth-integratie
Referentiedata	De referentiedataset waar producten naartoe geïmporteerd moeten worden

Configuratieparameters:

Parameter	Waarde
Path	/api/search/product
Transformer	shopware_products
Request Method	Post
Data Wrapper	data
Page Parameter	page
Page Start Index	1
Page Step Size	1
Page Size Parameter	limit
Page Size Length	10

Extra headers:

{
    "Accept": "application/json",
    "sw-inheritance": "true"
}

Extra parameters (request body):

{
    "includes": {
        "product": [
            "id", "productNumber", "name", "parentId",
            "price", "stock", "ean", "options", "translated"
        ]
    },
    "associations": {
        "options": {
            "associations": {
                "group": {}
            }
        }
    },
    "filter": [
        {
            "type": "equals",
            "field": "active",
            "value": true
        },
        {
            "type": "multi",
            "operator": "or",
            "queries": [
                {
                    "type": "not",
                    "operator": "and",
                    "queries": [
                        { "type": "equals", "field": "parentId", "value": null }
                    ]
                },
                {
                    "type": "equals",
                    "field": "childCount",
                    "value": 0
                }
            ]
        }
    ]
}

Het filter zorgt ervoor dat alleen actieve producten worden geïmporteerd en sluit bovenliggende producten met varianten uit (alleen de varianten zelf worden opgehaald).

Klanten

Maak een importprofiel aan met de volgende configuratie:

Veld	Waarde
Naam	Customers
Integratie	De hierboven aangemaakte Shopware OAuth-integratie
Referentiedata	De referentiedataset waar klanten naartoe geïmporteerd moeten worden

Configuratieparameters:

Parameter	Waarde
Path	/api/search/customer
Transformer	shopware_customers
Request Method	Post
Data Wrapper	data
Page Parameter	page
Page Start Index	1
Page Step Size	1
Page Size Parameter	limit
Page Size Length	10

Extra headers:

{
    "Accept": "application/json",
    "sw-inheritance": "true"
}

Extra parameters (request body):

{
    "includes": {
        "customer": [
            "id", "customerNumber", "firstName", "lastName",
            "email", "company", "defaultBillingAddress",
            "defaultShippingAddress", "vatIds"
        ]
    },
    "associations": {
        "defaultBillingAddress": {
            "associations": {
                "country": {}
            }
        },
        "defaultShippingAddress": {
            "associations": {
                "country": {}
            }
        }
    }
}

Mapping

Na het aanmaken van elk importprofiel configureer je de veldmapping om de geïmporteerde Shopware-velden te koppelen aan de kenmerken van het assettype van je tenant. De mapping is tenantspecifiek en moet per installatie worden geconfigureerd.

---

4. Exportprofiel (Bestellingen)

Om bestellingen terug te exporteren naar Shopware, maak je een exportprofiel aan met de Shopware-provider.

Veld	Waarde
Naam	Een beschrijvende naam voor de export
Integratie	De hierboven aangemaakte Shopware OAuth-integratie
Provider	shopware
Path	/

Template:

Het template gebruikt Twig-syntax en koppelt Order Fox-ordergegevens aan het Shopware-bestelformaat via de API. Vervang de salesChannelId door je Shopware Sales Channel ID. De velden op de partij- en regelobjecten zijn afhankelijk van je veldmappingconfiguratie, dus pas het template dienovereenkomstig aan als je andere velden hebt gemapped.

{
    "salesChannelId": "<your-sales-channel-id>",
    "customerId": "{{ buyer_customer_party.external_id }}",
    "billingAddressId": "{{ accounting_customer_party.account_id }}",
    "shippingAddressId": "{{ buyer_customer_party.account_id }}",
    "items": [
        {% for line in lines %}
        {
            "productId": "{{ line.item.external_id }}",
            "quantity": {{ line.quantity }}
        }{% if not loop.last %},{% endif %}
        {% endfor %}
    ]
}

Template-variabelemapping:

Variabele	Verwijst naar
buyer_customer_party.external_id	customerId uit de klantenimport
accounting_customer_party.account_id	Facturatie-addressId uit de klantenimport
buyer_customer_party.account_id	Verzend-addressId uit de klantenimport
line.item.external_id	productId uit de productenimport

Door de provider op shopware in te stellen, wordt de export via de speciale Shopware-exporthandler gerouteerd, die authenticatie en API-communicatie automatisch afhandelt.