API développeur, MCP, GitHub et simulation de déclenchement
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 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 s'y prendre :
- 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 passé.
La simulation est volontairement fidèle à la réalité. Elle ne crée pas de charge utile simplifiée : elle suit exactement le même processus qu’un webhook réel d’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 affiche la charge utile, 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 (polling) 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éveloppeur » et choisissez son niveau d'accès :
- Accès en lecture seule : afficher la liste des déclencheurs et leur état, consulter l'historique des événements, les statistiques et les autorisations.
- Lecture et écriture - ainsi que l'activation et la désactivation des déclencheurs.
- Lire, écrire et exécuter - simuler également 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_hereLa simulation se situe à un niveau supérieur pour la raison évoquée ci-dessus : elle exécute vos automatisations en conditions réelles ; par conséquent, une clé utilisée pour les lectures quotidiennes ne peut pas les déclencher.
API REST
| Méthode | Chemin | Niveau | Objectif |
|---|---|---|---|
| OBTENIR | /api/v1 |
aucun | Index API - indique que l'API est opérationnelle |
| OBTENIR | /api/v1/me |
lire | Vérifiez l'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 une gâchette |
| 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 sa charge utile |
| 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 pratique 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 où le gérer dans l'application.
Activer et désactiver les 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 fait défiler la page directement jusqu'à 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 contenant le code de votre Déclencheurs personnalisés. Les modifications deviennent alors soumises à révision sous forme de pull request ; vous pouvez voir qui a modifié quoi et annuler une transformation qui ne fonctionne plus.
En cliquant sur « Connecter », vous installez notre application GitHub sur le compte de votre choix. C’est vous qui 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, l’application est d’emblée configurée pour ce dépôt, 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 tel qu'il apparaît dans l'éditeur - sans aucun élément supplémentaire autour. 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 Trigger 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éintégrez, sous la forme d'un nouveau commit.
Modification ou déconnexion
L'option « Changer de dépôt » vous ramène au sélecteur sans modifier l'installation. L'option « Déconnecter » annule l'installation sur GitHub et la supprime également ici ; son nom en dit 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 d'un 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'exemple 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 l'action se déclencherait, l'objet de sortie, vos lignes d'ctx.logs et la durée d'exécution.
Rien n'est déclenché 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é. Ce workflow peut être exécuté en toute sécurité à chaque enregistrement déclenché par 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 n'a aucun 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 sa charge utile |
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 événement à 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 personnelles contenues dans un champ de texte libre peuvent tout de même être divulguées. Les messages d'erreur sont également dépouillés de leurs 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 l'indemnité.
- Présentation d'Workflow Trigger Extensions - comment fonctionnent les déclencheurs et comment les activer.
Limites de débit
L'API REST et le serveur MCP partagent un même budget par clé API.
- 300 requêtes par 60 secondes 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 consomment les deux budgets ; ainsi, une rafale d'appels « Execute » entame également le quota partagé. Pour cette application, cela implique de simuler un déclencheur et d'exécuter du code de déclenchement personnalisé, deux opérations qui déclenchent réellement vos workflows.
- C'est la même chose pour toutes les formules. Ce sont les compteurs de votre formule qui déclenchent des événements, et non des appels API ; la mise à niveau n'entraîne donc pas d'augmentation de ces chiffres.
- Si la requête renvoie un code HTTP 429, attendez un certain temps puis réessayez, de préférence en utilisant une stratégie de retard exponentiel.
- Si notre cache est temporairement indisponible, le limiteur se désactive plutôt que de bloquer votre intégration.
Les webhooks entrants d'Shopifys ne sont pas soumis à une limitation de débit
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 faut 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 flux de travail) peuvent faire du côté de Shopify, et vous pourriez les atteindre si vous gérez une boutique de grande envergure, même si vous restez largement en deçà de nos limites.
- Le nombre d'éléments des tableaux d'entrée est limité à 250 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 méthode
Shopifyrenvoie25001, ce qui signifie « plus de 25 000 ». Si vous avez besoin d'aller plus loin, appliquez d'abord un filtre. - L'API d'Shopify de 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' choisi par la boutique :
| Shopify plan | Points par seconde |
|---|---|
| Standard | 100 |
| Avancé | 200 |
| Et en plus | 1 000 |
| Entreprise (composants commerciaux) | 2000 |
L'API Storefront n'est pas soumise à une limitation de débit.
Tous les détails : Limites de requêtes de l'API «Shopify »