Integrations

An integration is a product that plugs into an existing ShopiMind account — CRM, ERP, point of sale (POS), loyalty platform, reviews service, carrier… It receives a shop's lifecycle events and pushes its data into ShopiMind, alongside the e-commerce data.

You don't write all of that by hand. The JavaScript integration kit @shopimind/integration-kit-js provides the complete runtime: webhook server, signature verification, scheduler, an encrypted local store (a SQLite database, inside your own service), and typed access to the ShopiMind API. You describe your integration with a single call — defineIntegration({ … }) — and the kit does the rest.

The starting point: the kit

Everything starts with @shopimind/integration-kit-js. You declare your integration there, the kit mounts the server, verifies every signed webhook, schedules the syncs, and hands you an already-authenticated API client. → The kit in detail · → Quickstart

Integration or e-commerce connector?

• An integration (POS, CRM, loyalty, reviews…) plugs into an existing ShopiMind account and is built with the kit @shopimind/integration-kit-js. This is what this section is about.
• An e-commerce connector (PrestaShop, WooCommerce, Odoo…) is a standalone platform. It is built directly via the SDK or the API, with its own signed callback channel and its own tracking script. → E-commerce connectors.

	Integration	E-commerce connector
What it is	A third-party product plugged into an account (POS, CRM, loyalty, reviews…)	A standalone e-commerce platform (PrestaShop, WooCommerce, Odoo…)
Example	Hiboutik POS	PrestaShop, Odoo
How to build it	The kit @shopimind/integration-kit-js	The SDK / API directly — see E-commerce connectors
Data pushed	A targeted scope + dedicated sources (customers, orders, point-of-sale products…)	The full catalog (customers, products, categories, orders…)

The building-block model

A ShopiMind integration is organized around four clearly separated building blocks.

Building block	What it is	Who writes it
The SDK (@shopimind/sdk-js)	Transport: the outbound HTTP client and typed resources for the ShopiMind API	ShopiMind (you use it)
The kit (@shopimind/integration-kit-js)	Runtime: webhooks, signature, scheduler, store. Depends on and re-exports the SDK	ShopiMind (you use it)
Your integration	Your declarations and functions, passed to defineIntegration	You
The ShopiMind core	The platform: emits signed webhooks, receives your data via the API	ShopiMind

In practice, you only write the third building block. The kit depends on and re-exports the SDK (export * from '@shopimind/sdk-js'), so you import SDK resources and types from the kit — no separate SDK install needed in your integration.

You push your data through ctx.spm, which is a raw SpmHttpClient (built and authenticated by the kit). You call the SDK's static methods on it:

import { SpmCustomers, SpmEvents } from '@shopimind/integration-kit-js';

await SpmCustomers.bulkSave(ctx.spm, items, { chunk: true });
await SpmEvents.trigger(ctx.spm, codeName, payload);

The SDK returns an envelope { ok, statusCode, data, error } and never throws on an HTTP error. For sync steps and inbound handlers, prefer ctx.sendBulk(fn, items): it sends in chunks, throws on a transport failure, surfaces per-item rejections, and lets the engine hold the cursor — no silent data loss.

The kit builds on the SDK

The SDK is the transport layer; the kit depends on it, re-exports it, and gives you an already-authenticated ctx.spm. You import SDK resources and types straight from the kit. → JavaScript SDK

The three communication directions

An integration is a middleware between your application and ShopiMind: it communicates in three directions, each with its own mechanism — all handled by the kit.

Direction	Who calls	How it is authenticated
Outbound — integration → ShopiMind	You call the ShopiMind API to push your data	Shop API key in the spm-api-key header (handled by the SDK, via ctx.spm)
Inbound — lifecycle — ShopiMind → integration	ShopiMind calls your webhooks (lifecycle, test, remote data)	HMAC-SHA256 signature X-Shopimind-Signature, verified by the kit
Inbound — middleware — your app → integration	Your application calls your inbound routes to trigger an event or push data in real time	Per-installation HMAC signature (x-integration-*), verified by the kit

You have no signature to code

The kit verifies both inbound directions (HMAC-SHA256, anti-replay window, constant-time comparison) before your code is even called. A poorly signed request never reaches your callbacks. → Lifecycle & webhooks · → Inbound middleware

Installation lifecycle

ShopiMind drives the installation through a sequence of lifecycle events, delivered to your signed webhooks and dispatched by the kit to your hooks.

install  →  (configure)  →  activate  →  … config_updated …  →  deactivate  →  uninstall

• install — the user installs your integration from ShopiMind.
• configure — the user fills in the fields you declared in configSchema (see Configuration).
• activate — the integration is activated; your calls to the ShopiMind API work. The kit applies your provisioning and then calls your onActivate hook.
• config_updated — on every configuration change.
• deactivate — the integration is deactivated; onDeactivate hook.
• uninstall — the integration is uninstalled; onUninstall hook.

You hook your business logic onto these optional hooks — onActivate, onDeactivate, onUninstall, onConfigUpdated — declared in defineIntegration({ hooks: { … } }). The kit handles reception, signature verification, and dispatch.

installation_id: an opaque token

Each installation is identified by an installation_id: an opaque token issued by ShopiMind, stable across an uninstall followed by a reinstall.

The kit exposes it to you as ctx.installationId in all your callbacks. Never interpret it: it is not an internal identifier and its format must not be parsed. Use it as-is as a correlation key on your service's side.

Section map

Follow these pages in order to build your integration end to end.

• Quickstart — your first integration: install the kit, a minimal defineIntegration, run it locally, emit the manifest.
• The kit — the full defineIntegration contract, the IntegrationContext, the createIntegrationApp runtime, the exposed HTTP routes, and the store.
• Configuration — config_schema (steps, fields, groups), sensitive fields, connection test, dynamic options via remote-data.
• Synchronize data — pushing your data: SyncStep, safe cursor, pagination, provisioning, ctx.sendBulk, ctx.withSource (dedicated sources), and ctx.customData.
• Lifecycle & webhooks — events, HMAC signature verified by the kit, lifecycle hooks, response contract.
• Inbound middleware — expose routes that your application calls to trigger an event or push data in real time, with per-installation HMAC.
• Widgets — declare widgets (image, static HTML, dynamic HTML) in widgets.
• Manifest — generate the neutral manifest with yarn print:manifest and send it to ShopiMind for registration.
• Studio (JSON generator) — generate your config_schema and widgets declarations without coding, to paste into your defineIntegration.
• Archetypes — loyalty, reviews, POS, CRM: which kit building blocks for which need.
• Example: Hiboutik POS — a real integration, end to end.
• Example: loyalty program — a loyalty integration, end to end.
• E-commerce connectors — build a standalone e-commerce platform (e.g. Odoo, a headless front end) via the SDK / API directly.