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

É possível verificar seus gatilhos, ativá-los ou desativá-los, consultar o histórico de eventos e simular um gatilho a partir de seu próprio código ou de um assistente de IA. O Workflow Trigger Extensions disponibiliza uma API REST e um servidor MCP, além de poder se conectar a um repositório do GitHub para que seu código de gatilho personalizado fique sob controle de versão. Todos os três são gerenciados na página do Desenvolvedor.

Simulação de um gatilho

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

Duas maneiras de executar um:

• No aplicativo. Abra qualquer evento no Histórico de Eventos e selecione “Simular” novamente. Isso aciona novamente esse evento específico.
• Por meio da API ou do MCP, utilizando um ID de recurso ou um evento anterior.

A simulação é deliberadamente fiel. Ela não cria uma carga de dados simplificada - ela passa pelo mesmo fluxo de processamento que um webhook real do Shopify, de modo que o que seu fluxo de trabalho recebe é exatamente o que receberia em produção.

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 exibe a payload - sem acionar nada. Remova dryRun para acioná-lo de fato. Você também pode passar {"fromHistoryId":"456"} para reativar um evento anterior, em vez de criar um novo.

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

Chaves de API

Crie uma chave na página “Desenvolvedor” e selecione seu nível de acesso:

• Somente leitura - listar os gatilhos e seu estado, consultar o histórico de eventos, as estatísticas e as permissões.
• Leitura e gravação - além de ativar e desativar os gatilhos.
• Ler, gravar e executar - além de simular gatilhos e testar códigos de gatilhos personalizados.

A chave completa é exibida uma única vez, no momento da criação. As chaves são armazenadas na 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 está em um nível à parte pelo motivo acima: ela executa suas automações de fato, de modo que uma chave utilizada para leituras cotidianas não pode acioná-las.

API REST

Método	Caminho	Nível	Objetivo
OBTER	/api/v1	nenhum	Índice da API - confirma que a API está em funcionamento
OBTER	/api/v1/me	ler	Verifique a autenticação e confira o nível da sua chave
OBTER	/api/v1/triggers	ler	Cada gatilho, com seu status para a sua loja
OBTER	/api/v1/triggers/:handle	ler	Um gatilho em detalhes
PUT	/api/v1/triggers/:handle	escrever	Ativar ou desativar um gatilho
PUT	/api/v1/triggers	escrever	Ativar ou desativar vários itens em uma única chamada
POST	/api/v1/triggers/:handle/simulate	executar	Simular um gatilho
OBTER	/api/v1/triggers/custom	ler	Seus próprios gatilhos personalizados, com seus códigos
OBTER	/api/v1/triggers/custom/:handle/test	ler	O evento de amostra capturada para um gatilho personalizado
POST	/api/v1/triggers/custom/:handle/test	executar	Executar código de gatilho personalizado sem salvar ou acionar
OBTER	/api/v1/history	ler	Listar eventos gatilhos
OBTER	/api/v1/history/:id	ler	Obter um evento, com seu payload
OBTER	/api/v1/stats	ler	Totais, taxa de sucesso, distribuição por status
OBTER	/api/v1/permissions	ler	Quais permissões de dados o(a) senhor(a) concedeu e o que cada uma delas permite

GET /api/v1/triggers é útil para a configuração: para cada gatilho, ele informa qual permissão é necessária, se essa permissão está concedida, se o gatilho está ativado e em que parte do aplicativo ele pode ser gerenciado.

Ativando e desativando os gatilhos

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

A função “Enabling” nunca concede uma permissão. Se o gatilho precisar de uma permissão que o senhor ainda não tenha concedido, a chamada ainda assim será bem-sucedida e informará exatamente o que está faltando e onde 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 a tela já posicionada diretamente no cartão de que o senhor precisa.

Adicione "sync": true para iniciar também uma sincronização de dados, de modo que o gatilho funcione em registros já existentes, e não apenas naqueles criados a partir de agora.

