API para desenvolvedores e MCP

Tudo o que o senhor gerencia no aplicativo, também pode ser gerenciado 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 estão disponíveis na página do Desenvolvedor.

Chaves de API

Ambas as plataformas realizam a autenticação por meio de uma chave de API. Na página “Desenvolvedor”, na seção “Chaves de API”, crie uma chave e selecione seu nível de acesso:

Somente leitura - listar webhooks, consultar o histórico de chamadas e as estatísticas.
Leitura e gravação - além de criar, atualizar e excluir webhooks.
Ler, gravar e executar - além de iniciar uma chamada de teste ou reproduzir uma chamada anterior.

A chave completa é exibida uma única vez, no momento da criação. Copie-a nesse momento e guarde-a em local seguro; você não poderá visualizá-la novamente. As chaves são armazenadas na forma de hash, nunca em texto simples, e você pode revogar uma chave a qualquer momento.

Envie a chave como um token “Bearer” em todas as solicitações:

text

Authorization: Bearer fwk_your_key_here

Por que a execução constitui um nível à parte

A ativação de um Webhook realmente executa seus fluxos de trabalho do Shopify Flow, e esses fluxos de trabalho podem alterar sua loja - adicionar tags aos pedidos, enviar e-mails, atualizar o estoque. Manter isso em um nível separado significa que uma chave que o senhor fornece a um script ou a um assistente de IA para tarefas cotidianas não poderá acionar suas automações acidentalmente. Conceda chaves de leitura por padrão e crie uma chave de execução apenas quando houver necessidade real.

URL base

A API e o servidor MCP são hospedados em um nome de host dedicado:

text

https://shopify.workflow-webhooks.app

Portanto, a API REST está disponível em https://shopify.workflow-webhooks.app/api/v1 e o servidor MCP em https://shopify.workflow-webhooks.app/api/mcp. A página “Desenvolvedor” exibe ambos com um botão “Copiar”.

Este nome de host serve apenas /api - a interface de administração incorporada permanece em sua própria URL registrada Shopify. Mantê-las separadas significa que o endereço que o(a) senhor(a) cola em um script, em uma tarefa de CI ou em um cliente de IA é estável e não está relacionado à incorporação do aplicativo.

API REST

A URL base é exibida na página do Desenvolvedor. Os principais endpoints:

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/webhooks`	ler	Listar webhooks
POST	`/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
EXCLUIR	`/api/v1/webhooks/:id`	escrever	Excluir um webhook
POST	`/api/v1/webhooks/:id/test`	executar	Execute uma chamada de teste
OBTER	`/api/v1/history`	ler	Invoções de lista
OBTER	`/api/v1/history/:id`	ler	Obter uma invocação, com seu payload
POST	`/api/v1/history/:id/replay`	executar	Reproduzir uma invocação anterior
OBTER	`/api/v1/stats`	ler	Totais, taxa de sucesso, séries diárias
OBTER	`/api/v1/templates`	ler	Modelos de webhook integrados

Uma verificação rápida para saber 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 seus webhooks durante uma conversa. Na página “Desenvolvedor”, a aba “MCP” exibe a URL do servidor e um comando de conexão pronto para ser copiado para cada cliente, com sua chave já inserida.

As ferramentas espelham os endpoints REST, e o conjunto de ferramentas reflete o nível da sua chave: uma chave somente leitura nem sequer tem acesso às ferramentas que criam, excluem ou acionam webhooks. Toda a autenticação e o tratamento de dados ocorrem no lado do servidor.

Como seus dados são protegidos

Há duas coisas que vale a pena saber antes de utilizar uma automação ou um assistente de IA com esta API.

O token de autenticação do seu webhook nunca pode ser lido. O token ou o segredo de assinatura que o(a) senhor(a) definir em um webhook não pode ser recuperado por meio da API ou do MCP em nenhum nível. As respostas informam apenas se um token está definido (hasToken), mas nunca seu valor. O(a) senhor(a) 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, frequentemente, contêm detalhes dos clientes. Antes que uma carga de invocação saia 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ão e campos cujos nomes remetem a uma pessoa (customerName, shippingAddress e similares). Os cabeçalhos de solicitação são sanitizados da mesma forma que a tela de histórico do aplicativo o faz.

Essa ocultação é cuidadosa, mas não constitui uma garantia. Ela atua sobre nomes de campos e padrões de valores; portanto, dados pessoais contidos em um campo de texto livre - uma nota, um comentário, o corpo de uma mensagem - ainda podem ser revelados. Trate as respostas da API como se pudessem conter dados de clientes e armazene-as de acordo com isso.

Os testes e as reproduções não consomem sua cota. As invocações que o senhor realiza por meio da API são registradas como testes; portanto, não são contabilizadas na cota mensal do seu plano. As reproduções também não são contabilizadas, pois a invocação original já foi contabilizada.

Próximos passos

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

Limites de taxa

A API REST e o servidor MCP compartilham um único limite de uso 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 utilizam ambos, de modo que um pico de chamadas de execução também consome a cota compartilhada. Para este aplicativo, isso significa invocar um webhook para fins de teste e reproduzir uma entrada do histórico, ações que, na verdade, executam seus fluxos de trabalho do Shopify Flow.
É o mesmo em todos os planos. Seu plano limita o número de invocações, e não de chamadas de API; portanto, a atualização não aumenta esses números.
A consulta retorna o código HTTP 429. Aguarde e tente novamente, de preferência com um intervalo de espera 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 recebidos não estão sujeitos a limites de frequência

Vale a pena deixar claro, pois essa é a pergunta que mais nos fazem: não limitamos o envio de webhooks recebidos. Nós os enviamos assim que chegam, independentemente dos picos de tráfego que seu sistema de origem produza - não há limite por segundo ou por minuto da nossa parte.

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

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: Limites de taxa da API do Shopify