Datos de la tienda para el bot

El bot de la IA en el chat puede responder no solo con la base de conocimiento, sino también con datos en vivo de la tienda: dónde está un pedido, cuál es su número de seguimiento, si un producto está disponible, cuánto cuesta el envío y cómo devolver una compra. Y, si usted lo permite, puede cancelar un pedido sin pagar o enviar a la tienda una solicitud de devolución o de cambio de envío. Para ello, la tienda se conecta al bot mediante el protocolo MCP (Model Context Protocol): el bot llama a las herramientas de la tienda y la tienda responde con datos.

La tienda se puede conectar en cualquier plan, pero el bot, como toda la IA del chat, funciona en un plan de pago: las respuestas con datos de la tienda se pagan como las respuestas normales de la IA, con el saldo del proyecto; consulte Pago.

Conexión

Lo más sencillo es usar nuestro plugin para la tienda. El plugin pone en marcha el servidor y lo conecta al proyecto al guardar los ajustes:

La clave secreta del plugin necesita el permiso «Conexión del servidor MCP de la tienda al bot de IA» (chats.manage). Los permisos de una clave no se pueden cambiar después de crearla: si la clave del plugin no lo tiene, cree en Claves de API una clave nueva con los mismos permisos más este e indíquela en los ajustes del plugin. Los sitios de un mismo proyecto se conectan una sola vez.

Una tienda propia en PHP o Laravel se conecta con el servidor listo de la biblioteca PHP y del paquete de Laravel: al desarrollador solo le queda escribir los manejadores de las herramientas. Cualquier otro servidor que cumpla el contrato MCP de la tienda se conecta manualmente: en Chats → Ajustes del chat → Bot → Tienda (MCP), indique la dirección https://…, la clave de acceso que emitió la tienda y un nombre. El contrato, con la descripción de las herramientas, los errores y la confirmación del cliente, está en la sección Para desarrolladores.

En la sección Tienda (MCP) se ve si el servidor funciona y qué herramientas ha permitido la tienda al bot. El interruptor desactiva el servidor temporalmente, y el botón de actualizar lo vuelve a comprobar y relee las herramientas (la plataforma también lo hace por sí misma una vez al día).

Qué puede hacer el bot

Lo que el bot tiene permitido lo decide la tienda, en los ajustes del plugin. De forma predeterminada, solo está activada la lectura:

Las acciones están desactivadas hasta que la tienda las permita:

Las descripciones de las herramientas para el modelo las define la plataforma, no la tienda, y el bot trata las respuestas de la tienda como datos, no como instrucciones. Si la respuesta del bot contiene precios, plazos o promesas que no figuran en los datos de la tienda, la comprobación de la respuesta no la deja llegar al cliente.

Confirmación del cliente

Los pedidos y las acciones con ellos solo están disponibles para un cliente confirmado: el bot no mostrará un pedido ajeno ni confirmará siquiera que existe. El cliente se puede confirmar de dos maneras:

1. Inicio de sesión en el sitio. Si el cliente ha iniciado sesión en su cuenta de la tienda, el plugin pasa al widget del chat un token firmado y el bot sabe de inmediato quién escribe.
2. Código. En los mensajeros y con los invitados, el bot pide el correo electrónico registrado en la tienda, la tienda envía a esa dirección un código de 6 dígitos y el cliente lo escribe en el chat. El código es válido durante 10 minutos, y no se envían más de 5 códigos por hora a una misma dirección.

La confirmación es válida durante 24 horas. El operador la ve en la ventana de la conversación: «cliente confirmado: inició sesión en el sitio» o «cliente confirmado con un código». El token del cliente se guarda cifrado en la conversación; ni el modelo ni los operadores lo ven.

Acciones en la tienda

El bot realiza una acción solo después de que el cliente dé su consentimiento expreso:

1. El bot describe lo que va a hacer, con el número de pedido y los artículos, y pide confirmación.
2. El cliente acepta en el chat, por ejemplo «sí, cancélelo».
3. Un modelo de valoración independiente comprueba que el cliente aceptó exactamente esa acción. Una pregunta, una duda u otra petición no es consentimiento.
4. La tienda realiza la acción; una nueva llamada a la misma acción no la repite.

En la conversación aparece la línea «El bot realizó en la tienda: …» con el resultado, y en el registro de auditoría del proyecto, la entrada «Acción del bot en la tienda». El borrador del operador usa los datos de la tienda solo para lectura: las acciones las realiza el propio operador, en la tienda.

Para desarrolladores

Un servidor propio se puede conectar si cumple la versión 1 del contrato MCP de la tienda. Para PHP y Laravel el contrato ya está implementado: la clase StoreMcp\Server de la biblioteca PHP y la ruta POST /onetrace/mcp del paquete de Laravel; solo queda escribir los manejadores de las herramientas.

Transporte. MCP Streamable HTTP, versión del protocolo 2025-06-18: una sola dirección, solicitudes POST con JSON-RPC 2.0; la respuesta es JSON o un flujo text/event-stream con una sola respuesta. La dirección debe ser https:// en una IP pública, sin redirecciones. La respuesta no debe tardar más de 10 segundos ni superar los 256 KB. La plataforma llama a initialize, notifications/initialized, tools/list y tools/call; el encabezado Mcp-Session-Id se admite, pero no es obligatorio.

Acceso. Cada solicitud lleva Authorization: Bearer <clave>; la clave la crea la tienda y debe tener al menos 32 caracteres aleatorios. Una solicitud sin clave o con una clave ajena recibe la respuesta 401.

Marca del contrato. En la respuesta a initialize, el servidor declara capabilities.experimental["onetrace/store"] = { "version": 1 }; sin ella, el servidor no se conecta.

Herramientas. Los nombres son exactamente los de la tabla, y tools/list devuelve solo las que el propietario ha permitido. Cada una tiene la anotación readOnlyHint: true (lectura) o destructiveHint: true (acción) y _meta["onetrace/auth"]: customer, se requiere un cliente confirmado; none, no se requiere. El resultado es structuredContent y el mismo JSON como texto en content[0].text. Los importes tienen la forma { "amount": 1250.5, "currency": "RUB" }, y las fechas, ISO 8601.

El estado del pedido es uno de pending, processing, on_hold, shipped, delivered, completed, cancelled, refunded, failed. El pedido de otro cliente recibe la respuesta not_found, como si no existiera.

Cliente. El token customer_token lo emite y lo comprueba la tienda, con una validez máxima de 24 horas. La tienda envía el código de confirmación por sí misma y responde igual tanto si el cliente existe como si no; el código tiene 6 dígitos, es válido durante 10 minutos, admite hasta 5 intentos y se envían hasta 5 códigos por hora a cada dirección. Para un cliente que ha iniciado sesión, la página pasa el token al rastreador: cdp.chatCustomer('…').

Contexto de la llamada: en params._meta, onetrace/customer_token, onetrace/language (idioma de la conversación), onetrace/conversation y, en las acciones, además onetrace/confirmed: true y onetrace/idempotency_key. El servidor rechaza una acción sin onetrace/confirmed; una repetición con la misma clave de idempotencia devuelve el mismo resultado sin repetir la acción.

Errores: isError: true y structuredContent: { "error": "<código>", "message": "<texto para el cliente>" }:

Conexión desde el plugin. El plugin registra su servidor con una clave secreta que tiene el permiso chats.manage: PUT /api/v1/chat/store-mcp con url, key, name, platform conecta o actualiza el servidor, y DELETE /api/v1/chat/store-mcp con url lo desconecta.