Intégrations partenaires

Une intégration connecte votre produit (CRM, ERP, POS, plateforme de fidélité, transporteur…) à ShopiMind : vous recevez les événements de cycle de vie d'une boutique, et vous poussez vos données vers ShopiMind via l'API.

Cette section s'adresse aux intégrateurs partenaires. Pour synchroniser simplement les données d'une boutique e-commerce standard, voyez plutôt le connecteur e-commerce.

Le modèle en deux directions

Une intégration communique avec ShopiMind dans deux sens :

Direction	Qui appelle	Comment c'est authentifié
Entrant — ShopiMind → vous	ShopiMind appelle vos webhooks (install, activate, config…)	Signature HMAC-SHA256 (voir Cycle de vie & webhooks)
Sortant — vous → ShopiMind	Vous appelez l'API ShopiMind pour pousser des données	Clé API spm-api-key remise à l'installation (voir Appeler l'API)

Vous n'hébergez donc qu'un petit serveur de webhooks, et vous consommez l'API ShopiMind avec le SDK officiel — exactement ce que fournit le starter.

Cycle de vie d'une installation

Install  →  (Configurer)  →  Activate  →  … config_updated …  →  Deactivate  →  Uninstall

1. Install — l'utilisateur installe votre intégration depuis ShopiMind. Vous recevez un webhook install contenant un access_token (la clé API à conserver). À ce stade la clé est révoquée : aucun appel API n'est encore possible.
2. Configurer — l'utilisateur renseigne les champs de configuration que vous avez déclarés (voir Configuration).
3. Activate — l'utilisateur active l'intégration. ShopiMind dé-révoque la clé puis vous envoie activate avec les valeurs de configuration. C'est seulement maintenant que vos appels à l'API ShopiMind fonctionnent.
4. config_updated — à chaque modification de configuration (best-effort).
5. Deactivate — l'utilisateur désactive : ShopiMind re-révoque la clé.
6. Uninstall — l'utilisateur désinstalle : ShopiMind supprime la configuration et révoque définitivement la clé.

La clé API n'est valide que pendant le statut « actif »

Tout appel à l'API ShopiMind avant activate ou après deactivate renvoie 401. Stockez le access_token reçu à l'install — vous ne le recevrez pas une seconde fois.

Deux types d'installation

• Type A — clé API directe : ShopiMind crée l'installation et vous envoie directement le webhook install avec le access_token. Aucune authentification externe.
• Type B — OAuth : votre produit nécessite que l'utilisateur s'authentifie chez vous d'abord. ShopiMind redirige le navigateur vers votre page de consentement, puis vous le renvoyez vers ShopiMind. Voir le détail dans Cycle de vie & webhooks.

Sécurité en bref

• Webhooks entrants : vérifiez la signature HMAC-SHA256 de chaque requête avant de la traiter (en-têtes X-Shopimind-Signature / X-Shopimind-Timestamp).
• Contrat de réponse : répondez toujours HTTP 200 avec { "success": true }. Tout autre code/corps est traité comme un échec.
• Clé API : transmise uniquement via le header spm-api-key, valide pendant la fenêtre active.

Cette section

• Cycle de vie & webhooks — événements, payloads, HMAC, OAuth, retries.
• Configuration — schéma de config, étapes, test de connexion, données distantes.
• Widgets — déclarer des widgets (image / HTML statique / HTML dynamique).
• Studio (générateur JSON) — générer vos déclarations sans coder.
• Appeler l'API ShopiMind — pousser vos données avec le SDK.
• Starter — le projet de démarrage prêt à cloner.

Démarrer vite

Ne partez pas d'une page blanche : le starter d'intégration câble déjà tous les webhooks, la vérification HMAC, OAuth Type B et un magasin local des installations.