Manifeste & enregistrement

Pour qu'une intégration soit installable, ShopiMind doit la connaître : son slug, sa configuration, ses widgets, ses webhooks. Vous fournissez ces informations sous forme d'un manifeste — un JSON neutre généré depuis votre code — que l'équipe ShopiMind enregistre. L'enregistrement est manuel et validé (gage de qualité de la marketplace).

1. Générer le manifeste

Le kit fournit buildIntegrationManifest(integration). Ajoutez un petit script à votre intégration :

// src/print-manifest.ts
import { buildIntegrationManifest } from '@shopimind/integration-kit-js';
import { myIntegration } from './integration.js';

console.log(JSON.stringify(buildIntegrationManifest(myIntegration), null, 2));

// package.json
{
  "scripts": {
    "print:manifest": "node dist/print-manifest.js"
  }
}

Puis :

yarn build
yarn print:manifest > integration.manifest.json

2. Ce que contient le manifeste

Champ	Contenu
manifest_version	1.
slug, name, version	Identité de l'intégration.
categories?	Catégories (slugs neutres, ex. ['pos']).
icon_url?, short_description?, description?, documentation_url?	Métadonnées d'affichage.
config_schema	Votre formulaire de configuration.
widgets	Vos widgets.
webhooks	Chemins relatifs : /webhook/receive, /webhook/test-connection, /webhook/remote-data/{resource}.
lifecycle_events	['install','activate','deactivate','uninstall','config_updated'].
remote_resources	Les ressources de vos select dynamiques (ex. ['stores']).

Un artefact volontairement neutre

Le manifeste ne contient aucun secret, aucun SQL, aucun identifiant de partenaire, aucun statut, aucune URL absolue. Il décrit votre intégration ; il ne touche pas au plan de contrôle interne de ShopiMind. Vous pouvez le versionner et le partager sans risque.

3. L'envoyer à ShopiMind

Envoyez votre integration.manifest.json à dev@shopimind.com avec :

• l'URL publique de votre intégration (l'hôte où tournent vos webhooks, ex. https://my-app.example.com) ;
• le partenaire (votre organisation) à rattacher.

4. Ce que fait ShopiMind

L'équipe technique :

1. valide le manifeste ;
2. résout les catégories (vos slugs → identifiants internes) ;
3. génère un webhook_secret (le secret HMAC qui signera les webhooks vers votre intégration) ;
4. compose les URLs absolues de vos webhooks à partir de votre hôte public (ex. https://my-app.example.com/webhook/receive) ;
5. choisit le statut (généralement inactive au départ, le temps de la revue), puis enregistre l'intégration.

5. Récupérer le webhook_secret

ShopiMind vous communique le webhook_secret généré. Reportez-le dans la variable d'environnement WEBHOOK_SECRET de votre intégration : c'est avec ce secret que le kit vérifie la signature de chaque webhook entrant (voir Cycle de vie & webhooks).

# .env de l'intégration
WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Gardez le secret côté serveur

Le webhook_secret est un secret partagé. Il ne doit jamais apparaître dans un dépôt public, un journal, ou côté client.

Mettre à jour une intégration

Quand votre intégration évolue (nouveau champ de config, nouveau widget, nouvelle version) : régénérez le manifeste (yarn print:manifest) et renvoyez-le à dev@shopimind.com. Le slug identifie votre intégration ; l'enregistrement est mis à jour. Votre webhook_secret reste inchangé.

Pour aller plus loin

• Cycle de vie & webhooks — comment le webhook_secret est utilisé.
• Configuration & Widgets — ce qui alimente le manifeste.
• Exemple complet (Hiboutik) — du code au manifeste.