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 store (SQLite by default, or your own PostgreSQL database, but always inside your service, never the ShopiMind database), 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 is 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, with 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.
• Persistence & stores. Where your integration keeps its state: SQLite by default, or your own PostgreSQL database. What is encrypted, what to plan for before deploying, and how to plug in a storage backend of your own.
• 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.