API para programadores e MCP

Tudo o que gere na aplicação, também pode gerir a partir do seu próprio código ou de um assistente de IA. O Workflow Webhooks disponibiliza duas interfaces: uma API REST e um servidor MCP. Ambas se encontram na página do Desenvolvedor.

Chaves API

Ambas as plataformas efetuam a autenticação através de uma chave API. Na página «Desenvolvedor», na secção «Chaves API», crie uma chave e selecione o seu nível de acesso:

Apenas leitura - listar webhooks, consultar o histórico de invocações e as estatísticas.
Leitura e escrita - bem como criar, atualizar e eliminar webhooks.
Ler, escrever e executar - bem como lançar uma invocação de teste ou reproduzir uma invocação anterior.

A chave completa é apresentada uma única vez, no momento da sua criação. Copie-a nessa altura e guarde-a num local seguro; não a poderá ver novamente. As chaves são armazenadas sob a forma de hash, nunca em texto simples, e pode revogar uma chave a qualquer momento.

Envie a chave como um token «Bearer» em cada pedido:

text

Authorization: Bearer fwk_your_key_here

Por que razão a execução constitui um nível distinto

A ativação de um Webhook executa efetivamente os seus fluxos de trabalho do Shopify Flow, e esses fluxos de trabalho podem alterar a sua loja - atribuir etiquetas aos pedidos, enviar e-mails, atualizar o estoque. Manter isso num nível separado significa que uma chave que atribua a um script ou a um assistente de IA para as tarefas diárias não pode acionar as suas automatizações acidentalmente. Atribua chaves de leitura por predefinição e crie uma chave de execução apenas quando for realmente necessário.

URL de base

A API e o servidor MCP são disponibilizados a partir de um nome de host dedicado:

text

https://shopify.workflow-webhooks.app

Assim, a API REST encontra-se em https://shopify.workflow-webhooks.app/api/v1 e o servidor MCP em https://shopify.workflow-webhooks.app/api/mcp. A página do Desenvolvedor apresenta ambos com um botão «Copiar».

Este nome de anfitrião serve apenas /api - a interface de administração incorporada mantém-se no seu próprio URL registado em Shopify. Mantê-los separados significa que o endereço que colar num script, numa tarefa de CI ou num cliente de IA é estável e não está relacionado com a incorporação da aplicação.

API REST

O URL de base é apresentado na página «Desenvolvedor». Os principais pontos de extremidade:

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 veja o nível da sua chave
OBTER	`/api/v1/webhooks`	ler	Listar webhooks
PUBLICAÇÃO	`/api/v1/webhooks`	escrever	Criar um webhook
OBTER	`/api/v1/webhooks/:id`	ler	Obter un webhook
PUT / PATCH	`/api/v1/webhooks/:id`	escrever	Atualizar um webhook
ELIMINAR	`/api/v1/webhooks/:id`	escrever	Eliminar um webhook
PUBLICAÇÃO	`/api/v1/webhooks/:id/test`	executar	Execute uma chamada de teste
OBTER	`/api/v1/history`	ler	Invocações de listas
OBTER	`/api/v1/history/:id`	ler	Obter uma invocação, com a respetiva payload
PUBLICAÇÃO	`/api/v1/history/:id/replay`	executar	Repetir uma invocação anterior
OBTER	`/api/v1/stats`	ler	Totais, taxa de sucesso, séries diárias
OBTER	`/api/v1/templates`	ler	Modelos de webhooks integrados

Uma verificação rápida para confirmar se a sua chave funciona:

bash

curl https://shopify.workflow-webhooks.app/api/v1/me \
  -H "Authorization: Bearer fwk_your_key_here"

json

{ "authenticated": true, "shop": "your-store.myshopify.com", "level": "READ" }

Servidor MCP

O servidor MCP permite que um assistente de IA (Claude, Cursor, VS Code, Gemini CLI e outros) interaja com os seus webhooks durante uma conversa. Na página «Desenvolvedor», o separador «MCP» apresenta o URL do servidor e um comando de ligação pronto a copiar para cada cliente, com a sua chave já inserida.

As ferramentas correspondem aos pontos finais REST, e o conjunto de ferramentas reflete o nível da sua chave: uma chave de leitura exclusiva nem sequer tem acesso às ferramentas que criam, eliminam ou acionam webhooks. Toda a autenticação e o tratamento de dados ocorrem do lado do servidor.

Como são protegidos os seus dados

Há duas coisas que convém saber antes de utilizar uma automação ou um assistente de IA com esta API.

O token de autenticação do seu webhook nunca é legível. O token ou o segredo de assinatura que definir num webhook não pode ser recuperado através da API ou do MCP, a qualquer nível. As respostas indicam-lhe apenas se um token está definido (hasToken), mas nunca o seu valor. Pode definir um novo; nunca poderá recuperar o antigo.

Os dados pessoais nas cargas úteis são mascarados. As cargas úteis dos webhooks provêm de sistemas externos e contêm frequentemente dados de clientes. Antes de uma payload de invocação sair do servidor, os valores que se assemelham a dados pessoais são substituídos por ***: endereços de e-mail, números de telefone, números de cartões e campos cujos nomes remetem para uma pessoa (customerName, shippingAddress e similares). Os cabeçalhos dos pedidos são sanitizados da mesma forma que o ecrã do histórico da aplicação o faz.

Esta ocultação é cuidadosa, mas não constitui uma garantia. Funciona com nomes de campos e padrões de valores, pelo que os dados pessoais contidos num campo de texto livre - uma nota, um comentário, o corpo de uma mensagem - podem ainda assim ser revelados. Considere que as respostas da API podem conter dados de clientes e armazene-as em conformidade.

Os testes e as repetições não consomem a sua cota. As invocações que efetuar através da API são registadas como testes, pelo que não são contabilizadas na cota mensal do seu plano. As repetições também não são contabilizadas, uma vez que a invocação original já o foi.

Próximos passos

Introdução ao Workflow Webhooks - como funcionam os webhooks e o mapeamento de payload.

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 onda de execuções também consome a cota partilhada. Para esta aplicação, isso significa a invocação de teste de um webhook e a reprodução de uma entrada do histórico, sendo que ambas as operações executam efetivamente os seus fluxos de trabalho do Shopify Flow.
É o mesmo em todos os planos. O seu plano contabiliza as invocações, e não as chamadas à API, pelo que a atualização não aumenta estes números.
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 recebidos não estão sujeitos a limites de frequência

Vale a pena esclarecer isto, pois é a pergunta que mais nos fazem: não limitamos o fluxo de webhooks recebidos. Enviamo-los assim que chegam, independentemente dos picos de tráfego que o seu sistema de origem produza - não existe qualquer limite por segundo ou por minuto da nossa parte.

O único limite é a cota de 30 dias de chamadas prevista no seu plano. Assim que essa cota for esgotada, as chamadas adicionais deixam de ser processadas até que o período seja renovado ou até que efetue um upgrade. Para além disso, aplicam-se os limites do serviço Shopify: o Shopify Flow tem os seus próprios limites de execução e a carga útil do gatilho está limitada a 50 KB.

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 do lado da 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 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