Chaque requête API doit inclure votre clé API dans l’en-tête api-key. Si la clé est absente ou n’appartient pas au programme indiqué dans l’URL, l’API répond 403.

Chaque clé appartient à un seul programme. Vous pouvez créer plusieurs clés, par exemple une par système connecté à JeriCommerce, donner à chacune uniquement l’accès dont elle a besoin et en supprimer une sans affecter les autres.

Obtenir une clé API

Pour créer une clé, ouvrez Settings > Technical > API keys, puis cliquez sur Add API key. Une page s’ouvre avec ces réglages.

Page Add API key avec Name, Expiration, Restrict key, Permissions, Restrict by IP et Status
La page Add API key, avec Restrict key coché
1

Nommer la clé

Saisissez un nom dans Name, par exemple le système qui l’utilisera.

2

Choisir quand elle expire

Dans Expiration, choisissez 15 minutes, 1 hour, 1 day, 7 days, 30 days ou Never. Les nouvelles clés démarrent sur Never. Le délai court à partir de l’enregistrement.

3

Choisir à quoi elle peut accéder

Restrict key est coché sur les nouvelles clés. Sous Permissions, cochez au moins une option. Le tableau plus bas indique ce que chacune permet.

4

Limiter les adresses IP, si vous le souhaitez

Cochez Restrict by IP pour accepter uniquement les requêtes de certaines adresses. Saisissez-en une dans IP address or CIDR range, par exemple 203.0.113.7 ou 203.0.113.0/24, puis cliquez sur Add. Vous pouvez ajouter jusqu’à 100 entrées, IPv4 ou IPv6.

5

Enregistrer et copier la clé

Cliquez sur Save. La fenêtre API key created affiche la clé. Copiez-la et conservez-la en lieu sûr, car vous ne pourrez plus la voir.

Si vous décochez Restrict key, la clé peut appeler toute l’API et une fuite devient bien plus risquée. Laissez cette option cochée, sauf si un système a vraiment besoin d’un accès complet.

Inclure le jeton dans les requêtes API

Pour accéder aux endpoints de l’API, indiquez comme valeur de l’en-tête api-key la clé API obtenue à l’étape précédente.

Voici un exemple avec cURL qui lit un client :

curl --request GET \
  --url https://api.jericommerce.com/v1/programs/{program_slug}/customers/customer@example.com \
  --header 'api-key: {{ apiKey }}'

Gardez la clé sur votre serveur. Toute personne qui la possède peut modifier les données de vos clients : ne la placez donc jamais dans un site web, une application ou tout code exécuté sur l’appareil du client.

Les endpoints Aperçu du solde et Lister les récompenses sont publics et fonctionnent sans clé.

Ce que permet chaque autorisation

Une clé restreinte ne peut faire que ce que vous cochez sous Permissions. Les webhooks Klaviyo sont aussi des appels API : leur clé a donc besoin de l’autorisation correspondant à l’action.

Autorisation Ce que la clé peut faire
Customers Lire les données du client
Customer tokens Obtenir un lien de téléchargement et les jetons client
Balance Augmenter et réduire le solde
Coupons and rewards Attribuer un coupon et échanger une récompense
Campaigns Envoyer une Gift Card et attribuer des campagnes
Push Envoyer une notification push
Earning flows Exécuter un flux d’acquisition personnalisé
Subscriptions Créer ou annuler l’abonnement du programme à JeriCommerce
API integration Synchroniser les clients et les données de fidélité via la Custom API Integration
VTAP Connecter un lecteur NFC VTAP
MCP Utiliser cette clé avec le MCP de JeriCommerce : No access, Read ou Write. Write inclut la lecture

Modifier une clé

Dans Settings > Technical > API keys, cliquez sur les trois points d’une clé et choisissez Edit API key. Vous pouvez tout modifier, sauf la valeur de la clé.

  • Expiration propose Don't change lorsque la clé a une date d’expiration, afin qu’enregistrer un autre réglage ne la déplace pas.
  • Status, dans la colonne latérale, arrête une clé lorsque vous choisissez Inactive. Repassez sur Active pour la réactiver.
  • Delete API key, dans le même menu, supprime la clé. Les applications qui l’utilisent cesseront de fonctionner.

La liste affiche un badge pour chaque clé : Active, Inactive ou Expired. Les clés créées avant ces réglages n’ont ni restriction ni expiration, et affichent Unrestricted jusqu’à ce que vous les restreigniez.

Erreurs de clé API

Ces erreurs figurent dans le champ message de la réponse.

Statut message Signification
401 API_KEY_INACTIVE La clé n’est pas active. Vérifiez son Status.
401 API_KEY_EXPIRED L’Expiration de la clé est dépassée.
403 API_KEY_IP_NOT_ALLOWED La requête provient d’une adresse hors de Restrict by IP.
403 API_KEY_PERMISSION_DENIED La clé n’a pas l’autorisation pour cette requête.