Connexion

POST /v1/shop/connection déclare votre boutique auprès de ShopiMind : sa devise, ses langues, son fuseau horaire, et la racine des URLs que ShopiMind rappellera. C'est le premier appel de tout connecteur, et le seul qui soit obligatoire avant de pouvoir pousser quoi que ce soit.

→ Référence API : connectShop

Les deux identifiants

	Où le trouver	Rôle
Clé API : {prefix}.{secret}	Paramètres de la boutique → Accès API, à la génération (affichée une seule fois)	Authentifie tous vos appels, via l'en-tête spm-api-key. Résout la boutique.
Identifiant de la boutique : ex. SPM123456	Paramètres de la boutique → Accès API, encart dédié	Identifie la boutique. Envoyé en client-id ici, passé à spm('init', …) dans le tracking, et renvoyé par ShopiMind dans chaque rappel entrant.

L'identifiant de boutique est généré une seule fois, à la création de la boutique. Il n'y a aucun processus d'enrôlement partenaire à passer : si vous avez accès à la boutique, vous avez déjà tout ce qu'il faut.

L'identifiant n'est pas un secret

Il est public par construction, le script de tracking l'expose en clair dans le HTML de la boutique. Le secret, c'est la clé API. Ne les traitez pas de la même façon.

Les quatre en-têtes

Les trois en-têtes client-* s'ajoutent à spm-api-key, ils ne le remplacent pas. L'absence de spm-api-key renvoie 401 ; l'absence de l'un des trois autres renvoie 400 Missing required headers.

En-tête	Exemple	Rôle
spm-api-key	a1b2c3d4.xK9p…	Authentification. Résout la boutique cible.
client-id	SPM123456	Identifiant de la boutique. Revérifié côté serveur : la requête est rejetée s'il ne correspond pas à la boutique résolue depuis la clé.
client-version	1.0.0	Version de votre connecteur. Chaîne libre. Remontée dans nos outils de support.
current-build	1	Numéro de build de votre connecteur. Chaîne libre contenant un entier.

client-version et current-build n'ont aucun effet fonctionnel : ils servent au diagnostic. Faites-les évoluer à chaque livraison, c'est ce qui nous permet de savoir quelle version tourne chez un marchand quand vous nous appelez.

Le corps

{
  // Obligatoires
  "default_currency":  "EUR",              // ISO 4217
  "default_lang":      "fr",               // ISO 639-1
  "langs":             ["fr", "en"],       // ISO 639-1, liste COMPLÈTE, voir ci-dessous
  "timezone":          "Europe/Paris",     // IANA
  "url_client":        "https://connector.ma-boutique.com/shopimind",
  "ecommerce_version": "1.0.0",            // version de VOTRE plateforme
  "module_version":    "1.0.0",            // version de VOTRE connecteur

  // Facultatif
  "shop_id":           "1"                 // multiboutique, voir plus bas
}

Champ	Format	Notes
default_currency	ISO 4217	Devise d'affichage par défaut.
default_lang	ISO 639-1	Doit figurer dans langs.
langs	tableau ISO 639-1	Fait autorité, voir l'avertissement ci-dessous.
timezone	IANA (Europe/Paris)	Sert au calcul des heures d'envoi et à l'horodatage des paniers. Un identifiant non-IANA fera dériver toutes vos dates.
url_client	URL absolue	Racine des rappels entrants. Voir ci-dessous.
ecommerce_version	chaîne libre	Version de la plateforme boutique.
module_version	chaîne libre	Version de votre connecteur.
shop_id	chaîne	À ne renseigner que en multiboutique.

langs est destructif

Le tableau fait autorité : toute langue déjà enregistrée pour la boutique et absente de langs est supprimée, et default_lang réécrit le drapeau « langue par défaut ». Envoyez toujours la liste complète des langues actives, jamais un delta.

url_client : la racine des rappels

Ce champ n'est pas informatif. C'est la racine à partir de laquelle ShopiMind construit l'URL de chacun de ses appels entrants :

Action	URL construite
Générer des bons	POST {url_client}/vouchers
Créer un compte client	POST {url_client}/customers
Inscrire à la newsletter	POST {url_client}/subscribe-customer

Trois règles à respecter :

1. Pointez sur le service qui héberge votre connecteur, pas sur la vitrine. Si votre front est headless sur www.ma-boutique.com et votre connecteur sur une API séparée, url_client doit viser l'API.
2. Pas de redirection. ShopiMind suit les redirections same-site en conservant méthode et corps, mais refuse toute redirection cross-origin (le corps est signé, le rejouer ailleurs serait une faille) et toute redirection vers /. Servez l'URL exacte : attention au slash final, au http→https et au apex→www.
3. HTTPS obligatoire en production.

Vous n'êtes pas obligé d'implémenter toutes les routes. Exposez celles dont vous voulez les fonctionnalités, voir Rappels entrants.

Effets de bord

Deux conséquences de cet appel, à connaître avant de le câbler.

La clé utilisée devient la clé primaire

L'appel marque la clé qui l'a émis comme clé primaire de la boutique, et retire ce statut à toutes les autres. Or c'est le secret de la clé primaire qui sert à signer les rappels entrants (→ Signature).

Autrement dit : appelez /shop/connection uniquement avec la clé dédiée à votre connecteur. Si vous testez avec une autre clé, elle devient primaire, et la signature que votre connecteur vérifie ne correspondra plus à celle que ShopiMind émet, vos rappels renverront Unauthorized sans explication évidente.

Une reconnexion est idempotente… sauf pour langs

Rejouer l'appel avec la même configuration ne casse rien. Rejouer avec un langs amputé supprime des langues. Rejouer avec une autre clé change la clé de signature.

Multiboutique

Si votre plateforme héberge plusieurs boutiques sous une même installation, chacune est une boutique ShopiMind distincte, avec sa propre clé API et son propre identifiant.

Renseignez alors shop_id avec votre identifiant interne de boutique. ShopiMind le mémorise et le renvoie dans chaque rappel entrant sous la clé shopIdShop, ce qui vous permet de router l'appel vers la bonne boutique et d'y résoudre les bons identifiants.

{
  "shop_id": "3",
  "default_currency": "EUR"
  // …
}

Côté connecteur, résolvez donc vos identifiants par boutique : lisez shopIdShop dans le corps de chaque rappel et utilisez les identifiants de la boutique correspondante, avec repli sur votre configuration globale quand le champ est absent.

Quand rejouer la connexion

Événement	Rejouer ?
Installation du connecteur	Oui
Ajout / retrait d'une langue, changement de devise ou de fuseau	Oui
Changement de l'URL du connecteur	Oui : sinon les rappels partent dans le vide
Mise à jour de votre connecteur	Oui, met à jour module_version / current-build
Rotation de la clé API	Oui, avec la nouvelle clé : sinon la signature des rappels reste sur l'ancienne
Chaque démarrage du processus	Non, c'est un appel de configuration, pas un ping

Étape suivante

→ Pousser les données