API développeur, MCP, GitHub et simulation de déclencheur

Vous pouvez consulter vos déclencheurs, les activer ou les désactiver, consulter l'historique des événements et simuler un déclencheur à partir de votre propre code ou d'un assistant IA. Workflow Trigger Extensions met à disposition une API REST et un serveur MCP, et peut se connecter à un dépôt GitHub afin que votre code de déclencheur personnalisé soit soumis au contrôle de version. Ces trois éléments sont gérés depuis la page « Développeur ».

Simulation d'un déclencheur

Tester un workflow Shopify Flow implique généralement de reproduire une situation réelle dans votre boutique : modifier un produit, passer une commande, attendre le résultat d'un sondage. La simulation vous évite cette attente : choisissez un déclencheur, associez-le à une ressource, et il se déclenche comme si l'événement réel venait de se produire.

Deux façons de le faire :

• Dans l'application, ouvrez n'importe quel événement dans l'historique des événements, puis sélectionnez à nouveau « Simuler ». Cela déclenche à nouveau cet événement précis.
• Via l'API ou le MCP, à l'aide d'un identifiant de ressource ou d'un événement antérieur.

La simulation est volontairement fidèle à la réalité. Elle ne crée pas de payload simplifié : elle suit exactement le même parcours qu'un webhook réel de Shopify. Ainsi, ce que reçoit votre workflow correspond exactement à ce qu'il recevrait en production.

curl -X POST https://shopify.workflow-trigger-extensions.app/api/v1/triggers/product-update-trigger/simulate \
  -H "Authorization: Bearer ftk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"resourceId":"gid://shopify/Product/123456789","dryRun":true}'

Un test de simulation valide le déclencheur, résout le sujet et vous affiche la Payload, sans déclencher aucune action. Supprimez dryRun pour le déclencher réellement. Vous pouvez également passer {"fromHistoryId":"456"} pour redéclencher un événement passé au lieu d'en créer un nouveau.

Les déclencheurs fonctionnant par interrogation plutôt que par webhook ne peuvent pas être simulés ; ils affichent le message simulatable: false dans la liste des déclencheurs.

Clés API

Créez une clé sur la page « Développeurs » et sélectionnez son niveau d'accès :

• Accès en lecture seule : liste des déclencheurs et de leur état, consultation de l'historique des événements, des statistiques et des autorisations.
• Lecture et écriture - ainsi que l'activation et la désactivation des déclencheurs.
• Lire, écrire et exécuter - vous pouvez également simuler des déclencheurs et tester du code de déclencheur personnalisé.

La clé complète s'affiche une seule fois, lors de sa création. Les clés sont stockées sous forme hachée et peuvent être révoquées à tout moment. Envoyez-la sous forme de jeton « Bearer » :

Authorization: Bearer ftk_your_key_here

La simulation se situe à un niveau supérieur pour la raison évoquée ci-dessus : elle exécute réellement vos automatisations ; par conséquent, une clé utilisée pour les lectures quotidiennes ne peut pas les déclencher.

API REST

Méthode	Chemin d'accès	Niveau	Objectif
OBTENIR	/api/v1	aucun	Index API - confirme que l'API est opérationnelle
OBTENIR	/api/v1/me	lire	Vérifiez votre authentification et consultez le niveau de votre clé
OBTENIR	/api/v1/triggers	lire	Chaque déclencheur, avec son état pour votre boutique
OBTENIR	/api/v1/triggers/:handle	lire	Un déclencheur en détail
PUT	/api/v1/triggers/:handle	écrire	Activer ou désactiver un déclencheur
PUT	/api/v1/triggers	écrire	Activer ou désactiver plusieurs éléments en une seule opération
PUBLICATION	/api/v1/triggers/:handle/simulate	exécuter	Simuler un déclencheur
OBTENIR	/api/v1/triggers/custom	lire	Vos propres déclencheurs personnalisés, avec leur code
OBTENIR	/api/v1/triggers/custom/:handle/test	lire	L'événement d'échantillon capturé pour un déclencheur personnalisé
PUBLICATION	/api/v1/triggers/custom/:handle/test	exécuter	Exécuter un code de déclencheur personnalisé sans enregistrer ni déclencher
OBTENIR	/api/v1/history	lire	Liste des événements déclencheurs
OBTENIR	/api/v1/history/:id	lire	Récupérer un événement, avec son payload
OBTENIR	/api/v1/stats	lire	Totaux, taux de réussite, répartition par statut
OBTENIR	/api/v1/permissions	lire	Quelles autorisations d'accès aux données vous avez accordées, et ce que chacune d'entre elles permet d'accéder

