Calling the ShopiMind API

Once the activate event has been received, the access_token issued to the installation becomes usable. It is an API key that you send via the spm-api-key header — the simplest approach is to use the official JavaScript SDK.

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

// A client bound to a store's access_token
const client = SpmClient.getClient('v1', accessToken, { labelSource: null });

await SpmCustomers.bulkSave(client, customers, { chunk: true });

The key is only valid during the "active" status

Any call before activate or after deactivate / uninstall returns 401. Defer your calls to the moment when the integration is active.

labelSource: null

Set labelSource: null when creating the client, then set id_data_source yourself on each item. This lets you attribute your data to the correct source (useful for a multi-source parent / child model — one store per point of sale, for example).

Data sources

A data source identifies the origin of what you ingest. Create a source (parent), then optionally sub-sources (children), and tag your items with id_data_source.

const sources = await SpmDataSources.list(client);

const res = await SpmDataSources.create(client, {
  label: 'Hiboutik POS',
  type: 'api',
});

Custom data

Model your own business objects, then push records (automatic chunking):

const { SpmCustomDataDefinitions, SpmCustomDataRecords } = require('@shopimind/sdk-shopimind');

const def = await SpmCustomDataDefinitions.create(client, {
  name: 'POS profile',
  fields: [ /* … */ ],
});

await SpmCustomDataRecords.bulkSave(client, def.data.data.id, records, { chunk: true });

See the Custom data guide.

Synchronize customers, orders, products

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

await SpmCustomers.bulkSave(client, customers, { chunk: true });
await SpmOrders.bulkSave(client, orders, { chunk: true });
await SpmProducts.bulkSave(client, products, { chunk: true });

Writes are idempotent by external identifier (customer_id, order_id, …): re-sending an item updates it. See Resources & methods.

Events

Declare an event type, then trigger it for a contact:

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

await SpmEvents.create(client, {
  name: 'Abandoned cart',
  code_name: 'cart_abandoned',
  properties: { /* … */ },
});

await SpmEvents.trigger(client, 'cart_abandoned', {
  contact: { email: 'client@example.com' },
  metaData: { cart_total: 42 },
});

See the External events guide.

Resilience

The SDK handles retry (429 / 5xx / network) and chunking of large batches for you. Always check the response envelope:

const res = await SpmCustomers.bulkSave(client, customers, { chunk: true });
if (!res.ok) {
  console.error('Failed', res.error);   // res.error.code, res.error.retryable
}

Details: SDK resilience.