API para desarrolladores, MCP, GitHub y simulación de activadores

Puede revisar sus activadores, activarlos o desactivarlos, consultar el historial de eventos y simular un activador desde su propio código o desde un asistente de IA. Workflow Trigger Extensions pone a su disposición una API REST y un servidor MCP, y puede conectarse a un repositorio de GitHub para que su código de activadores personalizado esté sujeto a control de versiones. Estos tres elementos se gestionan en la página «Desarrollador».

Simulación de un activador

Probar un flujo de trabajo de Shopify Flow suele implicar llevar a cabo la acción real en su tienda: editar un producto, realizar un pedido o esperar a que se realice una encuesta. La simulación elimina esa espera: elija un activador, asigne un recurso y se activará como si el evento real acabara de producirse.

Dos formas de ejecutarlo:

• En la aplicación, abra cualquier evento en el «Historial de eventos» y seleccione de nuevo «Simular». De este modo, se volverá a activar ese mismo evento.
• A través de la API o del MCP, con un identificador de recurso o un evento anterior.

La simulación es deliberadamente fiel. No crea una carga útil abreviada, sino que sigue el mismo proceso que un webhook real de Shopify; por lo tanto, lo que recibe su flujo de trabajo es exactamente lo mismo que recibiría en entorno de producción.

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}'

Una ejecución de prueba valida el activador, resuelve el tema y le muestra el payload, sin activar nada. Elimine dryRun para activarlo de verdad. También puede pasar {"fromHistoryId":"456"} para volver a activar un evento anterior en lugar de crear uno nuevo.

Los activadores que funcionan mediante sondeo, en lugar de mediante un webhook, no se pueden simular; en la lista de activadores aparecen como simulatable: false.

Claves de API

Cree una clave en la página «Desarrollador» y seleccione su nivel de acceso:

• Solo lectura: ver los activadores y su estado, consultar el historial de eventos, las estadísticas y los permisos.
• Lectura y escritura; además, activación y desactivación de los activadores.
• Leer, escribir y ejecutar; además, simular activadores y probar código de activadores personalizados.

La clave completa se muestra una sola vez, en el momento de su creación. Las claves se almacenan en forma de hash y pueden revocarse en cualquier momento. Envíela como un token «Bearer»:

Authorization: Bearer ftk_your_key_here

La simulación se sitúa en un nivel superior por el motivo mencionado anteriormente: ejecuta sus automatizaciones de forma real, por lo que una clave utilizada para lecturas cotidianas no puede activarlas.

API REST

Método	Ruta	Nivel	Objetivo
OBTENER	/api/v1	ninguno	Índice de la API: confirma que la API está operativa
OBTENER	/api/v1/me	leer	Compruebe la autenticación y consulte el nivel de su clave
OBTENER	/api/v1/triggers	leer	Cada activador, con su estado para su tienda
OBTENER	/api/v1/triggers/:handle	leer	Un activador en detalle
PUT	/api/v1/triggers/:handle	escribir	Activar o desactivar un activador
PUT	/api/v1/triggers	escribir	Activar o desactivar varios dispositivos en una sola llamada
PUBLICAR	/api/v1/triggers/:handle/simulate	ejecutar	Simular un activador
OBTENER	/api/v1/triggers/custom	leer	Sus propios activadores personalizados, con su código
OBTENER	/api/v1/triggers/custom/:handle/test	leer	El evento de muestra capturado para un activador personalizado
PUBLICAR	/api/v1/triggers/custom/:handle/test	ejecutar	Ejecutar código de activador personalizado sin guardar ni activar
OBTENER	/api/v1/history	leer	Enumerar eventos activadores
OBTENER	/api/v1/history/:id	leer	Obtenga un evento, junto con su payload
OBTENER	/api/v1/stats	leer	Totales, índice de éxito, desglose por estado
OBTENER	/api/v1/permissions	leer	Qué permisos de acceso a datos ha concedido y qué funciones permite cada uno de ellos

GET /api/v1/triggers Es muy útil para la configuración: para cada activador, le indica qué permiso necesita, si dicho permiso está concedido, si el activador está activado y en qué parte de la aplicación puede gestionarlo.

Activar y desactivar los activadores

PUT Se utiliza esto en lugar de PATCH porque la llamada es idempotente: volver a ejecutarla tras un tiempo de espera no puede provocar que se aplique dos veces ninguna operación, lo cual es importante cuando un asistente controla la 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 función «Enabling» nunca concede ningún permiso. Si el activador necesita un permiso que usted no haya concedido, la llamada se ejecutará con éxito y le indicará exactamente qué falta y dónde debe concederlo:

