Módulo ChatGPT Checkout PrestaShop (ACP): instalação e configuração
Exponha o seu catálogo e o seu processo de compra aos agentes de IA (ChatGPT, Claude, Perplexity) através do Agentic Commerce Protocol.
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
- Back-office → Módulos → Carregar um módulo, e selecione depois o arquivo
dfaiagent.zip. - Ative os URL simplificados, se ainda não estiverem.
- 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ãoPOST /acp/checkout_sessions/{id}: atualizar (artigos, morada, opção de entrega)GET /acp/checkout_sessions/{id}: consultar o estado atualPOST /acp/checkout_sessions/{id}/complete: concluir e criar a encomendaPOST /acp/checkout_sessions/{id}/cancel: cancelarGET /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.