Archétypes

Le kit @shopimind/integration-kit-js n'est pas spécialisé pour un type de produit : c'est une fondation générique. Toutes les intégrations s'appuient sur le même petit jeu de briques — données personnalisées, événements, widgets, synchronisation (avec sources dédiées) et middleware entrant. Voici comment quatre archétypes courants les combinent.

Archétype	Données perso.	Événements	Widgets	Sync + withSource	Middleware entrant
Fidélité	✅	✅	✅	—	✅
Avis	✅	✅	○	—	✅
Caisse (POS)	○	○	○	✅	○
CRM	✅	○	—	○	✅

✅ central · ○ optionnel selon le besoin · — rarement utilisé

Deux précisions qui structurent chaque archétype

• ctx.withSource (sources dédiées) est une primitive CATALOGUE — elle tague par source les écritures e-commerce bulkSave*. Centrale pour le POS, elle n'est pas utilisée par Fidélité/Avis/CRM, qui travaillent avec données personnalisées + événements + middleware entrant.
• Un contact ne s'écrit jamais directement (pas d'API d'écriture de contact). Un contact se matérialise par la synchro clients ; on l'enrichit ensuite via des enregistrements de données personnalisées reliés au contact (relation: { by: 'email' | 'id_contact', value }). Un profil fidélité, un score CRM ou un agrégat d'avis est donc un enregistrement de données personnalisées sur le contact — relisez-le avec SpmCustomDataRecords.list(ctx.spm, definitionId, query).

Fidélité

Un programme de fidélité enrichit le profil du contact et réagit aux gains de points.

• Données personnalisées — un profil de fidélité (solde de points, palier, date d'expiration) attaché au contact.
• Événements — points_earned, tier_reached… pour déclencher des scénarios marketing.
• Widgets — afficher le solde de points ou le palier dans les emails.
• Middleware entrant — quand un client gagne des points chez vous, votre app appelle une route inbound pour le refléter en temps réel (mise à jour du profil + triggerEvent).

Pas de catalogue natif à pousser : une intégration de fidélité ne déclare en général pas de source de données e-commerce.

Avis

Un service d'avis remonte la réputation produit/marchand dans ShopiMind.

• Données personnalisées — note moyenne, nombre d'avis, dernier avis, attachés au contact ou à un produit.
• Événements — review_created, review_replied… pour relancer ou remercier.
• Middleware entrant — pousser un nouvel avis dès sa publication.
• Widgets (optionnel) — un badge de note dans les emails.

Caisse (POS)

Une caisse pousse l'activité des points de vente physiques à côté de l'e-commerce. C'est l'archétype « catalogue », illustré par l'exemple Hiboutik.

• Synchronisation multi-source — clients, commandes (et éventuellement produits) de chaque magasin, en SyncStep per-source.
• withSource — chaque magasin est une source dédiée ; les entités sont taguées avec leur id_data_source et leurs identifiants namespacés, pour ne jamais écraser le catalogue natif du marchand.
• Données personnalisées / événements (optionnel) — profil d'achat en magasin, événement « passage en caisse ».

CRM

Un CRM synchronise des attributs de relation client et réagit aux changements.

• Données personnalisées — segments, score, étape du cycle de vie, propriétaire du compte.
• Synchronisation (optionnel) — import régulier des contacts et de leurs attributs.
• Événements / middleware entrant — pousser une mise à jour (changement de segment, nouvelle opportunité) en temps réel.

Composer librement

Ces archétypes ne sont pas des cases fermées : une même intégration peut combiner plusieurs briques (un POS qui ajoute un programme de fidélité, un CRM qui pousse des avis…). Le kit vous laisse n'activer que ce dont vous avez besoin — chaque brique est indépendante.

Pour aller plus loin

• Le kit d'intégration — le contrat complet.
• Données personnalisées · Événements · Widgets
• Synchroniser les données · Middleware entrant
• Exemple : Hiboutik POS — l'archétype caisse, de bout en bout.