Dados da loja para o bot

O bot da IA no chat pode responder não só com base na base de conhecimento, mas também com dados da loja em tempo real: onde está o pedido, qual é o código de rastreamento, se o produto está em estoque, quanto custa a entrega, como devolver uma compra. E, se você permitir, pode cancelar um pedido não pago ou enviar à loja uma solicitação de devolução ou de alteração da entrega. Para isso, a loja se conecta ao bot pelo protocolo MCP (Model Context Protocol): o bot chama as ferramentas da loja, e a loja responde com os dados.

A loja pode ser conectada em qualquer plano, mas o bot, como toda a IA no chat, funciona em plano pago: as respostas com dados da loja são cobradas como as respostas comuns da IA, com o saldo do projeto; veja Cobrança.

Conexão

O jeito mais simples é usar o nosso módulo para a loja. O módulo sobe o servidor sozinho e o conecta ao projeto quando você salva as configurações:

A chave secreta do módulo precisa da permissão “Conexão do servidor MCP da loja ao bot de IA” (chats.manage). As permissões de uma chave não podem ser alteradas depois da criação: se a chave do módulo não tiver essa permissão, crie na seção Chaves de API uma chave nova com as mesmas permissões e mais esta e informe-a nas configurações do módulo. Os sites de um mesmo projeto são conectados uma única vez.

Uma loja própria em PHP ou Laravel se conecta com o servidor pronto da biblioteca PHP e do pacote Laravel — o desenvolvedor só precisa escrever os handlers das ferramentas. Qualquer outro servidor que cumpra o contrato MCP da loja é conectado manualmente: em Chats → Configurações do chat → Bot → Loja (MCP), informe o endereço https://…, a chave de acesso emitida pela loja e um nome. O contrato, com a descrição das ferramentas, dos erros e da verificação do cliente, está na seção Para desenvolvedores.

Na seção Loja (MCP) você vê se o servidor está funcionando e quais ferramentas a loja liberou para o bot. A chave liga/desliga desativa o servidor temporariamente, e o botão de atualizar verifica o servidor de novo e relê as ferramentas (a plataforma também faz isso sozinha uma vez por dia).

O que o bot pode fazer

Quem decide o que o bot pode fazer é a loja, nas configurações do módulo. Por padrão, só a leitura vem ativada:

As ações ficam desativadas até que a loja as libere:

As descrições das ferramentas para o modelo são definidas pela plataforma, não pela loja, e o bot trata as respostas da loja como dados, não como instruções. Se a resposta do bot tiver preços, prazos ou promessas que não estão nos dados da loja, a verificação da resposta não a deixa chegar ao cliente.

Verificação do cliente

Os pedidos e as ações sobre eles ficam disponíveis apenas para um cliente verificado — o bot não mostra o pedido de outra pessoa nem confirma que ele existe. O cliente pode ser verificado de duas formas:

1. Login no site. Se o cliente entrou na conta da loja, o módulo passa ao widget do chat um token assinado — o bot já sabe quem está escrevendo.
2. Código. Nos mensageiros e para visitantes sem login, o bot pede o e-mail cadastrado na loja, a loja envia para ele um código de 6 dígitos e o cliente digita o código no chat. O código vale por 10 minutos, com no máximo 5 códigos por hora para o mesmo endereço.

A verificação vale por 24 horas. O operador a vê na janela da conversa: “cliente confirmado: entrou no site” ou “cliente confirmado com código”. O token do cliente fica armazenado criptografado na conversa; nem o modelo nem os operadores têm acesso a ele.

Ações na loja

O bot só executa uma ação depois do consentimento explícito do cliente:

1. O bot descreve o que vai fazer — número do pedido, itens — e pede confirmação.
2. O cliente concorda no chat, por exemplo, “sim, pode cancelar”.
3. Um modelo de avaliação separado verifica se o cliente concordou exatamente com essa ação. Uma pergunta, uma dúvida ou outro pedido não contam como consentimento.
4. A loja executa a ação; uma nova chamada da mesma ação não a repete.

Na conversa aparece a linha “O bot executou na loja: …” com o resultado e, no log de auditoria do projeto, o registro “Ação do bot na loja”. O rascunho do operador usa os dados da loja apenas para leitura: as ações o próprio operador executa, na loja.

Para desenvolvedores

Um servidor próprio pode ser conectado se cumprir a versão 1 do contrato MCP da loja. Para PHP e Laravel, o contrato já está implementado: a classe StoreMcp\Server da biblioteca PHP e a rota POST /onetrace/mcp do pacote Laravel — basta escrever os handlers das ferramentas.

Transporte. MCP Streamable HTTP, versão do protocolo 2025-06-18: um único endereço, requisições POST com JSON-RPC 2.0, resposta em JSON ou um fluxo text/event-stream com uma única resposta. O endereço deve ser https:// em um IP público, sem redirecionamentos. A resposta deve chegar em até 10 segundos e ter no máximo 256 KB. A plataforma chama initialize, notifications/initialized, tools/list e tools/call; o cabeçalho Mcp-Session-Id é suportado, mas não obrigatório.

Acesso. Toda requisição traz Authorization: Bearer <chave>; a chave é criada pela loja e tem pelo menos 32 caracteres aleatórios. Requisição sem chave ou com outra chave recebe a resposta 401.

Marca do contrato. Na resposta a initialize, o servidor declara capabilities.experimental["onetrace/store"] = { "version": 1 } — sem isso, o servidor não é conectado.

Ferramentas. Os nomes são exatamente os da tabela; tools/list retorna apenas as liberadas pelo dono da loja. Cada uma tem a anotação readOnlyHint: true (leitura) ou destructiveHint: true (ação) e _meta["onetrace/auth"]: customer exige cliente verificado, none não. O resultado é structuredContent, com o mesmo JSON como texto em content[0].text. Valores no formato { "amount": 1250.5, "currency": "RUB" }, datas em ISO 8601.

O status do pedido é um destes: pending, processing, on_hold, shipped, delivered, completed, cancelled, refunded, failed. Para o pedido de outro cliente, a resposta é not_found, como se ele não existisse.

Cliente. O token customer_token é emitido e verificado pela loja, com validade de no máximo 24 horas. A loja envia o código de confirmação por conta própria e responde da mesma forma, exista ou não esse cliente; o código tem 6 dígitos, vale por 10 minutos, com até 5 tentativas e até 5 códigos por hora por endereço. Para o cliente logado, a página passa o token ao rastreador: cdp.chatCustomer('…').

Contexto da chamada em params._meta: onetrace/customer_token, onetrace/language (idioma da conversa), onetrace/conversation e, nas ações, onetrace/confirmed: true e onetrace/idempotency_key. O servidor recusa uma ação sem onetrace/confirmed; uma repetição com a mesma chave de idempotência retorna o mesmo resultado sem repetir a ação.

Erros: isError: true e structuredContent: { "error": "<código>", "message": "<texto para o cliente>" }:

Conexão pelo módulo. O módulo registra o próprio servidor com uma chave secreta com a permissão chats.manage: PUT /api/v1/chat/store-mcp com url, key, name, platform conecta ou atualiza o servidor, e DELETE /api/v1/chat/store-mcp com url o desconecta.