{
  "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."
}

Ese enlace abre la página «Permisos» y se desplaza directamente hasta la ficha que necesita.

Añada "sync": true para que también se inicie una sincronización de datos, de modo que el activador actúe sobre los registros que ya existen y no solo sobre los que se crean a partir de ahora.

Para cambiar varias opciones a la vez, la función PUT /api/v1/triggers admite una lista explícita o una categoría completa:

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

Conectar GitHub

En la página «Desarrollador», la pestaña «Conexiones» le permite conectar un repositorio de GitHub para su código de Activadores personalizados. Los cambios pasan a estar disponibles para su revisión en una solicitud de incorporación de cambios; podrá ver quién ha modificado qué y podrá revertir una transformación que haya dejado de funcionar.

Al hacer clic en «Conectar», se instala nuestra aplicación de GitHub en la cuenta que elija. Usted decide a qué repositorios puede acceder la aplicación y puede revocar dicho acceso desde GitHub en cualquier momento. Al seleccionar un repositorio, todos los activadores personalizados que ya tenga se guardarán en él de forma inmediata, de modo que la aplicación se adapte desde el principio en lugar de ir completándose con el tiempo.

A qué se dedica	¿Qué ocurre?
Crear, editar o duplicar un activador en la aplicación	El archivo se ha incorporado a su repositorio
Eliminar un activador de la aplicación	El archivo se ha eliminado de su repositorio
Envíe una modificación a la rama conectada	El código del activador se actualiza en la aplicación

Cada activador es un archivo cuyo nombre coincide con su identificador y que contiene exactamente el módulo que ve en el editor, sin ningún código adicional a su alrededor. Por lo tanto, puede abrirlo en su propio editor, ejecutarlo y comprobar su sintaxis como cualquier otro archivo JavaScript; a continuación, utilice el punto final /test mencionado anteriormente para ejecutarlo con un evento real capturado antes de realizar el commit.

Volver a una versión anterior

No es necesario conocer Git para deshacer un cambio. Una vez conectado el repositorio, el editor de activadores muestra un menú desplegable «Versión» en el que aparecen todas las versiones anteriores de ese archivo, junto con su fecha y autor. Seleccione una y se cargará en el editor como un cambio sin guardar, de modo que pueda leerla primero; al guardarla, se restablecerá como una nueva confirmación.

Modificar o desconectar

La opción «Cambiar repositorio» le devuelve al selector sin modificar la instalación. «Desconectar» revoca la instalación en GitHub y la elimina también aquí, tal y como indica su nombre. «Gestionar permisos» abre la configuración de la instalación en GitHub, donde puede añadir o eliminar repositorios.

Prueba del código de activador personalizado

Si guarda el código de su activador personalizado en un repositorio y lo edita en su propio editor, podrá ejecutarlo sobre el evento de muestra capturado sin necesidad de guardarlo primero en la aplicación.

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}')"

Obtendrá lo que muestra el botón «Test» de la aplicación: si se ejecutaría, el objeto de salida, sus líneas de ctx.log y el tiempo de ejecución.

No se ejecuta ni se guarda nada: no se ejecuta ningún flujo de trabajo, no se registra ningún evento, no se consume ninguna asignación y el código almacenado permanece intacto. Se puede ejecutar con total seguridad cada vez que se guarde desde un observador de archivos. Consulte Activadores personalizados para ver el flujo de trabajo completo.

Servidor MCP

La pestaña «MCP» de la página «Desarrollador» muestra la URL del servidor y un comando de conexión listo para copiar para Claude, Cursor, VS Code, Gemini CLI y otras herramientas. Las herramientas reflejan los puntos finales REST, y el conjunto de herramientas se adapta al nivel de su clave: una clave de solo lectura no tiene acceso en absoluto a las herramientas de escritura ni de ejecución.

Herramienta	Nivel	Para qué sirve
list_triggers	leer	Cada activador y su estado
list_custom_triggers	leer	Sus propios activadores personalizados, con su código
get_custom_trigger_sample	leer	El evento capturado que un activador personalizado comprueba
list_history	leer	Activadores recientes
get_event	leer	Un evento, incluida su payload
get_stats	leer	Estadísticas agregadas
get_permissions	leer	Permisos concedidos y lo que permiten hacer
get_trigger	escribir	Un activador en detalle
set_trigger	escribir	Activar o desactivar un activador
set_triggers_bulk	escribir	Encienda o apague varios a la vez
simulate_trigger	ejecutar	Activar un activador cuando se desee
test_custom_trigger	ejecutar	Ejecutar código de activador personalizado sin guardar ni activar