Para alternar entre várias opções 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" }

Conectar-se ao GitHub

Na página “Desenvolvedor”, a guia “Conexões” permite que você conecte um repositório do GitHub para o seu código do Gatilhos personalizados. As alterações ficam disponíveis para revisão em uma solicitação de pull; você pode ver quem alterou o quê e reverter uma transformação que deixou de funcionar.

Ao clicar em “Conectar”, nosso aplicativo do GitHub será instalado na conta que o(a) senhor(a) escolher. O(a) senhor(a) define quais repositórios o aplicativo poderá acessar e poderá revogar esse acesso no GitHub a qualquer momento. Ao selecionar um repositório, todos os gatilhos personalizados que o(a) senhor(a) já possui serão gravados nele imediatamente, de modo que ele já esteja alinhado com o aplicativo desde o início, em vez de ser preenchido gradualmente ao longo do tempo.

O que o(a) senhor(a) faz	O que acontece
Crie, edite ou duplique um gatilho no aplicativo	O arquivo foi enviado para o seu repositório
Excluir um gatilho no aplicativo	O arquivo foi removido do seu repositório
Envie uma alteração para o branch conectado	O código do gatilho é atualizado no aplicativo

Cada gatilho é um arquivo cujo nome corresponde ao seu identificador, contendo exatamente o módulo que o senhor vê no editor - sem nenhum código adicional em torno dele. Assim, o senhor pode abri-lo em seu próprio editor, executá-lo e verificar sua validade como faria com qualquer outro arquivo JavaScript; em seguida, utilize o endpoint /test acima para executá-lo em um evento real capturado antes de fazer o commit.

Voltar a uma versão anterior

Não é necessário ter conhecimento do Git para desfazer uma alteração. Assim que um repositório estiver conectado, o editor de gatilhos exibe um menu suspenso “Versão” que lista todas as versões anteriores daquele arquivo, com a respectiva data e autor. Escolha uma delas e ela será carregada no editor como uma alteração não salva, para que o senhor possa lê-la primeiro - é ao salvar que ela é restaurada, como um novo commit.

Alterar ou desconectar

A opção “Alterar repositório” leva-o de volta ao seletor sem alterar a instalação. A opção “Desconectar” revoga a instalação no GitHub e também a remove daqui; portanto, seu nome já explica o que significa. A opção “Gerenciar permissões” abre as configurações da instalação no GitHub, onde é possível adicionar ou remover repositórios.

Teste de código de gatilho personalizado

Se o senhor mantiver seu código de gatilho personalizado em um repositório e o editar em seu próprio editor, poderá executá-lo no evento de amostra capturado sem precisar salvá-lo primeiro no aplicativo.

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

O senhor receberá o que o botão “Test” do aplicativo exibe: se ele seria acionado, o objeto de saída, suas linhas de ctx.log e o tempo de execução.

Nada é disparado e nada é salvo - nenhum fluxo de trabalho é executado, nenhum evento é registrado, nenhuma cota é utilizada e o código armazenado permanece intacto. É seguro executar a cada salvamento a partir de um monitor de arquivos. Consulte Gatilhos personalizados para obter o fluxo de trabalho completo.

Servidor MCP

A guia “MCP” na página “Desenvolvedor” exibe a URL do servidor e um comando de conexão pronto para ser copiado para o Claude, o Cursor, o VS Code, a CLI do Gemini e outros. As ferramentas correspondem aos endpoints REST, e o conjunto de ferramentas reflete o nível da sua chave - uma chave somente leitura não tem acesso às ferramentas de gravação ou execução.

