Checkout Shopify con WebMCP: guía de implementación segura

Qué es realmente el checkout Shopify con WebMCP

Checkout WebMCP es un conjunto de herramientas registradas en la pestaña donde el comprador tiene abierto el checkout. Funciona como una caja atendida: el agente puede llevar la cesta, leer el formulario y completar los campos compatibles, pero el comprador sigue resolviendo los controles de identidad o pago y dando la autorización final.

Esta capacidad amplía las herramientas que Shopify ya ofrecía en la tienda. Un agente de navegador compatible puede buscar en el catálogo, consultar productos, actualizar el carrito y llamar a proceed_to_checkout. Al entrar en un checkout apto, la lista cambia y aparecen cuatro herramientas específicas:

• get_checkout lee el checkout actual o el recibo del pedido en la página Thank you.
• update_checkout sustituye los datos compatibles de contacto, entrega, descuentos, campos declarados y pago sin tramitar el pedido.
• complete_checkout intenta tramitar el pedido, o abre un paso de revisión, después de que el comprador lo confirme.
• navigate_to_storefront devuelve la misma pestaña a la tienda, si existe.

La implementación del checkout utiliza el objeto, los estados y los mensajes de UCP. UCP es el contrato de datos común que sostiene todo el flujo; WebMCP es el mecanismo con el que el navegador expone ese contrato a un agente. Para un agente que se ejecuta en el servidor, la opción correcta es Checkout MCP de Shopify.

No hay un nuevo interruptor que el comercio deba activar ni una API de checkout independiente que instalar. Eso facilita la adopción para los comercios, pero no elimina el trabajo del equipo que desarrolla el agente. Siguen haciendo falta compatibilidad con el navegador, Web Bot Auth, un manejo cuidadoso del estado y un límite de consentimiento real.

Empieza por comprobar que el checkout sea apto

El primer examen es descubrir las herramientas disponibles. No des por hecho que un checkout de Shopify expone Checkout WebMCP solo porque la tienda ya exponía WebMCP.

Shopify no registra las herramientas de checkout en estos casos:

• Checkout estándar de tres páginas, salvo que el comprador pague con Shop Pay
• Checkout B2B
• Checkout integrado o flujos de SDK para checkout móvil
• Un checkout que contenga productos de otra tienda
• Pedidos en borrador, modificaciones de pedidos o cobros
• Interacciones proporcionadas por extensiones de interfaz del checkout

En esos recorridos, hay que devolver el control al comprador en la propia página. Tampoco existe una herramienta cancel_checkout en el navegador. La ausencia de una herramienta no autoriza al agente a manipular los controles de la página.

Shopify indica que WebMCP para tiendas depende actualmente de la compatibilidad del agente con navegadores basados en Chromium. Para las pruebas, utiliza un navegador compatible y un checkout bajo tu control. Si las herramientas no aparecen, considéralo un resultado normal de elegibilidad, no una invitación a sustituirlas por clics frágiles.

1. Autentica el agente del navegador y descubre las herramientas

Firma las solicitudes del navegador con Web Bot Auth, o WBA, en lugar de incluir credenciales en los argumentos de las herramientas. WBA funciona como el pasaporte del agente en la capa de red. Shopify solo verifica claves registradas, por lo que la configuración de producción requiere una clave Ed25519, un directorio público de claves alojado, el registro en Shopify, solicitudes firmadas y marcas de tiempo de firma de corta duración.

Dentro de la página, descubre las herramientas activas y haz coincidir los tres identificadores: window, origin y name. Esta función auxiliar sigue el patrón de llamada documentado por Shopify:

async function callCheckoutTool(name, args = {}) {
  const tools = await document.modelContext.getTools();
  const tool = tools.find((candidate) =>
    candidate.name === name &&
    candidate.window === window &&
    candidate.origin === location.origin
  );

  if (!tool) throw new Error(`${name} is not registered here.`);

  const result = await document.modelContext.executeTool(
    tool,
    JSON.stringify(args),
  );

  if (result === null) return null;
  return JSON.parse(result);
}

