# DataFirefly MCP Commerce: guia completo

> O módulo DataFirefly MCP Commerce transforma a sua loja PrestaShop num servidor MCP (Model Context Protocol) que os agentes de IA (ChatGPT, Claude, Claude Desktop, Claude Code, n8n) podem consumir…

- Página: <https://www.datafirefly.com/pt/documentation/serveur-mcp-commerce-agentique/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/serveur-mcp-commerce-agentique/index.md), [en](https://www.datafirefly.com/en/documentation/serveur-mcp-commerce-agentique/index.md), [es](https://www.datafirefly.com/es/documentation/serveur-mcp-commerce-agentique/index.md), [de](https://www.datafirefly.com/de/documentation/serveur-mcp-commerce-agentique/index.md), [it](https://www.datafirefly.com/it/documentation/serveur-mcp-commerce-agentique/index.md), [pl](https://www.datafirefly.com/pl/documentation/serveur-mcp-commerce-agentique/index.md), [nl](https://www.datafirefly.com/nl/documentation/serveur-mcp-commerce-agentique/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

O módulo **DataFirefly MCP Commerce** transforma a sua loja PrestaShop num **servidor MCP** (Model Context Protocol) que os agentes de IA (ChatGPT, Claude, Claude Desktop, Claude Code, n8n) podem consumir diretamente para percorrer o catálogo, constituir carrinhos e preparar encomendas. Este guia cobre a instalação, o endpoint, a dupla autenticação (OAuth 2.1 e tokens Bearer), a ligação dos principais agentes, as ferramentas expostas, os scopes, os modos de encomenda e a resolução de problemas.

## Pré-requisitos

- PrestaShop 8.0 a 9.x.
- PHP 7.4 a 8.3 com a extensão cURL ativa.
- Uma loja servida em **HTTPS** (obrigatório para os conectores de IA).
- Recomendado: os **URL amigáveis** ativos (_Parâmetros avançados > SEO e URL_) para pontos de acesso limpos.

O módulo também funciona sem URL amigáveis: expõe então ligações de reserva baseadas em `index.php`, apresentadas no separador _Ligar um agente_ da configuração.

## Instalação

1. No back-office, abra _Módulos > Gestor de módulos_, depois _Carregar um módulo_ e envie o ficheiro `dfmcpcommerce.zip`.
2. Uma vez instalado, abra a configuração através do botão _Configurar_.
3. A instalação cria as tabelas técnicas (tokens, clientes OAuth, carrinhos, registo, limitador de débito) e ativa o servidor por defeito.

## O seu endpoint MCP

O URL do servidor MCP é apresentado no separador _Ligar um agente_. Com os URL amigáveis, tem este aspeto:

```
https://a-sua-loja.pt/mcp
```

É este URL que cola no conector do agente. O transporte é **Streamable HTTP** (JSON-RPC 2.0): um endpoint único, em POST.

## Autenticação: dois mecanismos

O módulo gere dois modos de autenticação em paralelo, consoante o cliente usado.

### OAuth 2.1: conectores web (Claude.ai, ChatGPT)

Os conectores web do Claude.ai e do ChatGPT **só aceitam OAuth**: nada de token colado, nada de token no URL. O módulo fornece um servidor de autorização OAuth 2.1 completo (authorization code + PKCE S256, metadados de recurso protegido e registo dinâmico de cliente). O agente declara-se sozinho e abre um ecrã de consentimento onde o cliente inicia sessão e aprova o acesso.

### Tokens Bearer: API, Desktop, CLI, n8n

Para a API Anthropic (conector MCP), Claude Desktop, Claude Code ou n8n, cria um **token Bearer estático** no separador _Tokens de acesso_ e passa-o no cabeçalho `Authorization: Bearer`.

Os tokens são apresentados **uma única vez** na criação e guardados em hash (SHA-256). Copie-o imediatamente; nunca mais será apresentado em claro.

## Ligar o Claude.ai ou o ChatGPT (web)

1. Mantenha o **OAuth 2.1** ativo no separador _Definições_.
2. No agente, adicione um conector personalizado e cole o URL do servidor MCP.
3. O agente descobre automaticamente a autenticação, regista-se e abre o ecrã de consentimento.
4. O cliente inicia sessão na sua conta da loja e aprova os scopes pedidos. Nenhum token a introduzir.

## Ligar a API Anthropic, Claude Desktop, Claude Code ou n8n

1. Abra o separador _Tokens de acesso_, escolha os scopes e clique em **Criar um token**.
2. Copie o token apresentado.
3. Configure o conector com o URL do servidor MCP e o cabeçalho `Authorization: Bearer O_SEU_TOKEN`.

## Scopes

Cada acesso é delimitado por scopes, pedidos pelo agente e concedidos no consentimento (OAuth) ou associados ao token (Bearer):

