Données personnalisées

Les données personnalisées ShopiMind permettent de modéliser des objets métier propres à votre activité — prix négociés, responsables commerciaux attitrés, contrats spécifiques, suivi métier — et de les rendre immédiatement exploitables dans la plateforme : segmentation, filtres, déclencheurs de scénarios, contenu dynamique des messages.

Le modèle en deux niveaux

L'API distingue clairement le schéma (ce que vous modélisez) et les records (les valeurs).

Custom data definitions — les schémas

Une définition déclare la structure d'un objet custom :

• Un name (label affiché dans le dashboard ShopiMind).
• Une liste de fields typés (string, number, date, boolean, list).
• Une éventuelle clé d'unicité (unique_keys) — utilisée par saveCustomDataRecords pour résoudre l'upsert.
• D'éventuelles relationships reliant un champ source à une autre ressource (un schéma système comme contacts ou products, ou une autre définition custom).

→ Référence : createCustomDataDefinition

Custom data records — les valeurs

Une fois la définition créée, vous y poussez des records : des lignes de données qui suivent le schéma déclaré. L'endpoint accepte des batches (jusqu'à 50 par appel) et fait l'upsert sur la clé d'unicité quand elle est définie.

→ Référence : saveCustomDataRecords

Les relations

Un champ d'une définition peut être déclaré comme une relation vers une autre ressource. Trois cibles supportées :

• contacts (schéma système) — pour rattacher un record à un contact ShopiMind.
• products (schéma système) — pour rattacher un record à un produit du catalogue.
• une autre custom data definition — pour modéliser des objets composites (ex. un programme de fidélité référence un commercial).

Une définition peut combiner plusieurs relations — par exemple « visite vétérinaire » référence à la fois un contact (le maître) et un produit (le service consommé).

Référencer un contact dans un record

Customers vs contacts

Avant d'aller plus loin, gardez en tête la distinction entre customers (poussés par votre intégration) et contacts (profils unifiés générés par ShopiMind). Les records custom se rattachent aux contacts, pas aux customers — voir Customers et contacts.

Pour un champ déclaré en relation avec le schéma système contacts, l'API accepte trois identifiants pour désigner le contact cible — sans pré-résolution côté votre code.

Trois identifiants supportés

by	Description	Type
id_contact	L'identifiant ShopiMind du contact (mode historique).	number
email	L'email du contact.	string
id_customer	Votre ID client côté boutique (id_customer_shop).	string

Quel que soit l'identifiant que vous envoyez, la base de données stocke toujours l'id_contact canonique. La résolution est transparente.

Deux formats acceptés

Format direct (rétrocompatible) — vous envoyez l'id_contact ShopiMind tel quel :

{
  "contact_id": 12345,
  "points": 450,
  "tier": "gold"
}

Format objet { by, value } — vous envoyez l'identifiant qui vous arrange, le serveur résout :

{
  "contact_id": { "by": "email", "value": "marie.dupont@example.com" },
  "points": 450,
  "tier": "gold"
}

Vous pouvez mélanger les deux formats dans un même batch : un record avec un id_contact direct, le suivant avec un email, le troisième avec un id_customer. Chaque type est résolu en une requête SQL groupée.

Quand utiliser quel identifiant

Vous avez…	Identifiant recommandé
Un export depuis votre BDD avec votre ID	id_customer
Un trigger basé sur l'inscription email	email
Un workflow ShopiMind qui vous a donné l'ID	id_contact
Un import CSV mixte	Mélange dans le batch

Erreurs courantes

• Contact introuvable — si l'email ou l'id_customer envoyé ne correspond à aucun contact, l'item est rejeté avec une erreur 400 indiquant la position dans le batch et le détail (la résolution est stricte, elle ne crée pas le contact à la volée).
• Identifiant non supporté — by n'accepte que id_contact, email, id_customer pour les relations vers contacts.
• Doublons d'email — cas atypique : si plusieurs contacts du shop partagent le même email, la résolution renvoie l'un d'eux sans ordre garanti. Préférez id_customer ou id_contact quand vous avez besoin d'une garantie 1-1 stricte.

Override de champs natifs (prix produits)

Une définition peut surcharger un champ système. Aujourd'hui, c'est principalement utilisé pour le prix : un même produit peut afficher un prix différent selon le contact connecté — tarification B2B, prix négocié, prix par tier de fidélité.

Trois sources priorisées maximum par champ surchargé. La règle de résolution est déterministe : priority: 1 (la plus haute) gagne en cas d'ambiguïté.

→ Cas d'usage concret : Tarification vétérinaire.

Exploitation côté ShopiMind

Une fois ingérés, les records (et leurs relations) sont disponibles dans :

• Segmentation : créer un segment « contacts dont loyalty.tier = gold ».
• Filtres de scénarios : « si le contact a fait au moins une visite véto cette année ».
• Contenu dynamique : injecter {var=loyalty.points_balance} dans un email.
• Déclencheurs : déclencher un scénario quand un record est créé ou mis à jour.

Workflow type

1. Modéliser la définition côté votre back-office (lister les champs, identifier les relations, définir la clé d'unicité).
2. Créer la définition via l'API (createCustomDataDefinition).
3. Récupérer l'id_definition retourné.
4. Pousser les records associés via saveCustomDataRecords en référençant cet id_definition.
5. Exploiter les données depuis le dashboard ShopiMind (segmentation, scénarios, contenu).

Limites à connaître

• Définitions shop-scoped — chaque définition est rattachée à une boutique, pas de partage entre boutiques d'un même compte.
• Override — aujourd'hui limité à products.price et products.price_discount, trois sources priorisées maximum par champ.
• Définition inactive = lecture seule — une définition inactive rejette toute écriture (saveCustomDataRecords, updateCustomDataRecord, deleteCustomDataRecord). Les records existants restent lisibles.
• Batch maximum — 50 records par appel pour saveCustomDataRecords, 20 pour bulkDeleteCustomDataRecords.

Pour aller plus loin

• Cas d'usage avec données personnalisées — tarification vétérinaire, responsable commercial dédié.
• Référence API : Custom data definitions et Custom data records.