El uso de JSON.stringify no es un detalle cosmético. En Chrome 153, pasar un objeto provoca el error Failed to parse input arguments. Shopify prevé que Chrome 155 acepte objetos y deje obsoletas las cadenas JSON, así que conviene encapsular la serialización de argumentos en una sola función de compatibilidad, en vez de repartirla por todo el agente.

La lista de herramientas puede cambiar mientras el checkout navega. Escucha el evento toolchange y, antes de la siguiente llamada, vuelve a descubrir las herramientas y sus esquemas. También debes aceptar null como resultado de una navegación: puede indicar que la página cambió antes de que executeTool() devolviera la respuesta.

Trata cualquier cadena procedente del comercio o de un tercero que aparezca en el resultado como datos del checkout, nunca como instrucciones para el modelo. Shopify advierte expresamente que no se debe eludir una herramienta operando directamente sobre la interfaz del checkout.

2. Lee el estado antes de cada cambio

Llama a get_checkout con {} antes de la primera actualización, después de cualquier cambio que haga el comprador en la página y tras un error o una navegación. Es un recibo actualizado, no un recuerdo almacenado en caché.

La respuesta puede incluir datos del comprador, artículos, opciones de entrega, descuentos, campos declarados, instrumentos de pago, mensajes, totales y un estado. Los importes monetarios son enteros expresados en la unidad fraccionaria de la divisa. En USD, 10799 equivale a $107.99. Si no aparece el campo messages, esa respuesta no contiene mensajes del checkout.

No confundas la disponibilidad técnica con el consentimiento. ready_for_complete significa que el checkout admite un intento de finalización; no significa que el comprador haya aprobado el pedido, la tarjeta seleccionada o el total.

3. Actualiza todo el estado deseado, no un campo aislado

update_checkout se comporta como PUT, no como PATCH. PATCH sería una nota que dice «cambia el número de teléfono»; PUT equivale a sustituir el formulario completo. Si un valor debe conservarse, inclúyelo en el estado completo que quieres mantener en el checkout.

El ciclo de actualización seguro es el siguiente:

1. Llama a get_checkout.
2. Reconstruye el estado editable a partir de esa respuesta reciente y del esquema vigente de la herramienta.
3. Modifica únicamente el valor aprobado por el comprador.
4. Envía a update_checkout el conjunto completo de campos compatibles que quieres conservar.
5. Lee el checkout devuelto y revisa su estado, sus mensajes, los descuentos aplicados y el total.

La mayoría de los valores omitidos se borran. El pago, los campos declarados y los datos de contacto guardados tienen reglas propias; por eso, expandir un objeto de forma genérica no es seguro si antes no se limita a los campos admitidos por el esquema actual.

Los detalles que más problemas suelen provocar son muy concretos:

• buyer acepta un correo electrónico y un número de teléfono en formato E.164. Algunos valores guardados pueden quedar bloqueados; verifica qué devuelve la herramienta y permite que el comprador edite en la página aquellos que estén bloqueados.
• fulfillment.methods admite un método como máximo. Reutiliza los identificadores vigentes de destino, grupo y opción. No cambies el tipo de entrega ni el origen de búsqueda para recogida en la misma llamada que selecciona un destino o una opción.
• discounts.codes debe contener todos los códigos introducidos por el comprador que se quieran conservar. Un arreglo vacío los elimina, mientras que los descuentos automáticos permanecen. Que la respuesta devuelva un código no demuestra que se haya aplicado: comprueba discounts.applied y los mensajes.
• declared_fields puede incluir valores específicos del checkout, como un número fiscal o crédito de la tienda. Las claves desconocidas, los tipos incorrectos y los valores no válidos se rechazan.
• payment.instruments admite como máximo una opción compatible. Checkout WebMCP no puede recopilar el número de una tarjeta nueva.