Ferramenta	Nível	O que ele faz
list_triggers	ler	Cada gatilho e seu estado
list_custom_triggers	ler	Seus próprios gatilhos personalizados, com seu código
get_custom_trigger_sample	ler	O evento capturado que um gatilho personalizado verifica
list_history	ler	Gatilhos recentes
get_event	ler	Um evento, incluindo seu payload
get_stats	ler	Estatísticas agregadas
get_permissions	ler	Permissões concedidas e o que elas permitem acessar
get_trigger	escrever	Um gatilho em detalhes
set_trigger	escrever	Ativar ou desativar um gatilho
set_triggers_bulk	escrever	Ligue ou desligue vários de uma só vez
simulate_trigger	executar	Acionar um gatilho quando desejado
test_custom_trigger	executar	Executar código de gatilho personalizado sem salvar ou acionar

É isso que torna um assistente genuinamente útil: ele pode listar o que existe, explicar o que um gatilho precisa, ativá-lo, disparar um evento de teste, exibir o resultado - e, no caso de gatilhos personalizados, reescrever o código e testá-lo - sem que o senhor precise sair da conversa.

Como seus dados são protegidos

As cargas de dados 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 comerciais permanecem inalterados, de modo que a carga de dados continue sendo útil.

O mascaramento atua sobre nomes de campos e padrões de valores; portanto, é uma medida cuidadosa, mas não constitui uma garantia - dados pessoais contidos em um campo de texto livre ainda podem ser revelados. As mensagens de erro também têm seus detalhes de diagnóstico internos removidos antes de saírem do servidor.

A conexão com o GitHub não armazena nenhuma credencial que possa vazar: apenas o ID da instalação é mantido, e o acesso ao repositório utiliza um token gerado sob demanda que expira em até uma hora.

Próximos passos

• Gatilhos personalizados - crie seu próprio gatilho com algumas linhas de JavaScript.
• Planos e uso - o que se considera um evento e como funciona o auxílio.
• Introdução ao livro Workflow Trigger Extensions - como funcionam os gatilhos e como ativá-los.

Limites de taxa

A API REST e o servidor MCP compartilham um único limite por chave de API.

• 300 solicitações a cada 60 segundos por chave, em uma janela fixa.
• As chamadas no nível de execução contam com um segundo limite, mais restrito, de 60 por hora. Elas consomem ambos, de modo que uma sequência de execuções também consome a cota compartilhada. Para este aplicativo, isso significa simular um gatilho e executar código de gatilho personalizado, ações que, na prática, acionam seus fluxos de trabalho.
• É o mesmo em todos os planos. Os medidores do seu plano acionam gatilhos, e não chamadas de API; portanto, a atualização não aumenta esses números.
• A consulta retorna um código HTTP 429. Aguarde e tente novamente, de preferência com um intervalo exponencial.
• Caso nosso cache fique indisponível por um breve período, o limitador entrará em modo de falha aberta, em vez de bloquear sua integração.

Os webhooks de entrada do Shopify não estão sujeitos a limites de frequência

Não limitamos os webhooks que o Shopify nos envia - eles são aceitos assim que chegam e colocados em fila. O limite máximo é a cota de eventos de 30 dias do seu plano.

Uma informação importante para quem escreve gatilhos personalizados: seu código é executado a cada evento do tópico que ele monitora, e cada execução conta como um evento, inclusive aqueles que você filtra ao retornar null. O custo é o mesmo que o de um gatilho embutido para o mesmo evento.

Shopify

Esses são os limites impostos pelo Shopify às APIs do Shopify, e não os nossos. Eles se aplicam ao que este aplicativo (e seus fluxos de trabalho) podem fazer no lado do Shopify, e é possível que você os atinja em uma loja de grande porte, mesmo estando bem dentro dos nossos limites.

• Os arranjos de entrada estão limitados a 250 itens em todas as APIs do Shopify. Uma solicitação com um arranjo maior será rejeitada.
• A paginação é interrompida ao atingir 25.000 objetos. As contagens são precisas até 25.000; acima desse número, Shopify retorna 25001, o que significa “mais de 25.000”. Caso precise ir mais além, aplique um filtro 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	1.000
Enterprise (Componentes de Comércio)	2000

A API da loja virtual não possui limitação de taxa.

Detalhes completos: Shopify Limites de taxa da API