Workflow Trigger ExtensionsWorkflow Trigger Extensions

API para programadores, MCP, GitHub e simulação de gatilhos

Pode verificar os seus gatilhos, ativá-los ou desativá-los, consultar o histórico de eventos e simular um gatilho a partir do seu próprio código ou de um assistente de IA. O Workflow Trigger Extensions disponibiliza uma API REST e um servidor MCP, e pode ligar-se a um repositório do GitHub para que o seu código de gatilho personalizado fique sob controlo de versões. Todos estes três elementos são geridos na página «Desenvolvedor».

Simular um gatilho

Testar um fluxo de trabalho no Flow significa, normalmente, reproduzir a situação real na sua loja - editar um produto, efetuar uma encomenda, aguardar o resultado de uma votação. A simulação elimina essa espera: escolha um gatilho, associe-o a um recurso e ele é acionado como se o evento real tivesse acabado de ocorrer.

Duas formas de o executar:

  • Na aplicação. Abra qualquer evento no Histórico de Eventos e selecione «Simular» novamente. Isso reativa exatamente esse evento.
  • Através da API ou do MCP, com um ID de recurso ou um evento anterior.

A simulação é deliberadamente fiel. Não cria uma carga útil simplificada - segue o mesmo fluxo que um webhook real do Shopify, pelo que o que o seu fluxo de trabalho recebe é exatamente o que receberia em produção.

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

Um teste de simulação valida o gatilho, resolve o tópico e mostra a carga útil - sem disparar nada. Remova dryRun para o disparar a sério. Também pode passar {"fromHistoryId":"456"} para voltar a disparar um evento anterior, em vez de criar um novo.

Os gatilhos acionados por sondagem, em vez de por webhook, não podem ser simulados; aparecem com a mensagem simulatable: false na lista de gatilhos.

Chaves API

Crie uma chave na página «Desenvolvedor» e selecione o seu nível de acesso:

  • Apenas leitura - listar os gatilhos e o seu estado, consultar o histórico de eventos, as estatísticas e as permissões.
  • Ler e escrever - e também ativar e desativar os gatilhos.
  • Ler, escrever e executar - simular também gatilhos e testar código de gatilhos personalizados.

A chave completa é apresentada uma única vez, no momento da criação. As chaves são armazenadas sob a forma de hash e podem ser revogadas a qualquer momento. Envie-a como um token «Bearer»:

Authorization: Bearer ftk_your_key_here

A simulação funciona num nível próprio devido à razão acima referida: executa as suas automatizações em tempo real, pelo que uma chave utilizada para leituras diárias não as pode acionar.

A página «Desenvolvedor» com o URL base da API REST, um pedido de teste e o botão «Criar chave da API»
A página «Desenvolvedor»: o URL base da API REST, um pedido para testar uma chave e o local onde as chaves são criadas.

API REST

Método Caminho Nível Objetivo
OBTER /api/v1 nenhuma Índice da API - confirma que a API está ativa
OBTER /api/v1/me ler Verifique a autenticação e veja o nível da sua chave
OBTER /api/v1/triggers ler Cada gatilho, com o seu estado para a sua loja
OBTER /api/v1/triggers/:handle ler Um gatilho em pormenor
PUT /api/v1/triggers/:handle escrever Ativar ou desativar um gatilho
PUT /api/v1/triggers escrever Ligar ou desligar vários dispositivos numa única chamada
PUBLICAÇÃO /api/v1/triggers/:handle/simulate executar Simular um gatilho
OBTER /api/v1/triggers/custom ler Os teus próprios gatilhos personalizados, com o respetivo código
OBTER /api/v1/triggers/custom/:handle/test ler O evento da amostra capturada para um gatilho personalizado
PUBLICAÇÃO /api/v1/triggers/custom/:handle/test executar Executar código de gatilho personalizado sem guardar nem acionar
OBTER /api/v1/history ler Listar eventos desencadeadores
OBTER /api/v1/history/:id ler Obter um evento, com a sua carga útil
OBTER /api/v1/stats ler Totais, taxa de sucesso, repartição por estado
OBTER /api/v1/permissions ler Que autorizações de acesso aos dados concedeu e o que cada uma delas permite

GET /api/v1/triggers é útil para a configuração: para cada gatilho, indica a autorização necessária, se essa autorização está concedida, se o gatilho está ativado e onde, na aplicação, é possível geri-lo.