GET /api/v1/triggers C'est l'outil le plus utile pour la configuration : pour chaque déclencheur, il vous indique l'autorisation requise, si cette autorisation est accordée, si le déclencheur est activé et à quel endroit de l'application vous pouvez le gérer.

Activation et désactivation des déclencheurs

PUT On utilise cette méthode plutôt que PATCH car l'appel est idempotent : le relancer après un délai d'expiration ne peut entraîner aucune application double, ce qui est important lorsqu'un assistant pilote l'API.

curl -X PUT https://shopify.workflow-trigger-extensions.app/api/v1/triggers/order-tags-added-trigger \
  -H "Authorization: Bearer ftk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

La fonction « Enabling » n'accorde jamais d'autorisation. Si le déclencheur a besoin d'une autorisation que vous n'avez pas accordée, l'appel aboutit tout de même et vous indique précisément ce qui manque et où l'accorder :

{
  "enabled": true,
  "scopeGranted": false,
  "missingScopeLabels": ["Order Data Access"],
  "permissionsUrl": "https://admin.shopify.com/store/.../app/permissions?permission=read_orders",
  "warning": "Enabled, but this trigger cannot fire until Order Data Access is granted."
}

Ce lien ouvre la page « Autorisations » et vous amène directement à la fiche qui vous intéresse.

Ajoutez "sync": true pour lancer également une synchronisation des données, afin que le déclencheur s'applique aux enregistrements existants et non pas uniquement à ceux créés à partir de maintenant.

Pour en modifier plusieurs à la fois, la commande PUT /api/v1/triggers accepte une liste explicite ou une catégorie entière :

{ "enabled": true, "handles": ["order-tags-added-trigger", "order-note-changed-trigger"] }
{ "enabled": true, "category": "orders" }

Se connecter à GitHub

Sur la page « Développeur », l'onglet « Connexions » vous permet de connecter un dépôt GitHub pour votre code d'Déclencheurs personnalisés. Les modifications deviennent alors soumises à révision dans une pull request ; vous pouvez voir qui a modifié quoi et vous pouvez annuler une transformation qui ne fonctionne plus.

L'option « Connecter » installe notre application GitHub sur le compte de votre choix. Vous choisissez les dépôts auxquels elle a accès, et vous pouvez révoquer cet accès depuis GitHub à tout moment. Lorsque vous sélectionnez un dépôt, tous les déclencheurs personnalisés dont vous disposez déjà y sont immédiatement enregistrés ; ainsi, le dépôt est d'emblée synchronisé avec l'application, plutôt que de se remplir progressivement au fil du temps.

Ce que vous faites	Que se passe-t-il ?
Créer, modifier ou dupliquer un déclencheur dans l'application	Le fichier a été validé dans votre dépôt
Supprimer un déclencheur dans l'application	Le fichier est supprimé de votre référentiel
Appliquer une modification à la branche connectée	Le code du déclencheur est mis à jour dans l'application

Chaque déclencheur correspond à un fichier portant le nom de son identifiant, qui contient exactement le module que vous voyez dans l'éditeur - sans aucun élément supplémentaire. Vous pouvez donc l'ouvrir dans votre propre éditeur, l'exécuter et le valider comme n'importe quel autre fichier JavaScript, puis utiliser le point de terminaison /test ci-dessus pour le tester sur un événement réel capturé avant de valider vos modifications.