Esto es lo que hace que un asistente resulte verdaderamente útil: puede enumerar lo que hay, explicar qué necesita un activador, activarlo, ejecutar un evento de prueba, leer el resultado y, en el caso de los activadores personalizados, reescribir el código y probarlo, todo ello sin que usted tenga que salir de la conversación.

Cómo se protegen sus datos

Las cargas útiles de los eventos se devuelven con los datos personales ocultos: las direcciones de correo electrónico, los números de teléfono, los números de tarjeta y los campos con nombres de personas se sustituyen por ***. Los identificadores de recursos Shopify y los campos relacionados con la empresa se mantienen intactos para que la carga útil siga siendo útil.

El enmascaramiento se aplica a los nombres de los campos y a los patrones de valores, por lo que es una medida de precaución, pero no ofrece garantías: los datos personales contenidos en un campo de texto libre podrían seguir siendo visibles. Además, a los mensajes de error se les eliminan los detalles de diagnóstico internos antes de que salgan del servidor.

La conexión con GitHub no almacena ninguna credencial que pueda filtrarse: solo se conserva el identificador de instalación, y el acceso al repositorio se realiza mediante un token generado bajo demanda que caduca en el plazo de una hora.

Próximos pasos

• Activadores personalizados - Cree su propio activador con unas pocas líneas de JavaScript.
• Planes y uso - qué se considera un acontecimiento y cómo funciona la prestación.
• Introducción a Workflow Trigger Extensions - cómo funcionan los activadores y cómo activarlos.

Límites de frecuencia

La API REST y el servidor MCP comparten un mismo presupuesto por cada clave de API.

• 300 solicitudes por cada 60 segundos por clave, en una ventana fija.
• Las llamadas a nivel de ejecución disponen de un segundo presupuesto, más restrictivo, de 60 por hora. Se consumen ambos, por lo que una ráfaga de ejecuciones también merma la asignación compartida. En el caso de esta aplicación, eso significa simular un activador y ejecutar código de activador personalizado, dos acciones que, en realidad, activan sus flujos de trabajo.
• Es igual en todos los planes. Los contadores de su plan activan activadores, no llamadas a la API, por lo que la actualización no aumenta estas cifras.
• Se devuelve el código de estado HTTP 429. Espere un tiempo y vuelva a intentarlo, a ser posible con un retardo exponencial.
• En caso de que nuestra caché no esté disponible durante un breve periodo de tiempo, el limitador se desactiva en lugar de bloquear su integración.

Los webhooks entrantes de Shopify no están sujetos a límites de frecuencia

No limitamos el número de webhooks que nos envía Shopify: se aceptan tal y como llegan y se ponen en cola. El límite máximo es el número de eventos permitidos en los últimos 30 días según su plan.

Hay algo que conviene saber si escribe activadores personalizados: su código se ejecuta cada vez que se produce un evento del tema que está escuchando, y cada ejecución cuenta como un evento, incluidos aquellos que se filtran al devolver un valor null. El coste es el mismo que el del activador integrado para el mismo evento.

Shopify

Se trata de los límites que impone Shopify a las API de Shopify, no los nuestros. Se aplican a lo que esta aplicación (y sus flujos de trabajo) pueden hacer en el lado de Shopify, y es posible que los alcance en una tienda de gran tamaño, incluso aunque se encuentre bien por debajo de nuestros límites.

• Los matrices de entrada tienen un límite máximo de 250 elementos en todas las API de Shopify. Se rechazará cualquier solicitud que contenga una matriz con un número mayor de elementos.
• La paginación se detiene a los 25 000 objetos. Los recuentos son precisos hasta 25 000; por encima de esa cifra, Shopify devuelve 25001, lo que significa «más de 25 000». Si necesita profundizar más, aplique primero un filtro.
• El uso de la API de administración de GraphQL se mide en función del coste calculado de las consultas, en puntos por segundo, y el límite máximo depende del plan Shopify de la tienda:

Shopify plan	Puntos por segundo
Estándar	100
Avanzado	200
Además	1000
Enterprise (Componentes de comercio)	2000

La API de Tienda online no tiene límite de solicitudes.

Más información: Shopify Límites de rate de la API