Reference

This page gathers the section's normative contracts: headers, routes, the target scope of a complete connector, a compliance checklist and a troubleshooting grid.

Headers

Direction	Header
You → ShopiMind	spm-api-key · client-id · client-version · current-build
ShopiMind → you	Shopimind-Client-Identifiant · Shopimind-Token · Shopimind-Client-Version · Shopimind-Client-Build · type-request

All routes

Outbound: you call ShopiMind

Route	Purpose
POST /v1/shop/connection	Connection
POST|PUT|DELETE /v1/{entity}	Pushing data
GET {tracking}/api/assets/js/spm.js	The spm.js loader: the tracking integration

Inbound: you expose, ShopiMind calls

Route	Action	Required?
POST {url_client}/vouchers	generateVouchers	For scenario vouchers
POST {url_client}/customers	createCustomer	For widgets with accounts
POST {url_client}/subscribe-customer	subscribeCustomer	For opt-in widgets

Target scope of a complete connector

This matrix reflects the coverage of ShopiMind's official modules. It is a target: it tells you what a "complete" connector covers, each entity pushed on events (creation, modification, deletion), complemented by scheduled incremental passes on your side.

Entity	Deletions
Customer groups	logical delete
Customers	logical delete
Customer addresses	logical delete
Newsletter subscribers	opt-out
Orders	logical delete
Order statuses	logical delete
Carriers	is_active
Products	is_active + logical delete
Variations	logical delete
Product images	logical delete
Categories	is_active
Manufacturers	is_active
Vouchers	is_active

Channels covered: push on events · vouchers, customers and subscribe-customer callbacks · tracking tag injection.

Format conventions

Topic	Convention
Dates	ISO 8601 with microseconds and the real offset: 2026-08-04T11:42:07.000000+02:00
Identifiers	Always strings
Amounts	Currency precision (2 for EUR/USD, 0 for JPY, 3 for BHD)
Languages	ISO 639-1
Currencies	ISO 4217
Timezones	IANA (Europe/Paris)
Booleans	JSON booleans

Compliance checklist

Connection

• [ ] All four headers are sent (spm-api-key, client-id, client-version, current-build)
• [ ] url_client points at the connector service, served over HTTPS with no redirect
• [ ] langs holds the complete list of active languages
• [ ] timezone is an IANA identifier
• [ ] The connection is replayed after a configuration change or a key rotation
• [ ] A single API key is used for the connector

Data push

• [ ] Upsert on a stable business key
• [ ] Dependency order respected on backfill (3 waves)
• [ ] Cursor advanced only after a fully successful pass
• [ ] rejected_count and rejected_items logged
• [ ] Deletions propagated (on hooks or by nightly reconciliation)
• [ ] Dates in ISO 8601 with the real offset, identifiers as strings

Inbound callbacks

• [ ] Body read raw then parsed as form-urlencoded (no automatic JSON parsing)
• [ ] Signature verified before any processing
• [ ] First level only sorted when flattening
• [ ] HMAC key = hex string of sha256(secret)
• [ ] Constant-time comparison
• [ ] codeToGenerate treated as an idempotence key
• [ ] Always HTTP 200 with success in the body; no uncaught exception

Tracking

• [ ] The spm.js loader tag pasted once per document, with the shop identifier
• [ ] spm('consent', …) wired to the CMP, nothing leaves before approval
• [ ] spm('identify', …) on the first render when the session is known
• [ ] spm('cart', …) called on every cart mutation, emptied carts included
• [ ] spm('order', …) on the order confirmation page
• [ ] First-party tracking domain in place (mandatory in headless)

Troubleshooting grid

Symptom	Most likely cause	Check
POST /shop/connection → 401	spm-api-key missing	Are all four headers present?
POST /shop/connection → 400 Missing required headers	current-build forgotten	It is the 4th header, the easiest to miss
POST /shop/connection → 400 with no message	A required body field is missing	Are all 7 required fields there?
Inbound callback → Unauthorized	Divergent flattening (sorting every level) or HMAC key built on bytes instead of the hex string	Replay the vector testConnection;1785412468;type;customers
Inbound callback → empty body	Redirect on the route (trailing slash, http→https, apex→www) or automatic JSON parsing	Serve the exact url_client URL; read the raw body
No callback ever arrives	Wrong url_client, or shop still configured on an official module	Check url_client; ask us to move the shop to generic connector mode
Vouchers not generated	Response without a populated vouchers	success: true and a non-empty vouchers are both required
The tag starts nothing	Unknown shop identifier, or inactive subscription	Compare with the identifier shown in API access
Duplicate vouchers	Callback replayed after a timeout, with no idempotence	Treat codeToGenerate as a unique key
Dates off	Non-IANA timezone, or dates sent as Z while the shop is local	Check the ISO 8601 format with the real offset

Going further

• API reference: field-by-field detail for every endpoint
• JavaScript SDK: transport, retries, chunking, signature primitives
• Custom data · External events
• Integrations: if your product grafts onto an account rather than being the shop