Revenir à une version antérieure

Il n'est pas nécessaire de connaître Git pour annuler une modification. Une fois le dépôt connecté, l'éditeur « Déclencheur » affiche un menu déroulant « Version » répertoriant toutes les versions précédentes de ce fichier, avec leur date et leur auteur. Choisissez-en une : elle s'affiche alors dans l'éditeur en tant que modification non enregistrée, ce qui vous permet de la consulter au préalable. C'est en enregistrant que vous la réintroduisez, sous la forme d'un nouveau commit.

Modification ou déconnexion

L'option « Changer de dépôt » vous ramène à la liste de sélection sans modifier l'installation. L'option « Déconnecter » annule l'installation sur GitHub et la supprime également ici ; son nom en dit donc long. L'option « Gérer les autorisations » ouvre les paramètres d'installation sur GitHub, où vous pouvez ajouter ou supprimer des dépôts.

Test du code de déclencheur personnalisé

Si vous conservez votre code de déclencheur personnalisé dans un référentiel et que vous le modifiez dans votre propre éditeur, vous pouvez l'exécuter sur l'événement d'échantillon capturé sans avoir à l'enregistrer au préalable dans l'application.

curl -X POST https://shopify.workflow-trigger-extensions.app/api/v1/triggers/custom/my-trigger/test \
  -H "Authorization: Bearer ftk_your_key_here" \
  -H "Content-Type: application/json" \
  -d "$(jq -Rn --rawfile c flow-triggers/my-trigger.js '{code:$c}')"

Vous obtenez les informations affichées par le bouton « Test » de l'application : si la fonction se déclencherait, l'objet de sortie, vos lignes d'ctx.logs et la durée d'exécution.

Aucune opération n'est déclenchée et rien n'est enregistré : aucun workflow n'est exécuté, aucun événement n'est enregistré, aucune allocation n'est utilisée et le code stocké reste inchangé. Vous pouvez l'exécuter en toute sécurité à chaque enregistrement à partir d'un observateur de fichier. Consultez Déclencheurs personnalisés pour découvrir le workflow complet.

Serveur MCP

L'onglet « MCP » de la page « Développeur » affiche l'URL du serveur ainsi qu'une commande de connexion prête à être copiée pour Claude, Cursor, VS Code, Gemini CLI et d'autres outils. Les outils reflètent les points de terminaison REST, et l'ensemble des outils disponibles dépend du niveau de votre clé : une clé en lecture seule ne donne absolument pas accès aux outils d'écriture ou d'exécution.

Outil	Niveau	Fonctionnalités
list_triggers	lire	Chaque déclencheur et son état
list_custom_triggers	lire	Vos propres déclencheurs personnalisés, avec leur code
get_custom_trigger_sample	lire	L'événement capturé par rapport auquel un déclencheur personnalisé effectue une vérification
list_history	lire	Événements déclencheurs récents
get_event	lire	Un événement, y compris son payload
get_stats	lire	Statistiques agrégées
get_permissions	lire	Les autorisations accordées et ce qu’elles permettent d’accéder
get_trigger	écrire	Un déclencheur en détail
set_trigger	écrire	Activer ou désactiver un déclencheur
set_triggers_bulk	écrire	Allumer ou éteindre plusieurs appareils à la fois
simulate_trigger	exécuter	Déclencher un déclencheur à la demande
test_custom_trigger	exécuter	Exécuter un code de déclencheur personnalisé sans enregistrer ni déclencher

C'est ce qui rend un assistant véritablement utile : il peut répertorier ce qui existe, expliquer ce dont un déclencheur a besoin, l'activer, lancer un événement de test, vous communiquer le résultat - et, pour les déclencheurs personnalisés, réécrire le code et le tester - sans que vous ayez à quitter la conversation.

Comment vos données sont-elles protégées ?

