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, podendo 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».

Simulação de um gatilho

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

Duas formas de o utilizar:

• Na aplicação. Abra qualquer evento no «Histórico de Eventos» e selecione novamente «Simular». Isso volta a disparar esse mesmo 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 payload simplificada - passa pelo mesmo fluxo de processamento que um webhook real do Shopify, pelo que o que o 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 mostra-lhe a payload - sem disparar nada. Remova dryRun para 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; apresentam o erro 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 - bem como ativar e desativar os gatilhos.
• Ler, escrever e executar - simule também gatilhos e teste código de gatilhos personalizado.

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 ao motivo acima referido: executa as suas automatizações em tempo real, pelo que uma chave utilizada para leituras diárias não pode ativá-las.

API REST

Método	Caminho	Nível	Objetivo
OBTER	/api/v1	nenhum	Índice da API - confirma que a API está operacional
OBTER	/api/v1/me	ler	Verifique a autenticação e consulte 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	Ativar ou desativar vários elementos numa única chamada
PUBLICAÇÃO	/api/v1/triggers/:handle/simulate	executar	Simular um gatilho
OBTER	/api/v1/triggers/custom	ler	Os seus 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 gatilhos
OBTER	/api/v1/history/:id	ler	Obter um evento, com o seu payload
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 é a ferramenta útil para a configuração: para cada gatilho, indica-lhe a autorização necessária, se essa autorização está concedida, se o gatilho está ativado e onde, na aplicação, pode geri-lo.

Ativar e desativar os gatilhos

PUT é utilizado em vez de PATCH porque a chamada é idempotente - a sua repetição após um tempo limite não pode aplicar duas vezes a mesma operação, o que é importante quando um assistente está a controlar 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 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 a visualização já posicionada diretamente no cartão de que necessita.

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árias opções de uma só vez, a função PUT /api/v1/triggers aceita uma lista explícita ou uma categoria completa:

{ "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 integração, pode ver quem alterou o quê e pode reverter uma transformação que tenha deixado de funcionar.

Ao estabelecer a ligação, a nossa aplicação GitHub é instalada na conta que escolher. É o senhor/a senhora 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 de que já dispõe 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 faz	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
Envie uma alteração para o ramo ligado	O código do gatilho é atualizado na aplicação

Cada gatilho corresponde a um ficheiro cujo nome corresponde ao seu identificador, contendo exatamente o módulo que vê no editor - sem qualquer código adicional à 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; em seguida, utilize o ponto final /test acima para o executar em relação a um evento real capturado antes de efetuar o commit.

Voltar a uma versão anterior

Não é necessário saber utilizar o Git para reverter uma alteração. Assim que um repositório estiver ligado, o editor «Gatilho» 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 aplicar, como um novo commit.

Alterar ou desligar

A opção «Alterar repositório» remete-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 o seu nome reflete exatamente o que faz. A opção «Gerir permissões» abre as definições da instalação no GitHub, onde pode adicionar ou remover repositórios.

Testar código de gatilho personalizado

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

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

Receberá o que o botão «Test» da aplicação apresenta: se a função seria executada, o objeto de saída, as suas 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 esta operação sempre que houver um registo de alterações num observador de ficheiros. Consulte Gatilhos personalizados para conhecer 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 Gemini CLI 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 única não tem acesso às ferramentas de escrita nem de execução.

Ferramenta	Nível	O que faz
list_triggers	ler	Cada gatilho e o seu estado
list_custom_triggers	ler	Os seus 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	Gatilhos recentes
get_event	ler	Um evento, incluindo a sua payload
get_stats	ler	Estatísticas agregadas
get_permissions	ler	Permissões concedidas e o que estas permitem
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	Acionar 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 tenha de sair da conversa.

Como são protegidos os seus dados

As cargas úteis dos eventos são devolvidas com os dados pessoais ocultados: os endereços de e-mail, os números de telefone, os números de cartão e os campos com nomes de pessoas passam a ser ***. Os IDs de recurso Shopify e os campos empresariais são mantidos inalterados, para que a payload 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 identificador da instalação, e o acesso ao repositório utiliza um token gerado na altura em que é solicitado, que expira no prazo de uma hora.

Próximos passos

• Gatilhos personalizados - crie o seu próprio gatilho com algumas linhas de JavaScript.
• Planos e utilização - o que se considera um evento e como funciona o subsídio.
• Introdução ao Workflow Trigger Extensions - como funcionam os gatilhos e como os ativar.

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 dispõem de um segundo orçamento, mais restrito, de 60 por hora. Estas consomem ambos, pelo que uma onda de execuções também consome a cota partilhada. No caso desta aplicação, isso significa simular um gatilho e executar código de gatilho personalizado, sendo que ambas as ações acionam efetivamente os seus fluxos de trabalho.
• É o mesmo em todos os planos. Os contadores do seu plano desencadeiam gatilhos, e não chamadas à API, pelo que a atualização não faz com que estes números aumentem.
• A consulta devolve um código de resposta HTTP 429. Aguarde e tente novamente, de preferência com um intervalo de espera exponencial.
• Caso a nossa cache fique temporariamente indisponível, o limitador funciona de forma a permitir o acesso, 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.

Há algo que vale a pena saber se escrever gatilhos personalizados: o seu código é executado em cada evento do tópico que está a monitorizar, e cada execução conta como um evento, incluindo aqueles que filtra 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 pela Shopify às APIs da Shopify, e 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 em uma 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 de dimensão superior é rejeitado.
• A paginação termina aos 25 000 objetos. As contagens são precisas até aos 25 000; acima desse valor, a função Shopify devolve 25001, o que significa «mais de 25 000». Se precisar de ir mais além, aplique primeiro um filtro.
• 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 da loja virtual não está sujeita a limites de frequência.

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