Configuration de l'intégration Shopware

Ce guide explique comment connecter une instance Shopware 6.6.5.0 ou supérieure à Order Fox afin d'importer des produits/clients et d'exporter des commandes.

Note : La version minimale théorique est Shopware 6.3.5.0 (lorsque le système d'intégration et d'ACL a été stabilisé), mais elle n'a pas été testée. Seules les versions Shopware 6.6.5.0 et supérieures sont vérifiées.

1. Identifiants d'intégration Shopware

Demandez ou créez une intégration dans Shopware Admin sous Paramètres > Système > Intégrations afin d'obtenir un Client ID (Access Key ID) et un Client Secret (Secret Access Key).

Une intégration de type Administrateur est préférable. Si ce n'est pas possible, activez les autorisations suivantes dans la grille ACL de l'intégration :

Section	Ligne	Afficher	Modifier	Créer	Supprimer
Catalogues	Produits	x
Catalogues	Propriétés	x
Clients	Clients	x	x
Commandes	Commandes	x	x	x
Autre	Canaux de vente	x

Aucune autorisation supplémentaire n'est nécessaire — le rôle « Créer » des commandes inclut déjà api_proxy_switch-customer en interne.

---

2. Créer une intégration OAuth

Créez une intégration de type OAuth avec les paramètres suivants :

Champ	Valeur
Label	Shopware
Webservice URL	Votre domaine Shopware, par ex. https://shopware.example.com (sans le suffixe /api)
Token URL	Le point de terminaison OAuth complet, par ex. https://shopware.example.com/api/oauth/token
Client ID	L'Access Key ID de votre intégration Shopware
Client Secret	La Secret Access Key de votre intégration Shopware
Scope	(laisser vide)

L'URL du webservice doit correspondre uniquement au domaine de base (jusqu'au TLD). L'URL du token doit inclure le chemin complet /api/oauth/token.

---

3. Profils d'importation

Les profils d'importation récupèrent des données depuis Shopware vers Order Fox. Chaque profil cible un point de terminaison de recherche spécifique de l'API Shopware.

Produits

Créez un profil d'importation avec la configuration suivante :

Champ	Valeur
Nom	Products
Intégration	L'intégration OAuth Shopware créée ci-dessus
Données de référence	Le jeu de données de référence dans lequel les produits doivent être importés

Paramètres de configuration :

Paramètre	Valeur
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

En-têtes supplémentaires :

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

Paramètres supplémentaires (corps de la requête) :

{
    "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
                }
            ]
        }
    ]
}

Le filtre garantit que seuls les produits actifs sont importés et exclut les produits parents qui possèdent des variantes (seules les variantes elles-mêmes sont renvoyées).

Clients

Créez un profil d'importation avec la configuration suivante :

Champ	Valeur
Nom	Customers
Intégration	L'intégration OAuth Shopware créée ci-dessus
Données de référence	Le jeu de données de référence dans lequel les clients doivent être importés

Paramètres de configuration :

Paramètre	Valeur
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

En-têtes supplémentaires :

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

Paramètres supplémentaires (corps de la requête) :

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

Mappage

Après avoir créé chaque profil d'importation, configurez le mappage des champs afin de faire correspondre les champs Shopware importés aux attributs du type d'actif de votre tenant. Le mappage est spécifique au tenant et doit être configuré pour chaque installation.

---

4. Profil d'exportation (commandes)

Pour réexporter les commandes vers Shopware, créez un profil d'exportation avec le provider Shopware.

Champ	Valeur
Nom	Un nom descriptif pour l'exportation
Intégration	L'intégration OAuth Shopware créée ci-dessus
Provider	shopware
Path	/

Template :

Le template utilise la syntaxe Twig et fait correspondre les données de commande d'Order Fox au format de l'API de création de commande Shopware. Remplacez le salesChannelId par l'ID de votre canal de vente Shopware. Les champs des objets parties et lines dépendent de votre configuration de mappage des champs ; adaptez donc le template en conséquence si vous avez mappé d'autres champs.

{
    "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 %}
    ]
}

Mappage des variables du template :

Variable	Correspond à
buyer_customer_party.external_id	customerId issu de l'importation des clients
accounting_customer_party.account_id	addressId de facturation issu de l'importation des clients
buyer_customer_party.account_id	addressId de livraison issu de l'importation des clients
line.item.external_id	productId issu de l'importation des produits

Définir le provider sur shopware achemine l'exportation via le gestionnaire d'exportation Shopware dédié, qui gère automatiquement l'authentification et la communication avec l'API.