Workflow Trigger ExtensionsWorkflow Trigger Extensions

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

Puedes revisar tus activadores, activarlos o desactivarlos, consultar el historial de eventos y simular un activador desde tu propio código o desde un asistente de IA. Workflow Trigger Extensions ofrece una API REST y un servidor MCP, y puede conectarse a un repositorio de GitHub para que tu código de activador personalizado esté bajo control de versiones. Los tres se gestionan en la página «Desarrollador».

Simulación de un disparador

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

Dos formas de ejecutarlo:

  • En la aplicación, abre cualquier evento en el «Historial de eventos» y vuelve a seleccionar «Simular». De este modo, se vuelve 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 que lo que recibe tu flujo de trabajo es exactamente lo que recibiría en producción.

Dry run firstbash
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 prueba de simulación valida el disparador, resuelve el tema y te muestra la carga útil, sin activar nada. Elimina dryRun para activarlo de verdad. También puedes pasar {"fromHistoryId":"456"} para reactivar un evento anterior en lugar de crear uno nuevo.

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

Claves de API

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

  • Solo lectura: ver los desencadenantes y su estado, consultar el historial de eventos, las estadísticas y los permisos.
  • Leer y escribir, así como activar y desactivar los disparadores.
  • Leer, escribir y ejecutar; además, simular disparadores y probar código de disparadores personalizado.

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íala como un token «Bearer»:

Authorization: Bearer ftk_your_key_here

La simulación se sitúa por debajo de su propio nivel por la razón mencionada anteriormente: ejecuta las automatizaciones de verdad, por lo que una clave utilizada para las lecturas cotidianas no puede activarlas.

La página «Desarrollador», con la URL base de la API REST, una solicitud de prueba y el botón «Crear clave API»
La página «Desarrollador»: la URL base de la API REST, una solicitud para probar una clave y el lugar donde se crean las claves.

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 Comprueba la autenticación y consulta el nivel de tu clave
OBTENER /api/v1/triggers leer Cada disparador, con su estado para tu tienda
OBTENER /api/v1/triggers/:handle leer Un desencadenante en detalle
PUT /api/v1/triggers/:handle escribir Activar o desactivar un disparador
PUT /api/v1/triggers escribir Activar o desactivar varios elementos en una sola llamada
PUBLICAR /api/v1/triggers/:handle/simulate ejecutar Simular un disparador
OBTENER /api/v1/triggers/custom leer Tus propios desencadenantes personalizados, con su código
OBTENER /api/v1/triggers/custom/:handle/test leer El evento de muestra capturada para un disparador 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 desencadenantes
OBTENER /api/v1/history/:id leer Obtener un evento, con su carga útil
OBTENER /api/v1/stats leer Totales, tasa de éxito, desglose por estado
OBTENER /api/v1/permissions leer Qué permisos de datos has concedido y qué funciones desbloquea cada uno de ellos

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

Activar y desactivar los disparadores

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 nada por duplicado, lo cual es importante cuando un asistente controla la API.

Enable one triggerbash
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 «Enable» nunca concede ningún permiso. Si el disparador necesita un permiso que tú no has concedido, la llamada se ejecuta con éxito y te indica exactamente qué falta y dónde debes 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 necesitas.

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

Para cambiar varias opciones a la vez, 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» te permite conectar un repositorio de GitHub para tu código de Desencadenantes personalizados. Los cambios se pueden revisar en una solicitud de incorporación de cambios, puedes ver quién ha modificado qué y puedes 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 elijas. Tú decides a qué repositorios puede acceder y puedes revocar ese acceso desde GitHub en cualquier momento. Al seleccionar un repositorio, se guardan en él inmediatamente todos los desencadenantes personalizados que ya tengas, de modo que la aplicación se adapta desde el principio, en lugar de ir completándose con el tiempo.

A qué te dedicas ¿Qué ocurre?
Crear, editar o duplicar un activador en la aplicación El archivo se ha guardado en tu repositorio.
Eliminar un activador de la aplicación El archivo se ha eliminado de tu repositorio
Enviar una modificación a la rama conectada El código del disparador se actualiza en la aplicación

Cada disparador es un archivo cuyo nombre coincide con su identificador y que contiene exactamente el módulo que ves en el editor, sin nada más a su alrededor. Así que puedes abrirlo en tu propio editor, ejecutarlo y comprobar su sintaxis como cualquier otro archivo JavaScript; después, utiliza el punto final /test indicado anteriormente para ejecutarlo con un evento real capturado antes de confirmar los cambios.

Volver a una versión anterior

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

Cambiar o desconectar

La opción «Cambiar repositorio» te lleva de vuelta 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 puedes añadir o eliminar repositorios.

Prueba del código de un disparador personalizado

Si guardas el código de tu activador personalizado en un repositorio y lo editas en tu propio editor, puedes ejecutarlo con el evento de muestra capturado sin necesidad de guardarlo primero en la aplicación.

Test the file you are editingbash
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}')"

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

No se ejecuta nada 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 guarda desde un observador de archivos. Consulta Desencadenantes 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 depende del nivel de tu 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 disparador y su estado
list_custom_triggers leer Tus propios desencadenantes personalizados, con su código
get_custom_trigger_sample leer El evento capturado con el que se compara un disparador personalizado
list_history leer Acontecimientos desencadenantes recientes
get_event leer Un evento, incluida su carga útil
get_stats leer Estadísticas agregadas
get_permissions leer Permisos concedidos y lo que permiten hacer
get_trigger escribir Un desencadenante en detalle
set_trigger escribir Activar o desactivar un disparador
set_triggers_bulk escribir Encender o apagar varios a la vez
simulate_trigger ejecutar Activar un disparador cuando se desee
test_custom_trigger ejecutar Ejecutar código de activación personalizado sin guardar ni activar

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

Cómo se protegen tus datos

Las cargas útiles de los eventos se devuelven con los datos personales enmascarados: 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 ***. Shopify Los identificadores de recursos 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 apareciendo. 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 utiliza un token generado en el momento que caduca en menos de una hora.

Próximos pasos

Límites de frecuencia

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

  • 300 solicitudes cada 60 segundos por clave, en una ventana fija.
  • Las llamadas de nivel de ejecución cuentan con un segundo presupuesto más ajustado 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 desencadenador y ejecutar código de desencadenador personalizado, dos acciones que realmente activan tus flujos de trabajo.
  • Es igual en todos los planes. Los contadores de tu plan activan eventos, no llamadas a la API, por lo que la actualización no hace que estas cifras aumenten.
  • Se devuelve el código HTTP 429. Espera un rato y vuelve a intentarlo, a ser posible con un retardo exponencial.
  • Si nuestra caché no está disponible durante un breve periodo de tiempo, el limitador se desactiva en lugar de bloquear tu 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 tu plan durante 30 días.

Hay algo que conviene saber si escribes disparadores personalizados: tu código se ejecuta cada vez que se produce un evento del tema al que está atento, y cada ejecución cuenta como un evento, incluidos aquellos que filtras devolviendo null. El coste es el mismo que el del disparador integrado para ese 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 tus flujos de trabajo) pueden hacer en el lado de Shopify, y es posible que los alcances en una tienda grande, incluso aunque te mantengas bien por debajo de nuestros límites.

  • Los matrices de entrada tienen un límite de 250 elementos en todas las API de Shopify. Se rechaza cualquier solicitud que contenga una matriz con más 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 necesitas ir más allá, aplica 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 de 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 Storefront no tiene límite de solicitudes.

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