Partner integrations

An integration connects your product (CRM, ERP, POS, loyalty platform, carrier…) to ShopiMind: you receive a shop's lifecycle events, and you push your data to ShopiMind through the API.

This section is intended for partner integrators. To simply synchronize the data of a standard e-commerce shop, see the e-commerce connector instead.

The two-way model

An integration communicates with ShopiMind in two directions:

Direction	Who calls	How it is authenticated
Inbound — ShopiMind → you	ShopiMind calls your webhooks (install, activate, config…)	HMAC-SHA256 signature (see Lifecycle & webhooks)
Outbound — you → ShopiMind	You call the ShopiMind API to push data	spm-api-key API key issued at installation (see Calling the API)

You therefore only host a small webhook server, and you consume the ShopiMind API with the official SDK — exactly what the starter provides.

Installation lifecycle

Install  →  (Configure)  →  Activate  →  … config_updated …  →  Deactivate  →  Uninstall

1. Install — the user installs your integration from ShopiMind. You receive an install webhook containing an access_token (the API key to keep). At this stage the key is revoked: no API call is possible yet.
2. Configure — the user fills in the configuration fields you declared (see Configuration).
3. Activate — the user activates the integration. ShopiMind un-revokes the key then sends you activate with the configuration values. Only now do your calls to the ShopiMind API work.
4. config_updated — on every configuration change (best-effort).
5. Deactivate — the user deactivates: ShopiMind re-revokes the key.
6. Uninstall — the user uninstalls: ShopiMind deletes the configuration and revokes the key permanently.

The API key is only valid while the status is "active"

Any call to the ShopiMind API before activate or after deactivate returns 401. Store the access_token received at install — you will not receive it a second time.

Two installation types

• Type A — direct API key: ShopiMind creates the installation and sends you the install webhook directly with the access_token. No external authentication.
• Type B — OAuth: your product requires the user to authenticate with you first. ShopiMind redirects the browser to your consent page, then you send them back to ShopiMind. See the details in Lifecycle & webhooks.

Security in brief

• Inbound webhooks: verify the HMAC-SHA256 signature of each request before processing it (X-Shopimind-Signature / X-Shopimind-Timestamp headers).
• Response contract: always respond with HTTP 200 and { "success": true }. Any other code/body is treated as a failure.
• API key: passed only via the spm-api-key header, valid during the active window.

This section

• Lifecycle & webhooks — events, payloads, HMAC, OAuth, retries.
• Configuration — config schema, steps, connection test, remote data.
• Widgets — declare widgets (image / static HTML / dynamic HTML).
• Studio (JSON generator) — generate your declarations without coding.
• Calling the ShopiMind API — push your data with the SDK.
• Starter — the ready-to-clone starter project.

Get started quickly

Do not start from a blank page: the integration starter already wires up all the webhooks, HMAC verification, Type B OAuth and a local store of installations.