> ## Documentation Index
> Fetch the complete documentation index at: https://docs.actero.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Intégration Shopify : installer Actero en 1 clic

> Installe l'agent SAV Actero depuis le Shopify App Store en 1 clic : scopes OAuth auditables, webhooks RGPD obligatoires et désinstallation propre.

Shopify est l'intégration phare d'Actero. Une fois connectée, ton agent répond aux WISMO (« où est ma commande ? »), gère retours, échanges, suivi, recommande des produits et personnalise chaque réponse avec le profil client — sans toucher à ta caisse.

## Prérequis

* Une boutique Shopify active (plan Basic, Shopify, Advanced ou Plus — peu importe)
* Le rôle **Owner** ou **Staff avec permission « Apps »** dans ton compte Shopify
* Un compte Actero avec au moins le plan **Free** (50 tickets/mois) — plan **Starter** ou supérieur recommandé pour les playbooks panier abandonné

## Installer Actero depuis le Shopify App Store

Actero est listée sur le Shopify App Store. L'installation est gratuite et passe par le flow OAuth officiel — tu vois exactement ce que l'agent peut lire avant de valider.

<Steps>
  <Step title="Ouvre la fiche Actero sur le Shopify App Store">
    Depuis le [Shopify App Store](https://apps.shopify.com), cherche **Actero** et clique **Ajouter l'app**. Tu peux aussi partir d'Actero : **Intégrations → Shopify → Connecter**, puis saisir ton domaine `ma-boutique.myshopify.com`.
  </Step>

  <Step title="Valide les scopes requis et optionnels">
    Shopify affiche deux blocs distincts : les permissions **requises** (sans elles, l'agent ne peut pas fonctionner) et les permissions **optionnelles** (tu peux les décliner — l'agent dégradera gracieusement les fonctionnalités concernées). Voir [Scopes demandés](#scopes-demand%C3%A9s).
  </Step>

  <Step title="Approuve l'installation">
    Tu reviens automatiquement sur `actero.fr`. Aucune carte bancaire requise côté Shopify — Actero est facturée séparément depuis ton compte Actero.
  </Step>

  <Step title="Active le widget de chat">
    Le widget est livré comme une **extension de thème** (theme app extension) — Actero ne modifie jamais ton `theme.liquid`. Active-le en un clic depuis **Boutique en ligne → Thèmes → Personnaliser → Widgets d'application (App embeds) → Actero**. Les 30 dernières commandes sont indexées en moins de 20 secondes.
  </Step>
</Steps>

<Tip>
  Si tu n'as pas encore configuré ton agent, regarde le [quickstart](/essentials/quickstart) — c'est la suite logique de cette connexion.
</Tip>

### Bouton « Open app » dans Shopify Admin

Une fois installée, Actero apparaît dans **Apps** dans ton Shopify Admin. Cliquer dessus t'envoie automatiquement vers le bon endroit :

* **Boutique déjà connectée** → redirection directe vers ton dashboard Actero
* **Première fois** → relance du flow OAuth pour finaliser l'install

Tu n'as donc jamais à coller manuellement une URL : Shopify Admin reste ton point d'entrée.

## Scopes demandés

Actero sépare scopes **requis** et **optionnels**. Tu peux décliner les optionnels sans casser l'install ; les fonctionnalités correspondantes restent simplement inactives jusqu'à ce que tu les accordes.

### Scopes requis

<AccordionGroup>
  <Accordion title="read_orders, read_fulfillments">
    Lecture des commandes et des expéditions. Indispensable pour répondre aux WISMO et donner un ETA fiable au client.
  </Accordion>

  <Accordion title="read_customers">
    Identifier le client qui pose la question, personnaliser le ton et reconnaître les clients VIP.
  </Accordion>

  <Accordion title="read_products, read_inventory">
    Répondre aux questions catalogue (taille, matière, prix) et stock (« est-ce qu'il en reste en M ? »).
  </Accordion>

  <Accordion title="read_checkouts">
    Détecter les paniers abandonnés pour le playbook de relance.
  </Accordion>

  <Accordion title="read_returns">
    Répondre aux questions sur la politique et le statut des retours.
  </Accordion>
</AccordionGroup>

<Note>
  Actero ne demande **aucun** scope de thème (`read_themes` / `write_themes`). Le widget de chat est une **extension de thème** (theme app extension) que tu actives depuis l'éditeur de thème — aucune modification de ton code n'est nécessaire.
</Note>

### Scopes optionnels

<AccordionGroup>
  <Accordion title="read_draft_orders">
    Donne du contexte d'upsell dans les conversations (devis en cours, panier construit par un staff). Sans ce scope, l'agent ignore les drafts.
  </Accordion>

  <Accordion title="read_shipping">
    Permet à l'agent de citer un tarif de livraison en direct (« combien coûte une livraison express vers Lyon ? »). Sans ce scope, l'agent répond avec une formulation générique.
  </Accordion>
</AccordionGroup>

<Warning>
  Actero ne demande **que des scopes en lecture** — aucun scope d'écriture (commandes, produits, stock, thème) ni de paiement. Les remboursements sont proposés en **brouillon** que tu valides toi-même dans Shopify Admin ; l'agent n'encaisse jamais et ne modifie jamais une commande, un produit ou ton inventaire.
</Warning>

## Webhooks configurés automatiquement

À l'installation, Actero enregistre cinq webhooks. Tous sont signés HMAC-SHA256 et vérifiés en temps constant (`crypto.timingSafeEqual`) côté Actero.

### Conformité (obligatoires App Store)

| Webhook                  | Effet dans Actero                                                                                      |
| ------------------------ | ------------------------------------------------------------------------------------------------------ |
| `customers/data_request` | Accusé de réception, traitement manuel sous 30 jours via [contact@actero.fr](mailto:contact@actero.fr) |
| `customers/redact`       | Suppression définitive des PII du client concerné (email, nom, historique de conversations)            |
| `shop/redact`            | Suppression définitive de toutes les données scoped au marchand, 48h après la désinstallation          |
| `app/uninstalled`        | Marque la boutique comme désinstallée, désactive le widget, alerte l'équipe Actero pour suivi          |

Chaque appel à un webhook de conformité est tracé (hash SHA-256 du payload, jamais le payload brut) dans un journal d'audit append-only conservé pour démontrer la conformité RGPD.

### Métier

| Webhook            | Effet dans Actero                                                                        |
| ------------------ | ---------------------------------------------------------------------------------------- |
| `checkouts/create` | Déclenche le playbook **panier abandonné** (relance email selon le délai que tu choisis) |

Tu peux désactiver un playbook depuis **Automatisation** sans toucher à l'intégration Shopify.

## Quelles données circulent

* **Commandes** (numéro, statut, total, items, tracking) → réponses WISMO et SAV
* **Clients** (nom, email, langue, historique) → personnalisation du ton, reconnaissance des VIP
* **Produits** (titre, description, variantes, prix, stock) → questions catalogue
* **Paniers abandonnés** (items, total, email, URL de checkout) → relances automatiques

Tout est stocké chiffré côté Actero (Supabase, RLS activée, isolation par `client_id`). Aucune donnée n'est jamais partagée avec un autre marchand.

## Multi-boutique

Sur le plan **Entreprise**, une même organisation Actero peut connecter plusieurs boutiques Shopify et les gérer depuis un dashboard unifié.

Sur les plans **Free**, **Starter** et **Pro**, tu as **un seul domaine Shopify par compte Actero**. Si tu gères deux marques distinctes, crée un second compte Actero — chaque agent reste isolé et garde son ton, sa base de connaissances et ses métriques.

<Note>
  Une seule plateforme e-commerce active par compte. Si tu connectes ensuite [WooCommerce](/integrations/woocommerce) ou [Webflow](/integrations/webflow), Actero te demande de déconnecter Shopify d'abord.
</Note>

## Désinstallation

Deux chemins, même résultat :

* **Depuis Shopify Admin** → **Apps → Actero → Supprimer l'app**. Shopify déclenche le webhook `app/uninstalled` ; Actero révoque le token, désactive le widget et marque ta boutique comme désinstallée dans les secondes qui suivent.
* **Depuis Actero** → **Intégrations → Shopify → Déconnecter**. Effet équivalent côté Actero, plus suppression manuelle des webhooks via l'API Shopify Admin.

Les conversations passées restent dans ton historique pour des raisons RGPD (export et suppression possibles depuis [Export RGPD](/essentials/export-rgpd)). Si Shopify déclenche `shop/redact` 48h après la désinstallation, toutes les données scoped à ta boutique sont effacées définitivement côté Actero.

## Problèmes fréquents

<AccordionGroup>
  <Accordion title="L'agent ne trouve pas ma commande #1234">
    Vérifie que Shopify est bien en statut **Connecté** dans Intégrations. L'agent matche d'abord par email client, puis par numéro de commande. Si le client a passé sa commande en invité avec une autre adresse email que celle utilisée dans la conversation, demande-lui de confirmer son email d'achat.
  </Accordion>

  <Accordion title="Webhook error 401 ou 403 dans les logs Shopify">
    Le secret HMAC a probablement tourné (rotation côté Shopify). Déconnecte puis reconnecte l'intégration depuis Actero — les webhooks sont régénérés avec un secret frais.
  </Accordion>

  <Accordion title="Relances panier abandonné qui ne partent pas">
    Trois choses à vérifier : (1) le playbook `panier abandonné` est **activé** dans Automatisation, (2) un service d'envoi est configuré ([Resend](/integrations/resend), [Gmail](/integrations/gmail) ou [SMTP/IMAP](/integrations/smtp-imap)), (3) le client a bien laissé son email à l'étape checkout (sans email, pas de relance possible).
  </Accordion>

  <Accordion title="Le widget ne s'affiche pas sur ma boutique">
    Vérifie que l'app embed **Actero** est activée : **Boutique en ligne → Thèmes → Personnaliser → Widgets d'application (App embeds)**. Si elle est déjà activée, désactive-la puis réactive-la pour forcer un rechargement du thème.
  </Accordion>

  <Accordion title="J'ai changé de domaine Shopify (migration .myshopify.com)">
    Reconnecte l'intégration avec le nouveau domaine. Les commandes historiques restent indexées, le nouveau token prend le relais sans coupure de service.
  </Accordion>

  <Accordion title="Comment tester sans impacter mes vrais clients">
    Utilise **Tester mon agent** (Simulator) dans le dashboard. Les messages simulés n'envoient rien aux vrais clients, ne créent aucune commande et n'écrivent rien dans Shopify.
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Actero est-elle listée sur le Shopify App Store ?">
    Oui. L'installation passe par le flow OAuth officiel Shopify, ce qui te garantit que les scopes sont visibles, révocables à tout moment et auditables depuis Shopify Admin → **Apps → Actero → Voir les détails de l'app**.
  </Accordion>

  <Accordion title="Combien de temps pour indexer toute ma boutique ?">
    Les 30 dernières commandes sont indexées en \~20 secondes (immédiat). L'indexation complète (catalogue, clients, historique 12 mois) prend de 2 à 30 minutes selon la taille de ta boutique. Tu reçois une notification dans le dashboard quand c'est fini.
  </Accordion>

  <Accordion title="Mes clients voient-ils que c'est une IA ?">
    Tu choisis. Par défaut, l'agent signe avec le nom de ta marque. Tu peux activer une signature explicite (« Réponse assistée par notre agent IA ») depuis **Configurer l'agent → Identité**.
  </Accordion>

  <Accordion title="Que se passe-t-il si je désinstalle puis réinstalle plus tard ?">
    Si tu réinstalles dans les 48h, tes données sont encore là — tu retrouves ton agent configuré tel quel. Au-delà, Shopify a déclenché `shop/redact` et tout a été effacé : tu repars d'une page blanche.
  </Accordion>
</AccordionGroup>