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.