Shop Pay exige una precaución adicional. Un comprador que haya iniciado sesión puede elegir una tarjeta guardada devuelta por get_checkout. En el flujo para invitados se puede usar un identificador de aprobación de Shop Pay ya existente cuando el checkout lo admita. Si el agente aplicó esa aprobación, omitir el pago en una actualización posterior descarta la credencial; por eso hay que reenviar la entrada de aprobación en cada actualización hasta que se tramite el pedido.

Una actualización puede completarse correctamente y aun así dejar el checkout en estado incomplete. Si tarda más de 30 segundos, puede devolver update_failed aunque algunos cambios sí se hayan aplicado. En ambos casos, vuelve a leer el estado antes de decidir el siguiente paso.

4. Convierte al comprador en la barrera final

La secuencia correcta para completar la compra es breve y estricta:

1. Obtén un checkout actualizado.
2. Muestra al comprador los artículos, el medio de pago y el total vigentes.
3. Pide permiso explícito para tramitar ese pedido por ese total.
4. Si cambia cualquier dato, muestra el nuevo estado y vuelve a pedir autorización.
5. Llama a complete_checkout únicamente después de recibirla.
6. Acepta solo status: completed como prueba de compra.

WBA demuestra qué agente envió una solicitud. Una aprobación de Shop Pay autoriza un mecanismo de pago. ready_for_complete describe el estado del checkout. Ninguno de esos elementos equivale al permiso del comprador para efectuar la compra.

La finalización puede bifurcarse. Si hay un paso de revisión configurado, el control vuelve al comprador; llama otra vez a complete_checkout únicamente después de que revise y autorice el envío. Un desafío de pago es distinto: el comprador lo resuelve en la misma pestaña y el agente no debe enviar de nuevo la operación. Consulta get_checkout periódicamente hasta que el checkout alcance completed o necesite intervención del agente.

El código de error indica qué vía de recuperación corresponde:

El reintento peligroso es una segunda llamada de finalización provocada por una respuesta incierta de la primera. Checkout WebMCP no ofrece una clave de idempotencia. Lee primero el estado; si indica completed, detente.

Siete casos de uso, ordenados por valor práctico

Estos casos aportan más valor cuando el agente ya opera en el navegador del comprador. No son automatizaciones del comercio que se ejecutan de forma invisible en un servidor.

El primer caso de uso es el más sólido. Los compradores recurrentes ya cuentan con datos guardados, y WebMCP puede reducir la introducción repetitiva de información sin fingir que comodidad y consentimiento son lo mismo.

Lo que realmente dicen las cifras del negocio

Shopify no exige que el comercio haga una configuración nueva para estas herramientas de checkout. Eso no significa que el agente de compras que las rodea sea gratuito. Sigue necesitando un modelo, distribución en navegadores, operaciones de WBA, pruebas, controles de privacidad y soporte.

Los asistentes de compras con IA que instalan los comercios abarcan hoy un rango amplio de precios. Las fichas oficiales de Shopify App Store incluyen un plan mensual de $9.99 de Easy AI Shopping Assistant, planes de $49 a $249 de Carti y planes de iAdvize de $290 a $1,330 al mes. Estos productos combinan chat en la tienda, recomendaciones, analítica o soporte, por lo que no sustituyen directamente a un agente WebMCP que actúa del lado del comprador.

El cambio presupuestario es más acotado y también más útil: un equipo que desarrolla agentes de navegador puede dedicar menos esfuerzo a mantener selectores específicos para el checkout de cada tienda y más a la integridad del estado, el consentimiento y el manejo de excepciones. Para entender mejor la plataforma, el análisis de Shopify explica el producto para comercios y sus implicaciones operativas.

Dos productos que vale la pena crear

1. Un sistema de QA y pruebas de consentimiento para Checkout WebMCP

