Démarrage rapide

Cette page vous mène d'une boutique ShopiMind vide à un connecteur qui déclare la boutique puis pousse ses premières données. Comptez une trentaine de minutes. Les canaux « rappels entrants » et « tracking » viennent ensuite, chacun dans sa page.

Avant de commencer

• Une boutique ShopiMind et un accès au dashboard.
• Node.js 18+ si vous suivez les exemples SDK. Sinon, tous les appels sont donnés aussi en HTTP brut : l'API REST est le contrat, le SDK n'est qu'une commodité.

1. Récupérer vos identifiants

Ouvrez Paramètres de la boutique → Accès API. Vous y trouvez deux choses distinctes :

	Ce que c'est	Confidentialité
Identifiant de la boutique	Identifie la boutique. Format court, ex. SPM123456.	Public : il apparaît en clair dans le HTML de votre boutique (canal tracking).
Clé API	Authentifie vos appels. Format {prefix}.{secret}, affichée une seule fois à la création.	Secrète : variable d'environnement ou coffre. Jamais dans un dépôt ni dans du code front.

Générez une clé dédiée à votre connecteur et notez-la. Nous les appellerons SPM_SHOP_IDENTIFIER et SPM_API_KEY.

Une seule clé pour le connecteur

L'appel de connexion (étape 3) marque la clé utilisée comme clé primaire de la boutique, celle qui servira ensuite à signer les rappels entrants. N'exécutez donc jamais cet appel avec une clé d'exploration ou de test : vous casseriez la signature des bons de réduction. → Connexion

2. Installer le SDK (facultatif)

yarn add @shopimind/sdk-js

Le SDK est ESM uniquement (Node ≥ 18.17) et n'a qu'une dépendance : axios. Il fournit le transport durci (TLS vérifié, redirections non suivies pour ne pas fuiter la clé, plafonds de taille), les relances automatiques, le découpage en lots et une enveloppe de réponse uniforme.

import { SpmClient } from '@shopimind/sdk-js';

const client = SpmClient.getClient('v1', process.env.SPM_API_KEY!);

3. Connecter la boutique

C'est l'appel qui déclare votre boutique auprès de ShopiMind : devise, langues, fuseau, et surtout url_client, la racine des rappels entrants. À faire une fois à l'installation, puis à chaque fois que la configuration change.

Quatre en-têtes sont obligatoires. L'oubli du dernier est l'erreur la plus fréquente.

curl -X POST 'https://core.shopimind.com/v1/shop/connection' \
  -H "spm-api-key: $SPM_API_KEY" \
  -H "client-id: $SPM_SHOP_IDENTIFIER" \
  -H 'client-version: 1.0.0' \
  -H 'current-build: 1' \
  -H 'Content-Type: application/json' \
  -d '{
    "default_currency":  "EUR",
    "default_lang":      "fr",
    "langs":             ["fr", "en"],
    "timezone":          "Europe/Paris",
    "url_client":        "https://connector.ma-boutique.com/shopimind",
    "ecommerce_version": "1.0.0",
    "module_version":    "1.0.0"
  }'

Avec le SDK, les en-têtes de connexion passent par les options du client :

import { SpmClient, SpmShopConnection } from '@shopimind/sdk-js';

const client = SpmClient.getClient('v1', process.env.SPM_API_KEY!, {
  headers: {
    'client-id':      process.env.SPM_SHOP_IDENTIFIER!,
    'client-version': '1.0.0',
    'current-build':  '1',
  },
});

const res = await SpmShopConnection.saveConfiguration(client, {
  default_currency:  'EUR',
  default_lang:      'fr',
  langs:             ['fr', 'en'],
  timezone:          'Europe/Paris',
  url_client:        'https://connector.ma-boutique.com/shopimind',
  ecommerce_version: '1.0.0',
  module_version:    '1.0.0',
});

if (!res.ok) throw new Error(res.error.message);

Une réponse 200 signifie que la boutique est déclarée. → Contrat complet

4. Pousser vos premières données

L'ordre compte : une entité ne peut pas référencer quelque chose qui n'existe pas encore. Pour un premier essai, poussez des catégories, puis des produits, puis des clients.

import { SpmProductsCategories, SpmProducts, SpmCustomers } from '@shopimind/sdk-js';

// 1) Catégories, avant les produits qui les référencent
await SpmProductsCategories.bulkSave(client, [
  {
    category_id: 'CAT-1',
    name:        'Cigarettes électroniques',
    is_active:   true,
    created_at:  '2026-01-15T10:00:00.000000+01:00',
    updated_at:  '2026-01-15T10:00:00.000000+01:00',
  },
], { chunk: true });

// 2) Produits
await SpmProducts.bulkSave(client, [
  {
    product_id:   'P-4471',
    name:         'Kit débutant',
    price:        49.9,
    category_ids: ['CAT-1'],
    is_active:    true,
    created_at:   '2026-01-15T10:00:00.000000+01:00',
    updated_at:   '2026-02-01T09:12:00.000000+01:00',
  },
], { chunk: true });

// 3) Clients
const res = await SpmCustomers.bulkSave(client, [
  {
    customer_id: '4212',
    email:       'marie@exemple.fr',
    first_name:  'Marie',
    last_name:   'Dupont',
    is_active:   true,
    created_at:  '2025-11-02T14:30:00.000000+01:00',
    updated_at:  '2026-02-01T09:12:00.000000+01:00',
  },
], { chunk: true });

console.log(res.data); // { sent_count, rejected_count, rejected_items }

En HTTP brut, c'est le même corps, un tableau d'objets :

curl -X POST 'https://core.shopimind.com/v1/customers' \
  -H "spm-api-key: $SPM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '[{ "customer_id": "4212", "email": "marie@exemple.fr", "first_name": "Marie",
        "last_name": "Dupont", "is_active": true,
        "created_at": "2025-11-02T14:30:00.000000+01:00",
        "updated_at": "2026-02-01T09:12:00.000000+01:00" }]'

Un 200 ne veut pas dire « tout est passé »

Les écritures en lot sont asynchrones et partiellement tolérantes : un 200 confirme la mise en file, et les objets invalides sont rejetés individuellement sans interrompre le lot. Vérifiez toujours rejected_count et rejected_items : chaque rejet vous renvoie le payload d'origine et la liste des champs fautifs. → Gérer les rejets

5. Vérifier

Relisez ce que ShopiMind a effectivement enregistré :

curl -s 'https://core.shopimind.com/v1/customers?limit=5' -H "spm-api-key: $SPM_API_KEY"

Comptez quelques secondes entre l'écriture et la lecture : le traitement est asynchrone.

Dans le dashboard, les données apparaissent dans les écrans Contacts et Catalogue. Un client poussé matérialise aussi un contact : c'est le profil unifié que ciblent les scénarios.

Et ensuite

Vous voulez…	Allez à
Comprendre l'ordre des entités et les curseurs	Pousser les données
Faire fonctionner la relance de panier abandonné	Script de tracking
Générer des bons nominatifs depuis un scénario	Rappels entrants
La liste des entités et le périmètre cible	Référence