Ce point de terminaison exécute un parcours de gains personnalisé pour un client donné. Les points, les limites de récurrence et le plafond par client sont ceux que vous avez définis lors de la configuration du parcours dans le tableau de bord. L'API déclenche simplement son exécution.

Utilisez-le si vous souhaitez qu'un système externe à JeriCommerce, comme votre CRM, votre plateforme d'avis ou un outil de sondage, décide si le client a gagné les points.

Pour consulter la spécification complète lisible par machine et essayer le point de terminaison, reportez-vous à la documentation de l'API JeriCommerce : Execute Custom Earning Flow.

Point de terminaison 

// POST
https://api.jericommerce.com/v1/programs/{programId}/custom-earning-flows/{earningFlowId}/execute

Remplacez {programId} par l'identifiant réel de votre programme (disponible dans Settings → Technical → Program Information) et {earningFlowId} par l'une des valeurs suivantes :

  • L'identifiant d'emplacement du parcours : CUSTOM_1, CUSTOM_2, CUSTOM_3, CUSTOM_4 ou CUSTOM_5.
  • L'UUID de la ligne ProgramEngagementFlow concernée, si vous préférez utiliser des identifiants stables.

L'identifiant d'emplacement est le plus simple à utiliser, car il reste identique même si vous réinitialisez le parcours.

Authentification

Ce point de terminaison accepte deux méthodes d'authentification. Choisissez celle qui correspond à votre cas d'usage.

Utilisez la clé API de votre programme dans l'en-tête `api-key`. Consultez [Authentification via l'API](/integrations/api/1-authentication-through-the-api/).

Avec une clé API, vous pouvez exécuter le parcours pour **n'importe quel** client du programme. L'adresse e-mail du client doit figurer dans le corps de la requête.

Transmettez le JWT du client dans l'en-tête `Authorization`. Le parcours s'exécute pour le client authentifié et le corps de la requête reste vide.

Utilisez cette méthode lorsque le navigateur ou l'application du client appelle le point de terminaison, par exemple depuis une intégration personnalisée de votre boutique.

Corps de la requête 

{
  "customerEmail": "customer@example.com"
}
Champ Type Obligatoire Notes
customerEmail string Obligatoire avec l'authentification par clé API. Ignoré avec l'authentification par JWT client. Adresse e-mail du client auquel attribuer les points. Elle doit correspondre à un client déjà inscrit au programme.

Réponse

Une requête aboutie renvoie le code 200 avec un corps JSON :

{
  "pointsAwarded": 100,
  "remainingExecutions": 0,
  "recurrence": "lifetime"
}
Champ Type Notes
pointsAwarded number Nombre de points ajoutés au solde du client lors de cette exécution.
remainingExecutions number Nombre de fois où ce client peut encore exécuter le parcours pendant la période de récurrence actuelle. 0 signifie qu'il a atteint le plafond.
recurrence string Période de récurrence du parcours : once, daily, weekly, monthly, quarterly, semiannually ou yearly.

Erreurs

Si la requête ne peut pas aboutir, l'API renvoie un code d'erreur auquel votre intégration peut réagir.

Code Signification
CUSTOMER_EMAIL_REQUIRED L'authentification par clé API a été utilisée sans envoyer customerEmail dans le corps.
EARNING_FLOW_NOT_FOUND earningFlowId n'existe pas dans ce programme.
NOT_A_CUSTOM_EARNING_FLOW L'identifiant correspond à un parcours standard (par exemple INCENTIVIZE_PURCHASES), qui ne peut pas être déclenché de cette manière.
EARNING_FLOW_INACTIVE Le parcours existe, mais il est désactivé dans le tableau de bord.
EARNING_FLOW_NOT_CONFIGURED Il manque des propriétés obligatoires au parcours (points, récurrence ou nombre maximal d'exécutions). Ouvrez-le dans le tableau de bord et enregistrez-le.
CUSTOMER_NOT_FOUND Aucun client associé à cette adresse e-mail n'existe dans le programme.
MAX_EXECUTIONS_REACHED Le client a déjà exécuté le parcours le nombre maximal de fois autorisé pendant la période de récurrence actuelle.

Exemple

Vous configurez CUSTOM_2 pour attribuer 100 points, une seule fois à vie, lorsqu'un client répond à un sondage après un achat. Votre outil de sondage appelle le point de terminaison lorsque le client envoie sa réponse.

// Request

POST https://api.jericommerce.com/v1/programs/{{program_id}}/custom-earning-flows/CUSTOM_2/execute
api-key: {your_api_key}
Content-Type: application/json

{
  "customerEmail": "customer@example.com"
}

// Response

{
  "pointsAwarded": 100,
  "remainingExecutions": 0,
  "recurrence": "lifetime"
}

Le solde du client augmente de 100 points et la carte du parcours dans son application web indique « Vous avez déjà gagné cette récompense ».

Si vous déclenchez le parcours depuis Shopify Flow ou Klaviyo, vous n'avez pas besoin de créer vous-même la requête. Utilisez l'action Execute earning flow décrite dans Shopify Flows et événements, ou générez un webhook prêt à coller avec le générateur de webhooks Klaviyo.