Intégrations

Une intégration est un produit qui se branche sur un compte ShopiMind existant — CRM, ERP, point de vente (POS), plateforme de fidélité, service d'avis, transporteur… Elle reçoit les événements de cycle de vie d'une boutique et pousse ses données dans ShopiMind, aux côtés des données e-commerce.

Vous n'écrivez pas tout cela à la main. Le kit d'intégration JavaScript @shopimind/integration-kit-js fournit le runtime complet : serveur de webhooks, vérification de signature, planificateur, un stockage local chiffré (une base de données SQLite, à l'intérieur de votre propre service) et un accès typé à l'API ShopiMind. Vous décrivez votre intégration avec un seul appel — defineIntegration({ … }) — et le kit fait le reste.

Le point de départ : le kit

Tout commence avec @shopimind/integration-kit-js. Vous y déclarez votre intégration, le kit monte le serveur, vérifie chaque webhook signé, planifie les synchronisations et vous remet un client API déjà authentifié. → Le kit en détail · → Démarrage rapide

Intégration ou connecteur e-commerce ?

• Une intégration (POS, CRM, fidélité, avis…) se branche sur un compte ShopiMind existant et se construit avec le kit @shopimind/integration-kit-js. C'est l'objet de cette section.
• Un connecteur e-commerce (PrestaShop, WooCommerce, Odoo…) est une plateforme autonome. Aujourd'hui il se construit directement via le SDK ou l'API — un « kit de connecteur » dédié viendra plus tard. → Connecteur e-commerce.

	Intégration	Connecteur e-commerce
Ce que c'est	Un produit tiers branché sur un compte (POS, CRM, fidélité, avis…)	Une plateforme e-commerce autonome (PrestaShop, WooCommerce, Odoo…)
Exemple	Hiboutik POS	PrestaShop, Odoo
Comment le construire	Le kit @shopimind/integration-kit-js	Le SDK / l'API directement (kit de connecteur à venir)
Données poussées	Un périmètre ciblé + des sources dédiées (clients, commandes, produits de point de vente…)	Le catalogue complet (clients, produits, catégories, commandes…)

Le modèle en briques

Une intégration ShopiMind s'organise autour de quatre briques clairement séparées.

Brique	Ce que c'est	Qui l'écrit
Le SDK (@shopimind/sdk-js)	Transport : le client HTTP sortant et les ressources typées pour l'API ShopiMind	ShopiMind (vous l'utilisez)
Le kit (@shopimind/integration-kit-js)	Runtime : webhooks, signature, planificateur, stockage. Dépend du SDK et le ré-exporte	ShopiMind (vous l'utilisez)
Votre intégration	Vos déclarations et fonctions, passées à defineIntegration	Vous
Le cœur ShopiMind	La plateforme : émet les webhooks signés, reçoit vos données via l'API	ShopiMind

En pratique, vous n'écrivez que la troisième brique. Le kit dépend du SDK et le ré-exporte (export * from '@shopimind/sdk-js'), si bien que vous importez les ressources et les types du SDK depuis le kit — aucune installation séparée du SDK n'est nécessaire dans votre intégration.

Vous poussez vos données via ctx.spm, qui est un SpmHttpClient brut (construit et authentifié par le kit). Vous appelez dessus les méthodes statiques du SDK :

import { SpmCustomers, SpmEvents } from '@shopimind/integration-kit-js';

await SpmCustomers.bulkSave(ctx.spm, items, { chunk: true });
await SpmEvents.trigger(ctx.spm, codeName, payload);

Le SDK renvoie une enveloppe { ok, statusCode, data, error } et ne lève jamais d'exception sur une erreur HTTP. Pour les étapes de synchronisation et les handlers entrants, préférez ctx.sendBulk(fn, items) : il envoie par lots, lève une exception en cas d'échec de transport, fait remonter les rejets par item et laisse le moteur tenir le curseur — aucune perte silencieuse de données.

Le kit s'appuie sur le SDK

Le SDK est la couche de transport ; le kit en dépend, le ré-exporte et vous fournit un ctx.spm déjà authentifié. Vous importez les ressources et les types du SDK directement depuis le kit. → SDK JavaScript

Les trois directions de communication

Une intégration est un middleware entre votre application et ShopiMind : elle communique dans trois directions, chacune avec son propre mécanisme — toutes prises en charge par le kit.

Direction	Qui appelle	Comment c'est authentifié
Sortant — intégration → ShopiMind	Vous appelez l'API ShopiMind pour pousser vos données	Clé API de la boutique dans l'en-tête spm-api-key (prise en charge par le SDK, via ctx.spm)
Entrant — cycle de vie — ShopiMind → intégration	ShopiMind appelle vos webhooks (cycle de vie, test, données distantes)	Signature HMAC-SHA256 X-Shopimind-Signature, vérifiée par le kit
Entrant — middleware — votre app → intégration	Votre application appelle vos routes entrantes pour déclencher un événement ou pousser des données en temps réel	Signature HMAC par installation (x-integration-*), vérifiée par le kit

Vous n'avez aucune signature à coder

Le kit vérifie les deux directions entrantes (HMAC-SHA256, fenêtre anti-rejeu, comparaison à temps constant) avant même que votre code ne soit appelé. Une requête mal signée n'atteint jamais vos callbacks. → Cycle de vie & webhooks · → Middleware entrant

Cycle de vie de l'installation

ShopiMind pilote l'installation via une séquence d'événements de cycle de vie, livrés à vos webhooks signés et distribués par le kit vers vos hooks.

install  →  (configure)  →  activate  →  … config_updated …  →  deactivate  →  uninstall

• install — l'utilisateur installe votre intégration depuis ShopiMind.
• configure — l'utilisateur renseigne les champs que vous avez déclarés dans configSchema (voir Configuration).
• activate — l'intégration est activée ; vos appels à l'API ShopiMind fonctionnent. Le kit applique votre provisioning puis appelle votre hook onActivate.
• config_updated — à chaque changement de configuration.
• deactivate — l'intégration est désactivée ; hook onDeactivate.
• uninstall — l'intégration est désinstallée ; hook onUninstall.

Vous branchez votre logique métier sur ces hooks facultatifs — onActivate, onDeactivate, onUninstall, onConfigUpdated — déclarés dans defineIntegration({ hooks: { … } }). Le kit prend en charge la réception, la vérification de signature et la distribution.

installation_id : un jeton opaque

Chaque installation est identifiée par un installation_id : un jeton opaque émis par ShopiMind, stable au travers d'une désinstallation suivie d'une réinstallation.

Le kit vous l'expose sous le nom ctx.installationId dans tous vos callbacks. Ne l'interprétez jamais : ce n'est pas un identifiant interne et son format ne doit pas être analysé. Utilisez-le tel quel comme clé de corrélation du côté de votre service.

Carte des sections

Suivez ces pages dans l'ordre pour construire votre intégration de bout en bout.

• Démarrage rapide — votre première intégration : installer le kit, un defineIntegration minimal, l'exécuter en local, émettre le manifeste.
• Le kit — le contrat complet de defineIntegration, l' IntegrationContext, le runtime createIntegrationApp, les routes HTTP exposées et le stockage.
• Configuration — config_schema (étapes, champs, groupes), champs sensibles, test de connexion, options dynamiques via remote-data.
• Synchroniser les données — pousser vos données : SyncStep, curseur sûr, pagination, provisioning, ctx.sendBulk, ctx.withSource (sources dédiées) et ctx.customData.
• Cycle de vie & webhooks — événements, signature HMAC vérifiée par le kit, hooks de cycle de vie, contrat de réponse.
• Middleware entrant — exposez des routes que votre application appelle pour déclencher un événement ou pousser des données en temps réel, avec HMAC par installation.
• Widgets — déclarez des widgets (image, HTML statique, HTML dynamique) dans widgets.
• Manifeste — générez le manifeste neutre avec yarn print:manifest et envoyez-le à ShopiMind pour l'enregistrement.
• Studio (générateur JSON) — générez vos déclarations config_schema et widgets sans coder, à coller dans votre defineIntegration.
• Archétypes — fidélité, avis, POS, CRM : quelles briques du kit pour quel besoin.
• Exemple : Hiboutik POS — une intégration réelle, de bout en bout.
• Exemple : programme de fidélité — une intégration de fidélité, de bout en bout.
• Connecteur e-commerce — construire une plateforme e-commerce autonome (p. ex. Odoo) via le SDK / l'API directement.