Configuration

Votre intégration déclare un schéma de configuration (config_schema). ShopiMind en génère automatiquement le formulaire dans l'interface ; les valeurs saisies vous sont transmises (déchiffrées) dans les webhooks activate et config_updated.

Schéma plat

{
  "fields": [
    { "key": "api_url",   "type": "url",      "required": true,  "label": "URL de l'API" },
    { "key": "api_token", "type": "password", "required": true,  "label": "Jeton" },
    { "key": "list_id",   "type": "select",   "required": false, "label": "Liste",
      "options": [{ "value": "vip", "label": "VIP" }, { "value": "all", "label": "Tous" }] }
  ]
}

Types de champ

text · password · textarea · email · url · number · select · multiselect · checkbox.

Règles de validation possibles : minLength / maxLength / pattern (texte), min / max / step (nombre).

Champs sensibles

Les champs password / secret / token sont chiffrés au repos côté ShopiMind. Ils vous sont transmis déchiffrés dans activate / config_updated, jamais exposés ailleurs.

Schéma multi-étapes

Pour les configurations en plusieurs temps (ex. saisir des identifiants, puis choisir une liste qui dépend de ces identifiants) :

{
  "steps": [
    {
      "key": "credentials",
      "label": "Identifiants",
      "fields": [
        { "key": "api_url",   "type": "url",      "required": true },
        { "key": "api_token", "type": "password", "required": true }
      ],
      "on_complete": { "action": "test_connection" }
    },
    {
      "key": "mapping",
      "label": "Correspondances",
      "fields": [
        { "key": "list_id", "type": "select", "required": true }
      ]
    }
  ]
}

• La sauvegarde partielle (étape par étape) est autorisée.
• Avec on_complete: { action: "test_connection" }, l'étape n'est considérée valide qu'après un test de connexion réussi. Modifier un champ d'une étape validée invalide sa validation.
• La complétude de toutes les étapes est exigée à l'activation.

test_connection

Lorsque l'utilisateur valide une étape on_complete: test_connection (ou clique « Tester »), ShopiMind envoie un webhook signé à l'URL test_connection que vous avez déclarée. Le corps est la map des configs (déchiffrées), sans enveloppe event :

{ "api_url": "https://...", "api_token": "..." }

Répondez (HTTP 200) :

{ "success": true }

ou

{ "success": false, "error": "Impossible de joindre le service" }

remote-data/<resource> — listes dynamiques

Pour peupler un select / multiselect avec des valeurs venant de votre système (ex. la liste des segments du compte connecté), déclarez une URL de webhook nommée d'après la resource. ShopiMind l'appelle (webhook signé, corps = configs) et attend :

{
  "data": [
    { "value": "list_42", "label": "Clients VIP" },
    { "value": "list_7",  "label": "Newsletter" }
  ]
}

L'utilisateur voit alors label, et value est stocké comme valeur du champ.

Déclarer vos webhooks

ShopiMind associe chaque événement (et chaque resource de remote-data) à une URL de votre serveur. Vous communiquez ces URLs et votre secret HMAC à ShopiMind lors de l'enregistrement de votre intégration :

{
  "install":         "https://votre-hote/webhook/receive",
  "uninstall":       "https://votre-hote/webhook/receive",
  "activate":        "https://votre-hote/webhook/receive",
  "deactivate":      "https://votre-hote/webhook/receive",
  "config_updated":  "https://votre-hote/webhook/receive",
  "test_connection": "https://votre-hote/webhook/test-connection",
  "votre_resource":  "https://votre-hote/webhook/remote-data/votre_resource"
}

Config intégrateur (owner: "integrator")

Un champ de config_schema peut être marqué owner: "integrator" : il n'est pas affiché au marchand, et c'est l'intégrateur qui pose sa valeur par boutique, via l'API, avec sa clé d'intégration. La valeur est résolue au rendu en {integration.<key>} (avec le default déclaré comme repli tant qu'elle n'est pas posée).

Utile pour une valeur propre à l'intégrateur mais spécifique à la boutique : URL de tracking, identifiant de compte, base d'API calculée, etc.

// dans config_schema.fields (ou steps[].fields)
{ "key": "tracking_base", "type": "text", "owner": "integrator", "default": "https://t.partner.io/p" }

Poser / relire les valeurs via le SDK (avec la clé API de l'intégration) :

const { SpmIntegrationConfig } = require('@shopimind/sdk-shopimind');

await SpmIntegrationConfig.set(client, { tracking_base: 'https://t.partner.io/p' });
const res = await SpmIntegrationConfig.get(client); // res.data.data.values = { tracking_base: '…' }

Ou en HTTP direct : PUT /v1/integration-config (corps = { <key>: <value> }) et GET /v1/integration-config. Seules les clés déclarées owner: "integrator" sont acceptées ; le marchand ne peut jamais les modifier, et elles ne transitent dans aucune URL d'image (valeurs non sensibles, résolues en {integration.*}).