Ativar e desativar os gatilhos

PUT é utilizado em vez de PATCH porque a chamada é idempotente - repeti-la após um tempo de espera não pode resultar na aplicação dupla de nada, o que é importante quando um assistente está a controlar a 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}'

A função «Enabling» nunca concede uma autorização. Se o gatilho necessitar de uma autorização que ainda não tenha concedido, a chamada é mesmo assim bem-sucedida e indica-lhe exatamente o que falta e onde deve concedê-la:

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

Esse link abre a página «Permissões», com o cursor já posicionado no cartão de que precisa.

Adicione "sync": true para iniciar também uma sincronização de dados, de modo a que o gatilho funcione em registos que já existam, em vez de apenas nos que forem criados a partir de agora.

Para alternar entre vários de uma só vez, o comando PUT /api/v1/triggers aceita uma lista explícita ou uma categoria inteira:

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

Ligar ao GitHub

Na página «Desenvolvedor», o separador «Ligações» permite-lhe ligar um repositório do GitHub para o seu código Gatilhos personalizados. As alterações ficam disponíveis para revisão numa solicitação de pull, pode ver quem alterou o quê e pode reverter uma transformação que deixou de funcionar.

Ao clicar em «Ligar», a nossa aplicação do GitHub é instalada na conta que escolher. É o utilizador que decide quais os repositórios a que a aplicação tem acesso e pode revogar esse acesso no GitHub a qualquer momento. Ao selecionar um repositório, todos os gatilhos personalizados que já tiver são imediatamente gravados nesse repositório, pelo que este começa por corresponder à aplicação, em vez de ir sendo preenchido ao longo do tempo.

O que fazes O que acontece
Criar, editar ou duplicar um gatilho na aplicação O ficheiro foi submetido ao seu repositório
Eliminar um gatilho na aplicação O ficheiro foi removido do seu repositório
Enviar uma alteração para o ramo ligado O código do gatilho é atualizado na aplicação

Cada trigger é um ficheiro com o nome do seu identificador, que contém exatamente o módulo que se vê no editor - sem nada à sua volta. Assim, pode abri-lo no seu próprio editor, executá-lo e submetê-lo a uma verificação de código como qualquer outro ficheiro JavaScript; depois, utilize o ponto final /test acima para o executar num evento real capturado antes de efetuar o commit.

Voltar a uma versão anterior

Não é necessário saber usar o Git para anular uma alteração. Assim que um repositório estiver ligado, o editor de gatilhos apresenta um menu suspenso «Versão» que lista todas as versões anteriores desse ficheiro, com a respetiva data e autor. Escolha uma e esta será carregada no editor como uma alteração não guardada, para que possa lê-la primeiro - é ao guardar que a volta a colocar no repositório, como um novo commit.

Alterar ou desligar

A opção «Alterar repositório» leva-o de volta ao seletor sem alterar a instalação. A opção «Desligar» revoga a instalação no GitHub e remove-a também aqui, pelo que faz exatamente o que o nome indica. A opção «Gerir permissões» abre as definições de instalação no GitHub, onde pode adicionar ou remover repositórios.

Testar código de disparador personalizado

Se guardar o código do seu gatilho personalizado num repositório e o editar no seu próprio editor, pode executá-lo no evento de amostra capturado sem ter de o guardar primeiro na aplicação.

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

Recebes o que o botão «Testar» da aplicação mostra: se a função seria executada, o objeto de saída, as tuas linhas ctx.log e o tempo de execução.

Nada é executado e nada é guardado - nenhum fluxo de trabalho é executado, nenhum evento é registado, nenhuma cota é utilizada e o código armazenado permanece inalterado. É seguro executar este processo sempre que um observador de ficheiros efetuar um registo. Consulte Gatilhos personalizados para ver o fluxo de trabalho completo.

Servidor MCP

O separador «MCP» na página «Desenvolvedor» apresenta o URL do servidor e um comando de ligação pronto a copiar para o Claude, o Cursor, o VS Code, a CLI do Gemini e outras ferramentas. As ferramentas correspondem aos pontos finais REST, e o conjunto de ferramentas reflete o nível da sua chave - uma chave de leitura exclusiva não tem acesso às ferramentas de escrita ou de execução.

