# Shopify

### Ce que ça fait

Shopify envoie en temps réel vers DURUM.ai vos **commandes payées** (ventes) et vos **remboursements**. La connexion se fait en un clic depuis votre boutique (OAuth) : DURUM.ai enregistre lui-même les webhooks nécessaires, il n'y a aucune URL à coller.

DURUM.ai suit votre boutique à partir de la connexion. Aucun import de l'historique des commandes.

### Avant de commencer

- Une boutique Shopify et un compte propriétaire ou collaborateur autorisé à installer une application.
- L'adresse `.myshopify.com` de la boutique (par exemple `mystore.myshopify.com`). Elle se trouve dans l'admin Shopify, section Paramètres, Domaines.
- Un accès à DURUM.ai avec un rôle agence ou client.

Accès demandés à Shopify (lecture seule) : `read_orders`, `read_products`, `read_customers`, `read_checkouts`, `read_analytics`, `read_reports`, `read_fulfillments`, `read_inventory`. DURUM.ai n'écrit rien dans votre boutique.

### Connexion étape par étape

1. Dans DURUM.ai, allez dans **Paramètres** puis **Intégrations**.
2. Sur la carte **Shopify** (catégorie E-commerce), cliquez sur **Connecter**.
3. Dans le champ **URL de votre boutique**, entrez le sous-domaine `.myshopify.com` de votre boutique, par exemple `mystore.myshopify.com`. La forme courte `mystore` est acceptée. Le domaine personnalisé de la boutique (`www.maboutique.com`) n'est pas accepté.
4. Cliquez sur **Connecter**. Vous êtes redirigé vers Shopify.
5. Connectez-vous à la boutique si nécessaire et cliquez sur **Installer** pour autoriser l'application DURUM.ai.
6. Vous revenez dans DURUM.ai avec le message « Shopify connecté ». DURUM.ai a enregistré cinq webhooks dans la boutique : `orders/create`, `orders/paid`, `orders/cancelled`, `refunds/create` et `app/uninstalled`, tous vers `https://app.durum.ai/api/webhook/shopify`. Ces webhooks sont créés par l'application : vous n'avez rien à configurer dans Shopify.

### Vérifier que ça marche

1. Passez une commande de test **payée** dans votre boutique (mode test de votre passerelle de paiement, ou commande réelle).
2. Attendez 30 secondes.
3. Dans DURUM.ai, ouvrez **Logs Data** : un événement `sale` de source `shopify` doit apparaître avec le statut `processed`.
4. Remboursez cette commande de test dans Shopify : un événement `refund` doit suivre, avec un montant négatif.

### Événements captés

| Côté Shopify | Événement DURUM.ai | Ce qu'il alimente |
|--------------|--------------------|-------------------|
| `orders/paid` | `sale` | Ventes. Montant = `total_price` dans la devise de la commande, contact = courriel du client, nom du client, produit = titre du premier article, référence = identifiant de la commande. Date = `processed_at` de la commande. |
| `orders/create` avec `financial_status` égal à `paid` | `sale` | Ventes (même contenu que ci-dessus). Une commande créée mais non payée est ignorée avec la raison `order_not_paid_yet`, puis comptée à réception de `orders/paid`. |
| `orders/cancelled` | aucun | Reçu puis ignoré. Une annulation ne crée pas d'événement. |
| `refunds/create` | `refund` | Remboursements. Montant négatif = somme des transactions du remboursement (remboursement partiel inclus). Courriel et nom repris de la commande d'origine. |
| `app/uninstalled` | aucun | La connexion passe en statut `revoked` et la synchro s'arrête. |

Une commande n'est comptée qu'une seule fois : DURUM.ai déduplique par identifiant de commande (et par identifiant de remboursement pour les remboursements). Un doublon apparaît dans Logs Data avec le statut `ignored`.

### Dépannage

| Problème | Solution |
|----------|----------|
| « Format invalide. Exemple attendu : mystore.myshopify.com » | Entrez l'adresse `.myshopify.com`, pas le domaine personnalisé de la boutique. |
| Aucun événement pour une commande | Vérifiez que la commande est **payée** (`financial_status` égal à `paid`). Une commande en attente de paiement n'est comptée qu'une fois payée. |
| Statut `error` avec le message `Invalid HMAC` | La signature du webhook ne correspond pas à l'application DURUM.ai installée dans la boutique. Déconnectez puis reconnectez l'intégration pour recréer les webhooks. |
| Réponse `unknown_client` dans Logs Data | DURUM.ai n'a pas pu rattacher la boutique à votre compte. Déconnectez puis reconnectez l'intégration. |
| Statut `ignored` sur une commande | Doublon (commande déjà comptée) ou commande non payée. Aucune action requise. |
| La carte affiche la connexion révoquée | L'application a été désinstallée depuis Shopify. Cliquez sur **Connecter** pour la réinstaller. |
| Remboursement sans courriel | La commande d'origine a été passée avant la connexion : DURUM.ai ne la connaît pas. Le remboursement est quand même enregistré. |

### FAQ

**DURUM.ai importe-t-il mes anciennes commandes ?**

Non. Le suivi commence à la connexion. Une commande passée avant la connexion n'apparaît pas, même si elle est payée ensuite.

**Puis-je connecter deux boutiques ?**

Une connexion Shopify par compte client. Pour une seconde boutique, utilisez un second compte client dans DURUM.ai.

**Comment sont traités les remboursements partiels ?**

Le montant enregistré est la somme réelle des transactions du remboursement, en négatif. Un remboursement partiel ne réduit donc que de son propre montant.

**Que se passe-t-il à la déconnexion ?**

DURUM.ai supprime uniquement les webhooks qui pointent vers `app.durum.ai`. Les webhooks de vos autres applications (Make, Zapier, etc.) ne sont jamais touchés.

**La devise ?**

Le montant est enregistré dans la devise de la commande telle que Shopify l'envoie.

---

---

Source: https://docs.durum.ai/integrations/shopify