Les données de l'événement sont renvoyées avec les données personnelles masquées : les adresses e-mail, les numéros de téléphone, les numéros de carte bancaire et les champs contenant des noms de personnes sont remplacés par ***. Les identifiants de ressource Shopify et les champs relatifs à l'entreprise sont conservés tels quels afin que les données restent exploitables.

Le masquage s'applique aux noms de champs et aux modèles de valeurs ; il s'agit donc d'une mesure de précaution, mais pas d'une garantie : les données à caractère personnel contenues dans un champ de texte libre peuvent tout de même être divulguées. Les messages d'erreur sont également dépourvus de détails de diagnostic internes avant de quitter le serveur.

La connexion GitHub ne stocke aucune information d'identification susceptible d'être divulguée : seul l'identifiant d'installation est conservé, et l'accès au dépôt s'effectue à l'aide d'un jeton généré à la demande dont la durée de validité est limitée à une heure.

Prochaines étapes

• Déclencheurs personnalisés - Créez votre propre déclencheur en quelques lignes de JavaScript.
• Forfaits et utilisation - ce qui est considéré comme un événement et comment fonctionne cette indemnité.
• Présentation d'Workflow Trigger Extensions - le fonctionnement des déclencheurs et la manière de les activer.

Limites de débit

L'API REST et le serveur MCP partagent un budget commun par clé API.

• 300 requêtes par 60 secondes et par clé, dans une fenêtre fixe.
• Les appels au niveau « Execute » disposent d’un deuxième budget, plus restreint, de 60 par heure. Ces appels utilisent les deux budgets ; ainsi, une série d’exécutions vient également entamer le quota partagé. Pour cette application, cela signifie simuler un déclencheur et exécuter du code de déclencheur personnalisé, deux opérations qui activent réellement vos workflows.
• C'est identique pour tous les forfaits. Ce sont les compteurs de votre forfait qui sont les déclencheurs d'événements, et non les appels API ; par conséquent, le passage à un forfait supérieur n'entraîne pas d'augmentation de ces chiffres.
• Si la réponse est un code HTTP 429, veuillez patienter puis réessayer, de préférence en utilisant une stratégie de temporisation exponentielle.
• Si notre cache est temporairement indisponible, le limiteur se désactive plutôt que de bloquer votre intégration.

The inbound Shopify webhooks are not limited by data rate

Nous n'appliquons aucune limitation aux Webhooks que nous envoie Shopify : ils sont acceptés dès leur réception et placés en file d'attente. La limite maximale correspond au quota d'événements sur 30 jours prévu par votre forfait.

Il y a une chose qu’il est bon de savoir si vous écrivez des déclencheurs personnalisés : votre code s’exécute à chaque événement du sujet qu’il surveille, et chaque exécution compte pour un événement, y compris celles que vous filtrez en renvoyant null. Le coût est le même que celui d’un déclencheur intégré pour le même événement.

Shopify

Il s'agit des limites imposées par Shopify concernant les API d'Shopify, et non des nôtres. Elles s'appliquent à ce que cette application (et vos workflows) peuvent faire du côté d'Shopify, et vous pourriez les atteindre si votre boutique est très importante, même si vous restez largement en deçà de nos limites.

• La taille des tableaux d'entrée est limitée à 250 éléments pour toutes les API d'Shopify. Toute requête comportant un tableau plus grand est rejetée.
• La pagination s'arrête à 25 000 objets. Les comptages sont exacts jusqu'à 25 000 ; au-delà, la commande Shopify renvoie 25001, ce qui signifie « plus de 25 000 ». Si vous souhaitez aller plus loin, appliquez d'abord un filtre.
• L'API d'Shopify GraphQL est facturée en fonction du coût calculé des requêtes, exprimé en points par seconde, et le plafond dépend du forfait d' de la boutique :

Shopify forfait	Points par seconde
Standard	100
Avancé	200
De plus	1 000
Entreprise (composants commerciaux)	2000

L'API de la boutique en ligne n'est pas soumise à une limitation de débit.

Tous les détails : Shopify Limites de débit de l'API