Ferramenta Nível O que faz
list_triggers ler Cada gatilho e o seu estado
list_custom_triggers ler Os teus próprios gatilhos personalizados, com o respetivo código
get_custom_trigger_sample ler O evento capturado que um gatilho personalizado verifica
list_history ler Eventos desencadeantes recentes
get_event ler Um evento, incluindo a sua carga útil
get_stats ler Estatísticas agregadas
get_permissions ler Permissões concedidas e o que estas desbloqueiam
get_trigger escrever Um gatilho em pormenor
set_trigger escrever Ativar ou desativar um gatilho
set_triggers_bulk escrever Ligar ou desligar vários ao mesmo tempo
simulate_trigger executar Disparar um gatilho quando necessário
test_custom_trigger executar Executar código de gatilho personalizado sem guardar nem acionar

É isto que torna um assistente verdadeiramente útil: consegue listar o que existe, explicar o que um gatilho necessita, ativá-lo, disparar um evento de teste, apresentar o resultado - e, no caso de gatilhos personalizados, reescrever o código e testá-lo - sem que tenhas de sair da conversa.

Como os seus dados são protegidos

As cargas úteis dos eventos são devolvidas com os dados pessoais ocultados: endereços de e-mail, números de telefone, números de cartão e campos com nomes de pessoas passam a ser ***. Shopify. Os IDs de recursos e os campos empresariais permanecem inalterados, para que a carga útil continue a ser útil.

O mascaramento aplica-se aos nomes dos campos e aos padrões de valores, pelo que é uma medida cautelosa, mas não constitui uma garantia - os dados pessoais contidos num campo de texto livre podem ainda assim ser revelados. As mensagens de erro também são desprovidas de detalhes de diagnóstico internos antes de saírem do servidor.

A ligação ao GitHub não armazena quaisquer credenciais que possam ser divulgadas: apenas é guardado o ID de instalação, e o acesso ao repositório utiliza um token gerado na altura do pedido, que expira no prazo de uma hora.

Próximos passos

Limites de taxa

A API REST e o servidor MCP partilham um único orçamento por chave de API.

  • 300 pedidos por cada 60 segundos por chave, num intervalo fixo.
  • As chamadas ao nível de execução têm um segundo limite, mais restrito, de 60 por hora. Utilizam ambos os limites, pelo que uma sequência de execuções também consome a cota partilhada. Para esta aplicação, isso significa simular um gatilho e executar código de gatilho personalizado, sendo que ambas as ações ativam efetivamente os seus fluxos de trabalho.
  • É igual em todos os planos. Os medidores do seu plano desencadeiam eventos, e não chamadas à API, pelo que a atualização não faz com que estes números aumentem.
  • A resposta recebida é um código HTTP 429. Aguarde e tente novamente, de preferência com um retardo exponencial.
  • Se o nosso cache ficar temporariamente indisponível, o limitador entra em modo de segurança, em vez de bloquear a sua integração.

Os webhooks de entrada do Shopify não estão sujeitos a limites de taxa

Não limitamos os webhooks que o Shopify nos envia - estes são aceites à medida que chegam e colocados em fila. O limite máximo é a quota de eventos de 30 dias do seu plano.

Uma coisa que vale a pena saber se escreveres gatilhos personalizados: o teu código é executado sempre que ocorre um evento do tópico que está a monitorizar, e cada execução conta como um evento, incluindo aqueles que filtras ao devolver um valor null. O custo é o mesmo que o de um gatilho integrado para o mesmo evento.

Shopify

Estes são os limites impostos pelo Shopify às APIs do Shopify, não os nossos. Aplicam-se ao que esta aplicação (e os seus fluxos de trabalho) podem fazer no lado do Shopify, e poderá atingi-los numa loja de grande dimensão, mesmo estando bem dentro dos nossos limites.

  • Os vetores de entrada estão limitados a 250 elementos em todas as APIs do Shopify. Um pedido com um vetor maior é rejeitado.
  • A paginação termina aos 25 000 objetos. As contagens são precisas até 25 000; acima desse valor, Shopify devolve 25001, o que significa «mais de 25 000». Se precisar de ir mais além, filtre primeiro.
  • A API de administração do GraphQL é cobrada com base no custo calculado das consultas, em pontos por segundo, e o limite máximo depende do plano Shopify da loja:
Shopify plano Pontos por segundo
Padrão 100
Avançado 200
Além disso 1000
Enterprise (Componentes de Comércio) 2000

A API do Storefront não está sujeita a limites de utilização.

Informações completas: Shopify Limites de taxa da API