Utilisation

Créer un client

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

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

Toutes les options

const client = SpmClient.getClient('v1', 'your-api-key', {
  baseUrl: 'https://core-staging.shopimind.com',
  headers: { 'x-trace-id': 'abc-123' },
  timeout: 60000,
  labelSource: 'web',
  retry: { maxRetries: 3 },
});

Option	Type	Défaut	Rôle
baseUrl	string	https://core.shopimind.com	URL de base de l'API
headers	Record<string,string>	{}	Headers additionnels
timeout	number	30000	Timeout de requête (ms)
labelSource	string | null	'web'	Injecté en label_source sur les POST/PUT de synchro. null désactive.
retry	SpmRetryOptions | false	voir Résilience	Politique de retry

La base URL peut aussi venir de la variable d'environnement SHOPIMIND_CORE_API_BASE. Priorité : options.baseUrl > SHOPIMIND_CORE_API_BASE > défaut.

L'enveloppe de réponse

Toutes les méthodes retournent le même objet, succès ou échec. Le SDK ne lève jamais d'exception sur une erreur HTTP.

{
  ok: true | false,
  statusCode: 200 | 4xx | 5xx | 0,
  data: {/* corps de l'API */} | null,
  error: null | {
    message: string,
    code: string,        // 'HTTP_503', 'ETIMEDOUT', …
    retryable: boolean,
    attempts: number,
    details?: any,
  },
}

const res = await SpmCustomers.bulkSave(client, items);

if (res.ok) {
  console.log(res.data.sent_count, res.data.rejected_count);
} else if (res.error.retryable) {
  console.warn('Échec transitoire — API momentanément indisponible');
} else {
  console.error('Échec permanent', res.error.message);
}

Lire des données

// Liste paginée — la query est sérialisée en query-string
const page = await SpmCustomers.list(client, { limit: 50, offset: 0 });

// Un élément par identifiant (+ projection de champs optionnelle)
const customer = await SpmCustomers.get(client, 'cust_1', ['email', 'first_name']);
const order    = await SpmOrders.get(client, 'ord_123');
const byRef    = await SpmOrders.getByReference(client, 'CMD-2024-0001');

// Sous-ressources d'un parent
const addresses = await SpmCustomersAddresses.list(client, 'cust_1', { limit: 20 });
const groups    = await SpmCustomers.listGroups(client, 'cust_1');

Écrire des données

Statique — opérations en lot (recommandé pour la synchro)

await SpmCustomers.bulkSave(client, items, { chunk: true });
await SpmCustomers.bulkUpdate(client, items, { chunk: true });
await SpmCustomers.delete(client, 'cust_1');
await SpmCustomers.bulkDelete(client, ['cust_1', 'cust_2']);

Instance — un item à la fois

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

const customer = new SpmCustomers(client);
customer.customer_id = 'cust_1';
customer.email = 'foo@bar.com';
customer.first_name = 'Foo';
customer.last_name = 'Bar';
customer.lang = 'fr';
customer.is_active = true;
customer.created_at = '2026-01-01T00:00:00Z';
customer.updated_at = '2026-01-01T00:00:00Z';

const res = await customer.save();   // ou .update()

Ressources imbriquées (addresses, images, variations)

Le constructeur prend le parent ; les méthodes statiques prennent le parent en 2ᵉ argument :

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

await SpmCustomersAddresses.bulkSave(client, 'cust_1', addresses, { chunk: true });
await SpmCustomersAddresses.bulkDelete(client, 'cust_1', [42, 43]);

Endpoint plat bulkSaveAll

Payload plat avec le parent embarqué dans chaque item (batch multi-parents) :

await SpmCustomersAddresses.bulkSaveAll(client, [
  { customer_id: 'cust_1', address_id: 1, /* ... */ },
  { customer_id: 'cust_2', address_id: 2, /* ... */ },
], { chunk: true });

Associer une source de données (data_source)

Les ressources de synchronisation acceptent optionnellement un identifiant ou libellé de source :

customer.id_data_source = 3;
customer.source_label = 'Magasin Paris';
await customer.save();

Enregistrer une boutique

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

// POST /shop/connection attend 3 headers : client-id, client-version, current-build
const client = SpmClient.getClient('v1', apiKey, {
  headers: { 'client-id': clientId, 'client-version': '5.0.0', 'current-build': '1' },
});

await SpmShopConnection.saveConfiguration(client, {
  default_currency: 'EUR',
  default_lang: 'fr',
  langs: ['fr', 'en'],
  timezone: 'Europe/Paris',
  url_client: 'https://myshop.example.com',
  ecommerce_version: '2.7.0',
  module_version: '5.0.0',
});

Suite : Résilience (retry, chunking, helpers).