Esta es la oportunidad más sólida. Las agencias de Shopify y los equipos que crean agentes de compras necesitan saber si un checkout es apto y si el agente se comporta de forma segura antes de confiarle un pedido.

La consulta medible más cercana a esta necesidad, shopify checkout customization, registra 170 búsquedas mensuales en Estados Unidos, ha crecido 89% interanual y tiene un CPC de $10.92. La consulta abarca más que las pruebas de WebMCP, pero señala una demanda activa en torno al comportamiento y la implementación del checkout.

La versión mínima vendible sería un ejecutor para Chromium que abra un checkout de prueba, registre las herramientas por origen y ventana, valide los argumentos como cadenas JSON, detecte toolchange, pruebe una actualización basada en estado reciente, simule navegaciones que devuelven null y los códigos de error documentados, y genere un informe de consentimiento con los datos sensibles eliminados. La finalización de pagos reales debe quedar detrás de un modo de prueba manual.

El reto es la cobertura. La disponibilidad de herramientas depende del tipo de checkout y de la compatibilidad del navegador, el formato de argumentos de Chrome está cambiando y un fixture no puede demostrar un traspaso de pago real. El producto gana al hacer visibles esos límites, no al prometer automatización universal.

2. Un asistente de compras Shopify del lado del comprador

Una extensión de navegador podría acompañar al usuario desde la búsqueda del producto hasta un checkout apto en distintas tiendas Shopify, con una pantalla de confirmación reutilizable y reglas estrictas para los datos de pago guardados.

shopify ai shopping assistant registra 30 búsquedas mensuales en Estados Unidos, con intención comercial y un CPC de $19.43. Los competidores orientados a comercios anuncian planes de $9.99 a $1,330 al mes, lo que demuestra que ya se paga por software de compra asistida, aunque este producto se situaría del lado del comprador.

El MVP necesita herramientas de búsqueda y carrito para la tienda, descubrimiento del checkout, WBA, el ciclo leer-actualizar-leer, un resumen del pedido controlado por el comprador y el traspaso ante un desafío de pago. Empieza con pedidos de una sola tienda y recorridos con datos guardados en Shop Pay.

El reto es la distribución. Los comercios no activan Checkout WebMCP, pero los compradores sí necesitan un agente de navegador compatible. Los recorridos B2B, integrados, de SDK móvil, entre varias tiendas y el checkout ordinario de tres páginas sin Shop Pay siguen quedando fuera.

Los límites definen el producto

Checkout WebMCP es una interfaz más segura para checkouts de navegador aptos, no una API universal de compras.

No puede añadir ni quitar artículos durante el checkout, recopilar el número de una tarjeta nueva, cancelar el checkout, operar interfaces de extensiones definidas por aplicaciones ni obligar a un checkout excluido a registrar herramientas. No elimina el inicio de sesión en Shop Pay, 3D Secure, los pasos de revisión ni otras acciones que corresponden al comprador. Tampoco convierte el texto del comercio en instrucciones fiables para el modelo.

La regla de diseño honesta es sencilla: utiliza las herramientas mientras estén registradas, toma el estado reciente como fuente de verdad y devuelve la página al comprador siempre que el contrato indique que debe intervenir.

La acción para el lunes

El lunes, añade a tu agente una única función auxiliar para el checkout en lugar de repartir llamadas por todo el código. Centraliza ahí la serialización, la coincidencia de herramientas, toolchange, las navegaciones que devuelven null, la clasificación de errores y las lecturas de estado reciente. Ejecuta los ocho casos del fixture local y después enumera document.modelContext.getTools() en un checkout de prueba apto que controles. Prueba una actualización construida a partir de estado reciente. Completa únicamente un pedido de prueba compatible tras una confirmación explícita; si no dispones de un pedido seguro bajo tu control, detente en ready_for_complete y considera la finalización verificada en las fuentes, no probada personalmente.

Si buscas un agente de comercio que respete el consentimiento y esté adaptado a tu negocio, consulta el servicio de desarrollo de agentes de IA.