API para desenvolvedores, MCP, GitHub e simulação de gatilhos
Você pode verificar 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, 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 “Desenvolvedor”.
Simulação de um gatilho
Testar um fluxo de trabalho no Flow normalmente significa reproduzir a situação real em sua loja - editar um produto, fazer um pedido, aguardar o resultado de uma enquete. 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 exatamente esse evento.
- Por meio da API ou do MCP, com um ID de recurso ou um evento anterior.
A simulação é deliberadamente fiel. Ela não cria uma carga de dados simplificada - passa pelo mesmo fluxo 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 carga útil - sem acionar nada. Remova dryRun para acioná-lo de verdade. Você também pode passar {"fromHistoryId":"456"} para reacionar 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 escolha seu nível de acesso:
- Somente leitura - listar os gatilhos e seus estados, consultar o histórico de eventos, estatísticas e 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_hereA simulação fica em um nível à parte pelo motivo mencionado acima: ela executa suas automações de verdade, de modo que uma chave usada para leituras diárias 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 veja o nível da sua chave |
| OBTER | /api/v1/triggers |
ler | Cada gatilho, com seu estado 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 o código correspondente |
| 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 desencadeadores |
| OBTER | /api/v1/history/:id |
ler | Obter um evento, com sua carga útil |
| OBTER | /api/v1/stats |
ler | Totais, taxa de sucesso, distribuição por status |
| OBTER | /api/v1/permissions |
ler | Quais permissões de acesso a dados você concedeu e o que cada uma delas permite |
GET /api/v1/triggers É a ferramenta útil para a configuração: para cada gatilho, ela 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 é usado em vez de PATCH porque a chamada é idempotente - repeti-la após um tempo limite não pode aplicar nada duas vezes, 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 você ainda não tenha concedido, a chamada ainda 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” já com o rolagem direto no cartão que você precisa.
Adicione "sync": true para iniciar também uma sincronização de dados, de modo que o gatilho funcione em registros que já existam, 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 o 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”, o aplicativo do GitHub será instalado na conta que você escolher. Você decide quais repositórios o aplicativo poderá acessar e pode revogar esse acesso no GitHub a qualquer momento. Ao selecionar um repositório, todos os gatilhos personalizados que você 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 você faz | O que acontece |
|---|---|
| Criar, editar ou duplicar 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 |
| Enviar 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 você vê no editor - sem nada a mais. Assim, você pode abri-lo em seu próprio editor, executá-lo e verificar sua validade como qualquer outro arquivo JavaScript; depois, use o endpoint /test acima para executá-lo em um evento real capturado antes de fazer o commit.
Voltar a uma versão anterior
Você não precisa saber usar o 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 data e o autor. Escolha uma delas e ela será carregada no editor como uma alteração não salva, para que você possa lê-la primeiro - é ao salvar que ela é restaurada, como um novo commit.
Alterar ou desconectar
A opção “Alterar repositório” leva você 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, faz exatamente o que diz. A opção “Gerenciar permissões” abre as configurações da instalação no GitHub, onde você pode adicionar ou remover repositórios.
Testando código de gatilho personalizado
Se você mantiver seu código de gatilho personalizado em um repositório e editá-lo 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}')"Você recebe o que o botão “Test” do aplicativo exibe: se o código seria executado, 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 observador de arquivos. Consulte Gatilhos personalizados para ver o fluxo de trabalho completo.
Servidor MCP
A aba “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, o Gemini CLI 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 o código correspondente |
get_custom_trigger_sample |
ler | O evento capturado que um gatilho personalizado verifica |
list_history |
ler | Eventos desencadeadores recentes |
get_event |
ler | Um evento, incluindo sua carga útil |
get_stats |
ler | Estatísticas agregadas |
get_permissions |
ler | Permissões concedidas e o que elas permitem |
get_trigger |
escrever | Um gatilho em detalhes |
set_trigger |
escrever | Ativar ou desativar um gatilho |
set_triggers_bulk |
escrever | Ligar ou desligar vários de uma vez |
simulate_trigger |
executar | Disparar um gatilho quando solicitado |
test_custom_trigger |
executar | Executar código de gatilho personalizado sem salvar ou acionar |
É isso que torna um assistente realmente útil: ele pode listar o que já 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 você precise sair da conversa.
Como seus dados são protegidos
As cargas de dados dos eventos são retornadas com os dados pessoais mascarados: endereços de e-mail, números de telefone, números de cartão e campos com nomes de pessoas são substituídos por ***. Shopify. Os IDs de recursos e os campos comerciais permanecem intactos, para que a carga de dados continue sendo útil.
O mascaramento funciona em nomes de campos e padrões de valores; portanto, é uma medida cuidadosa, mas não oferece 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 menos de uma hora.
Próximos passos
- Gatilhos personalizados - crie seu próprio gatilho com apenas algumas linhas de JavaScript.
- Planos e uso - o que é considerado um evento e como funciona o subsídio.
- 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 recebem 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 realmente acionam seus fluxos de trabalho.
- É o mesmo em todos os planos. Os medidores do seu plano acionam eventos, e não chamadas de API; portanto, a atualização não aumenta esses números.
- A resposta recebida é um código HTTP 429. Aguarde um tempo e tente novamente, de preferência com um intervalo exponencial.
- Se nosso cache ficar 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 têm limitação de taxa
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 coisa que vale a pena saber se você 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 você pode atingi-los 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 é rejeitada.
- A paginação é interrompida ao atingir 25.000 objetos. As contagens são precisas até 25.000; acima desse número,
Shopifyretorna25001, o que significa “mais de 25.000”. Se você precisar ir mais além, faça uma filtragem 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 do Storefront não tem limitação de taxa.
Detalhes completos: Shopify Limites de taxa da API