Événements externes

L'API ShopiMind permet de déclencher des scénarios d'automatisation marketing depuis n'importe quel système tiers — POS, ERP, plateforme de sondage, transporteur, scheduler maison — via des événements personnalisés. C'est la voie privilégiée pour relier un événement métier à un parcours marketing ShopiMind sans coupler les systèmes.

Le modèle en trois étapes

1. Déclarer un type d'événement via createEvent. Vous définissez son code_name (utilisé dans l'URL de déclenchement), sa structure de payload (metaData, customData) et la cible attendue (un contact ou un visiteur).
2. Configurer dans le dashboard ShopiMind un scénario d'automatisation dont le déclencheur est ce type d'événement personnalisé précédemment créé. À l'enregistrement du scénario, ShopiMind câble automatiquement l'événement au scénario — aucun appel API supplémentaire n'est nécessaire côté tiers.
3. Émettre une instance via triggerEvent avec le code_name et un payload conforme au schéma défini à l'étape 1. Tous les scénarios actifs abonnés à ce code_name sont déclenchés.

L'émission est asynchrone : triggerEvent retourne dès que l'événement est mis en queue. L'exécution des scénarios suit, en quasi temps réel.

Étapes 1 et 2 indépendantes

Vous pouvez déclarer le type d'événement via l'API avant que le scénario n'existe côté dashboard, ou inversement. La connexion se fait par le code_name : tant que celui-ci correspond, l'événement déclenche les scénarios abonnés.

Anatomie d'un type d'événement

Un type d'événement déclare un schéma (properties) qui sera validé à chaque déclenchement. Quatre emplacements de payload sont supportés :

Emplacement	Contexte
metaData	Métadonnées libres décrivant le contexte de l'événement.
customData	Données personnalisées libres rattachées à l'instance.
contact.customData	Données personnalisées rattachées au contact résolu.
visitor.customData	Données personnalisées rattachées au visiteur résolu.

Chaque champ du schéma précise :

Clé	Rôle
name	Clé attendue dans le payload.
type	bool, text, longtext, number, decimal, date ou json.
required	Booléen — si true, l'absence du champ rejette l'appel à triggerEvent.
description	Optionnel — libellé descriptif (utile en segmentation côté dashboard).

Format du code_name

Le code_name est le slug utilisé dans l'URL de déclenchement (/events/trigger/:code_name). Il doit suivre l'un de ces formats :

• un mot alphanumérique unique : store_purchase, nps_received, delivered ;
• une notation Resource.Action ou Resource_Action : Order.Created, Subscription_Renewed.

Les espaces et caractères spéciaux sont refusés. Modifier code_name via updateEvent rote immédiatement l'URL de déclenchement : basculez les émetteurs vers la nouvelle valeur avant la modification pour éviter une coupure côté tiers.

Cible : contact ou visiteur

Le payload de triggerEvent doit contenir au moins un des deux objets :

• contact — résolu par l'un des identifiants id, email, ou phone. Au moins l'un des trois est requis.
• visitor — résolu par son id (requis).

Si la cible n'est pas trouvée, l'événement est tout de même journalisé dans l'historique mais aucun scénario n'est déclenché.

Exemple — déclarer un type d'événement

curl -X POST https://api.shopimind.com/v1/events \
  -H "spm-api-key: votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Achat en boutique physique",
    "code_name": "store_purchase",
    "properties": {
      "metaData": [
        { "name": "order_id",     "type": "number",  "required": true },
        { "name": "total_amount", "type": "decimal", "required": true },
        { "name": "store_code",   "type": "text",    "required": false }
      ]
    }
  }'

Exemple — émettre un événement

curl -X POST https://api.shopimind.com/v1/events/trigger/store_purchase \
  -H "spm-api-key: votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "email": "marie.dupont@example.com" },
    "metaData": {
      "order_id": 12345,
      "total_amount": 89.50,
      "store_code": "PAR-13"
    }
  }'

Validation au déclenchement

triggerEvent valide chaque payload contre le schéma déclaré. L'appel est rejeté en 400 si :

• un champ marqué required: true est absent ;
• un champ a un type incompatible avec celui déclaré ;
• un champ non déclaré au schéma est présent (validation stricte).

Les erreurs sont accumulées et retournées en un seul lot :

{
  "statusCode": 400,
  "success": false,
  "errors": [
    "Missing required property: metaData.total_amount",
    "Invalid type for property: metaData.order_id. Expected number, got string"
  ]
}

Historique des déclenchements

Chaque émission est journalisée et consultable via listEventHistories. Chaque ligne contient le code_name, la cible, le payload sérialisé et le statut d'exécution. À utiliser en priorité pour diagnostiquer un scénario qui ne se déclenche pas comme attendu.

Cas d'usage typiques

• Caisse / POS — émettre un événement « achat en boutique physique » pour unifier les workflows post-achat web et retail (relance, fidélité, satisfaction).
• Programme de fidélité — émettre des événements loyalty.points_earned, loyalty.tier_upgraded ou loyalty.points_expiring depuis votre moteur de fidélité pour déclencher des scénarios temps réel (remerciement, palier débloqué, rappel d'expiration). Détail : Programme de fidélité par paliers.
• Webhook transporteur — émettre un événement « commande livrée » pour déclencher une demande d'avis 2 à 4 jours après la réception réelle (vs. l'expédition).
• ERP — émettre un événement « contrat renouvelé » ou « impayé détecté » pour brancher le suivi marketing sur les événements de gestion.

Voir aussi les cas d'usage détaillés combinant événements externes et données personnalisées.

Bientôt — webhooks d'actions sortants

L'API expose aujourd'hui uniquement le sens entrant : votre système tiers déclenche un événement, ShopiMind exécute les scénarios abonnés.

Les webhooks d'actions sortants — où ShopiMind notifie un système externe (CRM, ERP, data warehouse) via un POST signé sur une URL que vous fournissez lorsqu'une action de scénario se déclenche — sont en cours de finalisation et seront disponibles prochainement.

Limites et points d'attention

• Validation stricte — tout champ non déclaré dans le schéma properties est rejeté. Pensez à mettre à jour le type d'événement (updateEvent) avant d'envoyer un nouveau champ.
• Async par construction — triggerEvent retourne avant l'exécution du scénario. Pour un déclenchement fiable, monitorez listEventHistories plutôt que la réponse HTTP de l'appel.
• code_name casse l'URL — renommer un code_name change immédiatement le chemin de triggerEvent. Les scénarios en cours ne sont pas impactés, mais les émetteurs tiers doivent être mis à jour.
• Suppression définitive — deleteEvent est irréversible et arrête les scénarios abonnés. Pour une pause réversible, retirez l'abonnement côté scénario depuis le dashboard.

Référence API

createEvent · updateEvent · listEvents · getEvent · deleteEvent · triggerEvent · listEventHistories.