- `catalog:read`: pesquisa e fichas de produtos, categorias, informações da loja, transportadoras.
- `cart:write`: criação e gestão de carrinhos.
- `order:write`: preparação de encomenda.

## Ferramentas expostas

Estão disponíveis nove ferramentas. Cada uma pode ser ativada ou desativada individualmente no separador _Definições_, e está sujeita ao scope correspondente.

- `search_products`: pesquisa por palavra-chave, referência ou EAN, com filtros de categoria e preço.
- `get_product`: ficha detalhada de um produto (preço, stock, combinações, imagens).
- `list_categories`: árvore de categorias.
- `get_shop_info`: nome, idiomas, moedas e países servidos.
- `get_carriers`: transportadoras disponíveis.
- `create_cart`: criação de um carrinho.
- `add_to_cart`: adição de um produto ao carrinho.
- `view_cart`: conteúdo e totais do carrinho.
- `create_order`: finalização, consoante o modo de encomenda configurado.

Desative as ferramentas que não quer expor. Por exemplo, deixar apenas `catalog:read` e as suas ferramentas transforma o módulo num servidor de catálogo apenas de leitura para os agentes.

## Modos de encomenda

O separador _Definições_ propõe dois comportamentos para `create_order`.

### Modo transferência (por defeito)

O agente monta o carrinho e devolve depois um **URL de pagamento seguro**. Ao segui-lo, o cliente encontra exatamente esse carrinho na sua sessão e finaliza o pagamento no funil habitual do PrestaShop. Nenhum dado de pagamento passa pelo agente: **zero exposição PCI**.

### Modo encomenda

O agente cria diretamente uma encomenda **a aguardar pagamento**, no estado configurável (por defeito «Aguarda pagamento por transferência bancária»). Pensado para o B2B, o pagamento na entrega ou os orçamentos.

Em modo encomenda, a encomenda é criada sem pagamento cobrado. O pagamento é depois cobrado consoante o método associado ao estado de encomenda escolhido.

## Definições complementares

- **Exigir autenticação**: recomendado. Um pedido não autenticado aciona o fluxo OAuth (resposta 401 com cabeçalho `WWW-Authenticate`).
- **Leitura anónima do catálogo**: autoriza as chamadas `catalog:read` sem token, para expor um catálogo público.
- **Limite de débito**: número de pedidos por minuto e por IP (por defeito 120), em janela deslizante.
- **Registo** e **retenção**: regista cada pedido (método, ferramenta, estado, duração) no separador _Registo de atividade_, com um número de linhas conservadas configurável.

## Descoberta e pontos de acesso

Os agentes descobrem o servidor automaticamente. Os URL úteis estão listados no separador _Ligar um agente_:

- **Protected Resource Metadata** (RFC 9728): `/.well-known/oauth-protected-resource`.
- **Authorization Server Metadata** (RFC 8414): `/.well-known/oauth-authorization-server`.
- **Registo dinâmico de cliente** (RFC 7591), **autorização** e **token**: endpoints OAuth geridos pelo módulo.

Mesmo sem URL amigáveis, o cabeçalho `WWW-Authenticate` devolvido pelo endpoint aponta sempre para o URL de descoberta correto baseado em `index.php`: a ligação funciona em todos os casos.

## Segurança

- Todos os tokens são guardados **em hash SHA-256**, nunca em claro.
- PKCE S256 obrigatório, `redirect_uri` validados, códigos de autorização de uso único, rotação dos refresh tokens.
- Limitação de débito por IP e registo de atividade consultável.
- CORS gerido para os conectores web. Compatibilidade nativa com multiloja, multilingue e multimoeda.

## Resolução de problemas

- **O agente web não se liga**: verifique que a loja está em HTTPS e que o OAuth está ativo. Cole o URL `/mcp` (não uma página do back-office).
- **O cliente API devolve 401**: o token Bearer está ausente, revogado ou expirado. Crie um novo no separador _Tokens de acesso_ e verifique o cabeçalho `Authorization`.
- **Uma ferramenta não aparece**: provavelmente está desativada nas _Definições_, ou o scope correspondente não foi concedido.
- **Erro 429**: o limite de débito por IP foi atingido. Aumente o limiar nas _Definições_, se necessário.
- **A ligação de pagamento transferida expira**: as ligações de carrinho têm uma duração de vida limitada; peça ao agente para regenerar o carrinho.

## Desinstalação

A desinstalação elimina as tabelas do módulo (tokens, clientes OAuth, carrinhos, registo, limitador) e as suas variáveis de configuração. Os seus produtos, clientes e encomendas não são afetados. Para uma simples atualização, basta substituir os ficheiros: o esquema e os tokens existentes são preservados.