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

Liga a loja a um ERP, a uma folha de cálculo, a uma automação ou ao Claude com uma app personalizada, um token de acesso e avisos automáticos (webhooks).

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.

> **Importante — Só o proprietário**
> Apps, tokens e webhooks só podem ser geridos pelo proprietário da loja.

## Criar uma app personalizada

1. Abre **Definições → Apps e API**.
2. Em **Apps personalizadas**, carrega em **Criar app**.
3. Em **Nome da app**, escreve de onde vêm os pedidos (ex.: "ERP", "Zapier", "Claude").
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. Cria a app. Aparece o **Token de acesso (Admin API e MCP)** e o **Segredo para validar webhooks**.
6. **Copia o token agora**: por segurança não o voltamos a mostrar. Depois carrega em **Já copiei**.

*(Captura do painel: Definições → Apps e API: apps personalizadas e API de administração)*

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.

> **Aviso — Cuidado com o token**
> Nunca o ponhas num site público, num email ou numa mensagem. Se achas que alguém o viu, gera um novo token ou revoga a app imediatamente.

## 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:

| Plano | Pedidos por segundo | Picos até |
|---|---|---|
| Essencial | 2 | 40 |
| Pro | 4 | 80 |
| Avançado | 10 | 200 |

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. Em **Webhooks**, carrega em **Adicionar webhook**.
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. 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. Em **Assinado com o segredo de**, escolhe a app. Os avisos de uma app deixam de ser enviados se a revogares.
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. Cria uma app chamada, por exemplo, "Claude", com as permissões que lhe queres dar, e copia o token.
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. **Claude Code:** copia o comando do bloco **Claude Code** e corre-o no terminal.
4. Se o token já não aparecer no bloco, substitui `fta_O_TEU_TOKEN` pelo token da app.

*(Captura do painel: O cartão "Ligar ao Claude" com as instruções e o endereço do MCP de administração)*

> **Dica — Começa só com leitura**
> Para experimentar, dá ao token do Claude apenas permissões de **Ler**. Quando estiveres confortável, acrescenta **Escrever** nas áreas que queres que ele altere.

## Problemas frequentes

| Problema | O que fazer |
|---|---|
| O programa recebe "não autorizado" | O token está errado, foi substituído por um novo ou a app foi revogada. |
| O programa recebe "sem permissão" | Falta a permissão dessa área. Edita as **Permissões** da app. |
| Um webhook aparece como "Falhou" | Confirma o endereço e se o servidor de destino responde; depois usa **Reenviar**. |