Apps personalizadas, API, webhooks e ligar o Claude à loja

Precisas que outro programa fale com a tua loja — por exemplo, o ERP da empresa a atualizar o stock, uma folha de cálculo a ler as encomendas, ou o Claude a ajudar-te a gerir produtos? Para isso crias uma app personalizada. É uma ligação só da tua loja, que não passa pela Loja de apps.

Palavras que vais encontrar

• API: a porta de entrada para programas. Em vez de alguém carregar em botões no painel, um programa faz pedidos como "dá-me as encomendas de hoje".

• Token: uma chave secreta (começa por fta_) que identifica a tua app. Quem tiver o token pode fazer o que as permissões deixam — guarda-o como uma palavra-passe.

• Webhook: um aviso automático. Quando acontece algo na loja (uma encomenda paga, por exemplo), a Feitora envia os dados para um endereço teu.

• MCP de administração: a ligação que deixa o Claude usar a tua loja com as permissões do token.

Criar uma app personalizada

1. 1
   Passo 1:

   Abre Definições → Apps e API.

2. 2
   Passo 2:

   Em Apps personalizadas, carrega em Criar app.

3. 3
   Passo 3:

   Em Nome da app, escreve de onde vêm os pedidos (ex.: "ERP", "Zapier", "Claude").

4. 4
   Passo 4:

   Em Permissões, marca só o necessário: para cada área (Produtos e coleções, Encomendas, Clientes, Stock, Páginas e blog, Descontos, Subscrições, Análises) escolhe Ler ou Escrever. "Escrever" inclui "Ler".

5. 5
   Passo 5:

   Cria a app. Aparece o Token de acesso (Admin API e MCP) e o Segredo para validar webhooks.

6. 6
   Passo 6:

   Copia o token agora: por segurança não o voltamos a mostrar. Depois carrega em Já copiei.

12

Na lista de apps podes depois ver o Registo de pedidos, mudar as Permissões, Gerar novo token (o antigo deixa de funcionar) ou Revogar a app.

A API de administração

No cartão API de administração encontras o Endereço base da API da tua loja e o botão Documentação, com todas as operações explicadas (também em formato openapi.json, que muitos programas importam diretamente). O programa envia o token no cabeçalho Authorization: Bearer fta_….

Cada plano tem um ritmo máximo de pedidos:

Acima disso a API pede ao programa para esperar um pouco (resposta 429). Passa esta informação a quem fizer a integração.

Webhooks: avisos automáticos

1. 1
   Passo 1:

   Em Webhooks, carrega em Adicionar webhook.

2. 2
   Passo 2:

   Escolhe o Evento (por exemplo, Encomenda criada, Encomenda paga, Encomenda enviada, Reembolso criado, Produto atualizado, Stock alterado, Cliente criado ou eventos de subscrições).

3. 3
   Passo 3:

   Em URL que recebe o POST, cola o endereço que o teu programa indicou (em produção tem de começar por https://).

4. 4
   Passo 4:

   Em Assinado com o segredo de, escolhe a app. Os avisos de uma app deixam de ser enviados se a revogares.

5. 5
   Passo 5:

   Carrega em Criar e usa Enviar teste para confirmar que chega.

Cada aviso leva uma assinatura (cabeçalho X-Feitora-Hmac-Sha256) que o programa usa para confirmar que veio mesmo da tua loja. Se o destino falhar, a Feitora tenta de novo várias vezes ao longo de cerca de 24 horas. Em Entregas vês cada tentativa e podes Reenviar.

Ligar o Claude à tua loja

Com o cartão Ligar ao Claude podes gerir a loja a conversar no Claude Desktop ou no Claude Code — ele usa as ferramentas do MCP de administração com as permissões que deste ao token.

1. 1
   Passo 1:

   Cria uma app chamada, por exemplo, "Claude", com as permissões que lhe queres dar, e copia o token.

2. 2
   Passo 2:

   Claude Desktop: no Claude, abre Definições → Programador → Editar configuração, cola o bloco Claude Desktop no ficheiro claude_desktop_config.json e reinicia o Claude.

3. 3
   Passo 3:

   Claude Code: copia o comando do bloco Claude Code e corre-o no terminal.

4. 4
   Passo 4:

   Se o token já não aparecer no bloco, substitui fta_O_TEU_TOKEN pelo token da app.

1

Problemas frequentes