# Módulo ChatGPT Checkout PrestaShop (ACP): instalação e configuração
> Guia completo de instalação e configuração do módulo ChatGPT Checkout (ACP) para PrestaShop 8 e 9: chave de API, assinatura, endpoints, pagamento delegado Stripe e webhooks.
- Página:
- Idioma: pt
- Atualizado em: 2026-09-09
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/chatgpt-checkout-acp/index.md), [en](https://www.datafirefly.com/en/documentation/chatgpt-checkout-acp/index.md), [es](https://www.datafirefly.com/es/documentation/chatgpt-checkout-acp/index.md), [de](https://www.datafirefly.com/de/documentation/chatgpt-checkout-acp/index.md), [it](https://www.datafirefly.com/it/documentation/chatgpt-checkout-acp/index.md), [pl](https://www.datafirefly.com/pl/documentation/chatgpt-checkout-acp/index.md), [nl](https://www.datafirefly.com/nl/documentation/chatgpt-checkout-acp/index.md)
- Índice:
Este módulo transforma a sua loja PrestaShop num backend de comércio agêntico conforme ao **Agentic Commerce Protocol (ACP)**, o padrão aberto promovido pela OpenAI e pela Stripe. Um agente de IA (ChatGPT, Claude, Perplexity) pode descobrir os seus produtos através de um fluxo autenticado, criar uma sessão de pagamento e concluir depois a compra, o que cria uma encomenda real do PrestaShop na sua loja.
## Pré-requisitos
- PrestaShop 8.0 a 9.x (compatível com multiloja).
- Loja servida em **HTTPS** (o protocolo exige-o, e os endpoints impõem o SSL).
- **URL simplificados** ativos (SEO e URL → Reescrita de URL): os caminhos REST dependem disso.
- Uma conta Stripe, se quiser ativar o pagamento delegado (opcional).
Sem os URL simplificados, caminhos como `/acp/checkout_sessions` não são resolvidos. Enquanto a reescrita de URL não estiver ativa, aparece um aviso na configuração do módulo.
## Instalação
1. Back-office → **Módulos** → _Carregar um módulo_, e selecione depois o arquivo `dfaiagent.zip`.
2. Ative os **URL simplificados**, se ainda não estiverem.
3. Abra a configuração do módulo: copie o **URL de base** e a **chave de API** para a integração na plataforma agêntica.
## Configuração
### Chave de API (Bearer)
É gerada uma chave de API na instalação. Os agentes autenticam-se com o cabeçalho `Authorization: Bearer A_SUA_CHAVE_API`. Pode gerar uma nova chave a qualquer momento no painel; a anterior deixa de funcionar de imediato.
### Slug do URL de base
Segmento de caminho dos endpoints (por predefinição, `acp`). O URL de base fica então parecido com `https://a-sua-loja.pt/acp`.
### Verificação de assinatura
Se estiver ativa, o módulo verifica o cabeçalho `Signature`: um HMAC-SHA256 do corpo em bruto do pedido, codificado em base64 e calculado com o segredo partilhado fornecido pela plataforma agêntica.
### Webhooks de encomenda
Preencha o **URL de webhook** da plataforma e um **segredo de assinatura**. Na criação da encomenda, é enviado um evento `order_created`, assinado através do cabeçalho `DataFirefly-Signature`.
### Pagamento delegado Stripe (opcional)
Se a opção «Debitar através da Stripe» estiver ativa e existir uma chave secreta Stripe preenchida, o _shared payment token_ recebido na conclusão é debitado através de um PaymentIntent confirmado da Stripe, antes da criação da encomenda.
### Estados da encomenda
Escolha o estado inicial (encomenda criada sem débito pelo módulo) e o estado de «paga» (débito Stripe bem-sucedido).
**Enquadramento em Portugal.** Uma encomenda criada por um agente de IA é uma venda como qualquer outra: a fatura tem de ser emitida pelo seu software de faturação certificado pela AT, com ATCUD e assinatura. Confirme que o seu fluxo habitual (exportação para o software certificado, ou módulo de faturação) trata também as encomendas que chegam por esta via, e não apenas as do checkout normal, porque estas entram no PrestaShop sem passar pelo front-office.
## Pontos de terminação (endpoints)
Com o slug predefinido `acp`:
- `POST /acp/checkout_sessions`: criar uma sessão
- `POST /acp/checkout_sessions/{id}`: atualizar (artigos, morada, opção de entrega)
- `GET /acp/checkout_sessions/{id}`: consultar o estado atual
- `POST /acp/checkout_sessions/{id}/complete`: concluir e criar a encomenda
- `POST /acp/checkout_sessions/{id}/cancel`: cancelar
- `GET /acp/feed?page=1&limit=200`: fluxo de catálogo
### Criar uma sessão
```
curl -X POST "https://a-sua-loja.pt/acp/checkout_sessions" -H "Authorization: Bearer A_SUA_CHAVE_API" -H "Content-Type: application/json" -d '{ "items": [ { "id": "42", "quantity": 1 } ] }'
```
A resposta devolve o estado completo do carrinho: `line_items`, `totals`, `fulfillment_options`, `currency` e `status`. Os montantes vêm em **unidades menores** (cêntimos).
### Atualizar (morada, entrega)
```
curl -X POST "https://a-sua-loja.pt/acp/checkout_sessions/cs_XXXX" -H "Authorization: Bearer A_SUA_CHAVE_API" -H "Content-Type: application/json" -d '{ "fulfillment_option_id": "ship_2" }'
```
### Concluir
```
curl -X POST "https://a-sua-loja.pt/acp/checkout_sessions/cs_XXXX/complete" -H "Authorization: Bearer A_SUA_CHAVE_API" -H "Content-Type: application/json" -d '{ "buyer": { "name": "Maria Santos", "email": "maria@exemplo.pt" }, "payment_data": { "token": "spt_123", "provider": "stripe" } }'
```
Em caso de sucesso, é criada uma encomenda do PrestaShop e a resposta contém um objeto `order` (id e ligação permanente).
O objeto `buyer` traz o nome e o e-mail do comprador, mas não um NIF. Se os seus clientes pedem habitualmente fatura com contribuinte, previna que uma encomenda vinda de um agente chega sem esse dado: preveja um pedido posterior por e-mail, ou trate estas encomendas como consumidor final na emissão do documento certificado.
## Autenticação e assinatura
Cada pedido tem de levar o cabeçalho `Authorization: Bearer` com a chave de API. Se a verificação de assinatura estiver ativa, o módulo recalcula o HMAC-SHA256 do corpo e compara-o com o cabeçalho `Signature`, numa comparação em tempo constante. Os cabeçalhos `Idempotency-Key` e `Request-Id` são devolvidos na resposta.
## Codificação dos identificadores de artigo
O `item.id` do ACP segue o formato `{id_produto}` ou `{id_produto}-{id_combinacao}`. Por exemplo, `42` para um produto simples e `42-7` para a combinação 7 do produto 42. A mesma codificação é usada no fluxo de catálogo.
## Fluxo de catálogo
O endpoint `GET /acp/feed` (autenticado) expõe os seus produtos ativos e as respetivas combinações, com `price`, `availability`, `inventory_quantity` e `enable_checkout`. Use `page` e `limit` para a paginação.
O fluxo expõe o catálogo no idioma e na moeda da loja em contexto. Numa loja com português ativo, confirme que os nomes e as descrições estão mesmo preenchidos em português antes de abrir o fluxo a um agente: é o texto português que o agente vai ler e citar ao comprador.
## Pagamento delegado Stripe
Antes de passar a produção, verifique os nomes dos campos da Stripe para «agentic payments» face à configuração da sua conta (método `chargeStripe` em `classes/DfAiAgentOrder`). O pagamento continua opcional: sem débito pelo módulo, a encomenda é criada no estado inicial e capturada pelo seu PSP.
Se os seus clientes portugueses pagam sobretudo por Multibanco ou MB WAY, note que este fluxo assenta na Stripe e no cartão: um agente não gera uma referência Multibanco. Mantenha o pagamento delegado desativado e deixe a captura ao seu PSP habitual se quiser conservar esses meios de pagamento.
## Webhooks de encomenda
Na criação da encomenda, o módulo envia um evento `order_created` para o URL configurado, com um estado ACP derivado do estado da encomenda no PrestaShop (`created`, `confirmed`, `shipped`, `fulfilled`, `canceled`). A carga útil é assinada por HMAC.
## Ligar uma plataforma agêntica
Comunique à plataforma (por exemplo, na integração do ChatGPT Instant Checkout) o **URL de base**, a **chave de API** e, se for preciso, o segredo de assinatura e o URL e segredo do webhook. Como continua a ser o comerciante de referência, mantém o controlo sobre o stock, os preços, os impostos e o pagamento.
Continuar a ser o comerciante de referência significa também continuar a ser o responsável perante o consumidor: o direito de livre resolução de 14 dias do Decreto-Lei n.º 24/2014 e a garantia legal de 3 anos do Decreto-Lei n.º 84/2021 aplicam-se a uma encomenda feita por um agente exatamente como a qualquer outra venda à distância. Confirme que as informações pré-contratuais que a plataforma agêntica mostra ao comprador correspondem às suas condições reais.
## Resolução de problemas
### Os endpoints devolvem uma página 404 ou HTML
Ative os URL simplificados e limpe a cache do PrestaShop. Confirme que o slug de base corresponde mesmo ao URL transmitido à plataforma.
### Resposta 401
A chave de API está ausente ou errada no cabeçalho `Authorization`, ou a assinatura não corresponde ao segredo configurado.
### A encomenda não é criada
Confirme que são fornecidas uma morada de entrega válida e uma opção de entrega, que há stock suficiente e, se o débito pela Stripe estiver ativo, que a chave secreta da Stripe está correta.