Référence

Cette page rassemble les contrats normatifs de la section : les en-têtes, les routes, le périmètre cible d'un connecteur complet, une checklist de conformité et une grille de diagnostic.

En-têtes

Sens	En-tête
Vous → ShopiMind	spm-api-key · client-id · client-version · current-build
ShopiMind → vous	Shopimind-Client-Identifiant · Shopimind-Token · Shopimind-Client-Version · Shopimind-Client-Build · type-request

Toutes les routes

Sortantes : vous appelez ShopiMind

Route	Usage
POST /v1/shop/connection	Connexion
POST|PUT|DELETE /v1/{entité}	Pousser les données
GET {tracking}/api/assets/js/spm.js	Le loader spm.js : l'intégration du tracking

Entrantes : vous exposez, ShopiMind appelle

Route	Action	Obligatoire ?
POST {url_client}/vouchers	generateVouchers	Pour les bons de scénario
POST {url_client}/customers	createCustomer	Pour les widgets avec compte
POST {url_client}/subscribe-customer	subscribeCustomer	Pour les widgets d'opt-in

Périmètre cible d'un connecteur complet

Cette matrice reflète la couverture des modules officiels ShopiMind. Elle sert de cible : elle vous dit ce qu'un connecteur « complet » couvre, chaque entité poussée sur événement (création, modification, suppression), complétée par des passes incrémentales planifiées de votre côté.

Entité	Suppressions
Groupes clients	suppression logique
Clients	suppression logique
Adresses clients	suppression logique
Abonnés newsletter	opt-out
Commandes	suppression logique
Statuts de commande	suppression logique
Transporteurs	is_active
Produits	is_active + suppression logique
Déclinaisons	suppression logique
Images produits	suppression logique
Catégories	is_active
Fabricants	is_active
Bons de réduction	is_active

Canaux couverts : push sur événement · rappels vouchers, customers et subscribe-customer · injection du tag de tracking.

Conventions de format

Sujet	Convention
Dates	ISO 8601 avec microsecondes et décalage réel : 2026-08-04T11:42:07.000000+02:00
Identifiants	Toujours en chaînes
Montants	Précision de la devise (2 pour EUR/USD, 0 pour JPY, 3 pour BHD)
Langues	ISO 639-1
Devises	ISO 4217
Fuseaux	IANA (Europe/Paris)
Booléens	Booléens JSON

Checklist de conformité

Connexion

• [ ] Les quatre en-têtes sont envoyés (spm-api-key, client-id, client-version, current-build)
• [ ] url_client pointe sur le service du connecteur, servi en HTTPS sans redirection
• [ ] langs contient la liste complète des langues actives
• [ ] timezone est un identifiant IANA
• [ ] La connexion est rejouée après un changement de configuration ou une rotation de clé
• [ ] Une seule clé API est utilisée pour le connecteur

Push de données

• [ ] Upsert sur une clé métier stable
• [ ] Ordre des dépendances respecté au backfill (3 vagues)
• [ ] Curseur avancé uniquement après une passe entièrement réussie
• [ ] rejected_count et rejected_items journalisés
• [ ] Suppressions propagées (sur hook ou par réconciliation nocturne)
• [ ] Dates au format ISO 8601 avec décalage réel, identifiants en chaînes

Rappels entrants

• [ ] Corps lu en brut puis parsé en form-urlencoded (pas de parsing JSON automatique)
• [ ] Signature vérifiée avant tout traitement
• [ ] Tri du premier niveau seulement dans l'aplatissement
• [ ] Clé HMAC = chaîne hexadécimale de sha256(secret)
• [ ] Comparaison à temps constant
• [ ] codeToGenerate traité comme clé d'idempotence
• [ ] Toujours HTTP 200 avec success dans le corps ; aucune exception non capturée

Tracking

• [ ] Tag du loader spm.js collé une fois par document, avec l'identifiant de la boutique
• [ ] spm('consent', …) branchée sur la CMP, rien ne part avant l'accord
• [ ] spm('identify', …) dès le premier rendu quand la session est connue
• [ ] spm('cart', …) appelée à chaque mutation du panier, paniers vidés compris
• [ ] spm('order', …) sur la page de confirmation de commande
• [ ] Domaine de tracking first-party en place (obligatoire en headless)

Grille de diagnostic

Symptôme	Cause la plus probable	Vérification
POST /shop/connection → 401	spm-api-key absent	Les quatre en-têtes sont-ils présents ?
POST /shop/connection → 400 Missing required headers	current-build oublié	C'est le 4ᵉ en-tête, le plus facile à manquer
POST /shop/connection → 400 sans message	Un champ obligatoire du corps manque	Les 7 champs obligatoires sont-ils tous là ?
Rappel entrant → Unauthorized	Aplatissement divergent (tri de tous les niveaux) ou clé HMAC sur les octets au lieu de la chaîne hexa	Rejouer le vecteur testConnection;1785412468;type;customers
Rappel entrant → corps vide	Redirection sur la route (slash final, http→https, apex→www) ou parsing JSON automatique	Servir l'URL exacte de url_client ; lire le corps brut
Aucun rappel ne parvient	url_client incorrect, ou boutique encore configurée sur un module officiel	Vérifier url_client ; nous demander de basculer la boutique en mode connecteur générique
Bons non générés	Réponse sans vouchers renseigné	success: true et vouchers non vide sont requis
Le tag ne démarre rien	Identifiant de boutique inconnu, ou abonnement inactif	Comparer à l'identifiant affiché dans Accès API
Doublons de bons	Rejeu d'un rappel après timeout, sans idempotence	Traiter codeToGenerate comme clé unique
Dates décalées	timezone non-IANA, ou dates envoyées en Z alors que la boutique est locale	Vérifier le format ISO 8601 avec décalage réel

Pour aller plus loin

• Référence API : le détail champ par champ de chaque endpoint
• SDK JavaScript : transport, relances, découpage en lots, primitives de signature
• Données personnalisées · Événements externes
• Intégrations : si votre produit se greffe sur un compte plutôt que d'être la boutique