Catálogo de Shopify Storefront y presupuestos de envío

Esta guía conecta la API GraphQL de Shopify Storefront con Answers. Abarca tanto la configuración de Shopify como los ajustes de WordPress. Empiece con una tienda de prueba y un perfil de conversación que no sea de producción.

Elija la conexión adecuada​

Conexión	Dónde configurarla	Finalidad
Catálogo UCP de Shopify, incluido el ajuste shopify-storefront-catalog	Configuración guiada de Answers / herramientas MCP aprobadas	Operaciones de catálogo revisadas que expone el servicio MCP remoto
Adaptador tipado de Shopify Storefront	Perfil de conversación → Tools → External REST read tools	Búsquedas GraphQL de Storefront fijas, lecturas exactas de productos y capacidades de la tienda
Consentimiento para presupuesto de envío	Ajuste independiente de envío del adaptador tipado	Preparar un formulario visible; crear un carrito para el presupuesto solo tras la confirmación del visitante

El nombre del ajuste UCP no significa que active el adaptador tipado. Añadir una conexión MCP no añade automáticamente consultas de inventario, permisos de carrito ni estimaciones de envío. El adaptador tipado usa una petición GraphQL definida en el código mediante HTTPS POST; el asistente no puede aportar GraphQL arbitrario ni cambiar el comercio.

Para la conexión UCP guiada y los enlaces a productos de WordPress, consulte Configuración de Answers. Si mantiene ambas conexiones activas, describa sus finalidades de forma distinta para que las consultas de inventario y envío usen las herramientas tipadas de Storefront. Evite dos herramientas de búsqueda de catálogo indistinguibles.

1. Prepare la tienda Shopify​

Confirme el dominio original your-store.myshopify.com en los ajustes de dominio de Shopify. El conector necesita ese nombre de host exacto, no el dominio personalizado de la tienda, una URL de administración ni una URL de producto.

Prepare productos representativos: productos publicados, variantes con nombre, precios para el mercado previsto, seguimiento de inventario cuando corresponda y un artículo deliberadamente no disponible. Publique los productos en el canal de ventas de la storefront/app correspondiente. Que estén disponibles en Online Store no demuestra que lo estén en otro canal. Shopify explica la publicación por canal y los permisos en Gestionar el canal Headless.

Elija una de las siguientes vías de aprovisionamiento. No necesita ambas apps para una misma conexión.

Vía A: Canal Headless de Shopify​

1. Con permisos de administración de apps y canales, instale el canal de ventas Headless de Shopify.
2. Abra el canal y cree una storefront para esta integración.
3. En esa storefront, abra Storefront API permissions → Edit, apruebe los accesos necesarios indicados abajo y guarde la configuración.
4. Encargue el aprovisionamiento seguro del token Storefront adecuado en el backend. El editor actual de AI Kit usa el tipo de token Storefront público, pero conserva su valor en el servidor. No pegue ningún token en el perfil de conversación.

Shopify proporciona tokens públicos y privados en este proceso. Sus cabeceras de autenticación son distintas; un token privado no puede sustituir a uno público en su campo. Consulte Primeros pasos con la API Storefront.

Vía B: Una app gestionada por un desarrollador​

1. En Dev Dashboard → Apps, cree una app y configure una versión con los permisos Storefront necesarios.
2. Publique la configuración, seleccione Install app en su tarjeta Installs y apruebe la instalación en la tienda prevista.
3. El operador de la integración debe autenticar la app mediante el flujo de instalación y autenticación admitido por Shopify. La autenticación client-credentials es para tiendas elegibles de la propia organización de la app; no sustituye de forma general la instalación OAuth de otro comercio.
4. Durante el aprovisionamiento, use la Admin API autenticada para crear un token de acceso Storefront y verificar sus permisos concedidos. Guarde solo ese token Storefront en el parámetro de ejecución del conector. Un token de Admin API, un client secret y un token Storefront son credenciales diferentes.
5. Si cambia los permisos, publique la configuración actualizada y solicite al comerciante que apruebe el nuevo acceso. Verifique los permisos de la instalación y el acceso del token utilizado en ejecución; cambiar el borrador de configuración de la app no basta.

Siga la guía de apps de Dev Dashboard de Shopify para la instalación y aprobación. La operación de aprovisionamiento se documenta en storefrontAccessTokenCreate. AI Kit no realiza estas operaciones administrativas por usted. No sustituya el proceso actual de Shopify por un antiguo tutorial para crear una app privada.

Permisos necesarios​

Permiso Storefront	Necesario para
unauthenticated_read_product_listings	Productos, colecciones y variantes de las consultas de catálogo
unauthenticated_read_product_inventory	Cantidad devuelta de la variante usada en las condiciones de cantidad
unauthenticated_read_product_tags	Etiquetas de producto devueltas y verificadas por este adaptador
unauthenticated_read_checkouts	Lecturas opcionales del carrito de presupuesto
unauthenticated_write_checkouts	Creación opcional y expresamente confirmada del carrito de presupuesto

Los tres primeros corresponden al catálogo. Añada los dos últimos solo cuando el propietario active explícitamente los presupuestos de envío. Los permisos de Shopify cuyo nombre contiene checkout cubren la Cart API y son más amplios que el uso limitado de esta integración; no son permisos exclusivos para presupuestos. La integración no hace pedidos ni paga. Revise los permisos instalados con la referencia de permisos Storefront de Shopify.

2. Prepare los filtros y los datos de origen​

Instale o abra Search & Discovery de Shopify y configure los filtros de storefront que quiera usar. Disponibilidad y precio son filtros predeterminados; proveedor, tipo de producto, etiquetas y opciones de variante requieren la configuración correspondiente en la tienda. Use nombres y valores reales, como Color e Ice, en lugar de deducir un color a partir de la fotografía. Consulte la guía de configuración de filtros de Shopify.

El adaptador envía a Shopify los filtros compatibles de precio, disponibilidad, proveedor, tipo de producto, etiqueta y opción de variante. El código del backend también valida los datos devueltos: las condiciones combinadas de precio, disponibilidad, opción y cantidad deben cumplirse en la misma variante. Una variante barata y otra con mucho inventario no pueden combinarse en una oferta coincidente ficticia.

El ProductFilter de Shopify Storefront no ofrece una condición de inventario mínimo. Por eso el backend comprueba minQuantity de forma determinista con el inventario de variantes devuelto, sin pedir al modelo que filtre una página. No trate la sintaxis de búsqueda de Admin API como si fuera compatible con Storefront.

El campo nullable quantityAvailable representa la cantidad vendible de una variante en los canales en línea, no una garantía de inventario por almacén. Una cantidad desconocida no equivale a cero; «disponible para la venta» no es una cantidad exacta ni una promesa de entrega. Para condiciones de valoración, el adaptador lee el metacampo compatible reviews.rating cuando está disponible. Las valoraciones ausentes o inaccesibles siguen siendo desconocidas; configurar un filtro no crea datos de producto.

Páginas lógicas completas con Deployment Access v1.0.130​

Con la plantilla Deployment Access v1.0.129, la validación del backend opera sobre una página del proveedor. Las condiciones locales pueden dejar menos coincidencias visibles que el tamaño de página solicitado, aunque Shopify aún tenga más páginas de origen. Una página vacía tras el filtrado no demuestra que no existan coincidencias en todo el catálogo.

A partir de la plantilla Deployment Access v1.0.130, el adaptador crea una página lógica de coincidencias verificadas en el código del backend. Mantiene todos los filtros en las lecturas siguientes, completa el tamaño aprobado y busca una coincidencia verificada adicional antes de indicar que hay más resultados. La continuación parte del último producto mostrado, por lo que no se omiten silenciosamente los resultados adicionales ya leídos. Una última página más corta solo es válida tras agotar la búsqueda restante del proveedor.

Las búsquedas por palabras clave usan el orden de relevancia de Shopify; la navegación sin palabras clave usa el orden por precio. La búsqueda original y su orden siguen vinculados a cada continuación. La navegación anterior/siguiente no pide al modelo que vuelva a buscar ni que filtre tarjetas. El tamaño de página es el aprobado en la plantilla de visualización, no un recuento total. El asistente debe conservar los términos solicitados por el visitante; una palabra clave adicional inesperada puede limitar los resultados aunque la paginación funcione bien.

Es un trabajo acotado, no un recorrido ilimitado del catálogo: como máximo ocho peticiones al proveedor, un límite compartido de 15 segundos (o el plazo anterior de la operación superior) y límites de tamaño agregado de respuesta. Si esos límites, un inventario necesario desconocido, una cobertura incompleta de variantes o el máximo de búsqueda de Shopify impiden un resultado fiable, la operación indica búsqueda incompleta, no «sin coincidencias». Acote la búsqueda o corrija los datos ausentes antes de reintentar. Shopify limita cada búsqueda a 1.000 resultados; eso no demuestra que un catálogo mayor termine ahí. El recuento mostrado no es automáticamente el total de coincidencias del catálogo.

Si el visitante no solicita restringir por disponibilidad, el adaptador combina las particiones de búsqueda de disponibles y no disponibles sin añadir por su cuenta un filtro de productos que se puedan pedir. Un mínimo de existencias explícito sigue siendo una condición tipada independiente; una insignia «Available to order» no basta para cumplirlo.

3. Prepare la referencia del backend​

Pida al operador del backend que aprovisione de forma segura la credencial Storefront como parámetro de ejecución cifrado perteneciente a la app y dé acceso al entorno desplegado. El perfil acepta su nombre, por ejemplo /APPNAME/external-tools/storefront-token, no su contenido. APPNAME debe ser el prefijo real de la aplicación desplegada. Se rechaza un parámetro sin cifrar.

Nunca incluya valores de tokens en JSON del perfil, cabeceras fijas, archivos versionados, capturas, solicitudes de soporte ni chats. El navegador y el modelo no los necesitan. La rotación corresponde al procedimiento de gestión de secretos del operador; después, verifique una lectura mediante el despliegue previsto sin mostrar la credencial.

El editor actual de Storefront en WordPress fija la autenticación a X-Shopify-Storefront-Access-Token. El backend admite Shopify-Storefront-Private-Token, pero el editor no ofrece un selector de tipo de token. No pegue un token privado en la configuración del token público. Una integración privada gestionada por el operador necesita además una IP de visitante fiable procedente del contexto de petición del backend; no se admite una IP de relleno ni un argumento de herramienta enviado por el navegador. Shopify explica las distintas cabeceras en su referencia de autenticación Storefront.

4. Añada las herramientas tipadas en WordPress​

Abra SmartCloud → Answers → ajustes detallados → Conversation profile → Tools. En External REST read tools, añada una herramienta y seleccione Shopify Storefront (read only) como adaptador. Repita para cada operación necesaria:

ID de herramienta de ejemplo	Storefront read operation	Finalidad sugerida
shopify-products	Search products	Buscar productos con condiciones compatibles de precio, disponibilidad, cantidad y opciones
shopify-product	Get one product	Leer un ID exacto de producto Shopify previamente verificado y las variantes devueltas
shopify-capabilities	Read shop capabilities	Leer capacidades generales de la tienda sin prometer elegibilidad en un checkout concreto

Los IDs son ejemplos, no nombres obligatorios. Use IDs distintos y finalidades claras. Operaciones diferentes pueden compartir el endpoint de un comercio; no duplique una misma operación en ese endpoint.

Para cada herramienta:

1. Introduzca el Shopify shop domain original y elija la operación.
2. Introduzca el Storefront token SSM parameter name facilitado por el operador.
3. Compruebe el Derived Storefront endpoint de solo lectura: https://your-store.myshopify.com/api/2026-10/graphql.json. Este adaptador fija la versión 2026-10; el campo no permite editar libremente el endpoint ni la versión de API.
4. En Market and language, seleccione opcionalmente un código de país y un idioma publicado en Shopify. En blanco se usan los valores predeterminados de la tienda. El idioma no convierte monedas; precios y monedas devueltos siguen siendo hechos de la fuente. Mantenga consistentes los ajustes de mercado y credenciales de las tres herramientas.
5. Deje Offer separately confirmed shipping quotes desactivado hasta completar la revisión de consentimiento y permisos indicada más abajo.
6. Active las herramientas revisadas y pulse Save profile. Abrir o editar una herramienta solo cambia el borrador. Configure la finalidad del asistente para consultar datos actuales con estas herramientas, no para tratar los textos de producto de la base de conocimiento como inventario actual.

No hace falta un cuerpo GraphQL personalizado, un mapeo libre de parámetros de consulta ni un esquema de respuesta generado por el modelo. El adaptador tipado aporta su contrato aprobado de entrada y salida.

5. Configure las tarjetas verificadas y sus etiquetas​

En Display templates, active las vistas estructuradas y añada una plantilla vinculada a la fuente Storefront de lectura aprobada. Elija disposición y tamaño de página. Revise los mapeos de título, descripción, imagen, precio, cantidad y navegación con una muestra verificada de esa fuente. Los argumentos de vista previa son entradas para una lectura real aprobada, no un lugar donde pegar una respuesta de producto inventada. Use una búsqueda conocida o un ID de producto verificado, según la operación de la fuente seleccionada.

Aplique la plantilla al borrador y guarde el perfil de conversación. El backend construye las tarjetas con registros verificados. El asistente puede dar una introducción breve o una comparación fundamentada, pero no regenerar ni alterar precios, monedas, inventario, IDs ni datos de variantes de origen en las tarjetas.

Configure las etiquetas de tarjetas y paginación mediante el catálogo de traducciones compartido. Siguen el idioma de la interfaz del chatbot/sitio; la respuesta puede seguir el idioma de la pregunta. Si falta una traducción, se conserva la etiqueta de origen redactada. No hay un pase del modelo que traduzca todos los campos, nombres de producto o registros guardados.

Los formatos explícitos HTML/Markdown del contenido estructurado de WordPress replicado son una función aparte, no un permiso para mostrar HTML arbitrario de Shopify. Tras revisar los mapeos de formato y completar la sincronización, el HTML declarado se convierte por defecto en texto sin formato legible. Una plantilla de contenido estructurado puede activar por separado Allow safe rich-text formatting, que requiere display-policy versión 4 y wire versión 3 compatibles. Ese formato restringido no activa HTML sin procesar, enlaces ni imágenes dentro de una propiedad de texto. Los campos simples o sin marcar siguen siendo texto sin formato.

6. Active las estimaciones de envío confirmadas por separado​

Antes de activarlas, apruebe los dos permisos de carrito, verifique la configuración de envío del comercio y revise el aviso de privacidad del sitio. Explique que los datos de entrega se envían al comercio configurado y pasan por procesamiento privado en el backend, y que Shopify puede conservar el carrito según las políticas del comercio. No afirme que se elimina automáticamente al cerrar el chat.

Active Offer separately confirmed shipping quotes en las herramientas de catálogo cuyas variantes devueltas puedan usarse para presupuestos, en particular Search products y Get one product. Guarde el perfil. Esta opción no instala apps ni concede permisos Shopify. Activarla solo en una lectura de capacidades no proporciona variantes de producto.

El flujo previsto para el visitante es:

1. Solicita un presupuesto para un producto, una variante exacta y una cantidad.
2. El asistente lee datos actuales y resuelve la variante. Si hay ambigüedad, pide aclaración en lugar de adivinar.
3. El formulario Check shipping quote muestra los artículos verificados y solicita los datos de entrega. Prepararlo no crea un carrito ni calcula el envío.
4. Solo el envío explícito del formulario por el visitante autoriza crear el carrito temporal y consultar tarifas. No se selecciona ninguna opción, no se hace ningún pedido y no se realiza ningún pago.
5. El resultado muestra estimaciones, un estado pendiente/no disponible o un fallo. Una estimación pendiente de un carrito conocido puede actualizarse sin crear otro carrito. Si el resultado de la creación es incierto, el backend no repite a ciegas esa mutación.

Use el formulario, no el chat ordinario, para los datos de entrega. Los valores estructurados no entran en prompts del modelo, historial visible ni almacenamiento de conversaciones del navegador. Las referencias privadas del carrito permanecen en el servidor. Las propuestas caducan y están vinculadas a la conversación y al perfil revisado; inicie otra solicitud tras su caducidad o un cambio de perfil.

Las estimaciones Shopify dependen del carrito y destino concretos. Esta integración no promete una fecha de llegada ni determina medios de pago específicos de un checkout. Las marcas de tarjeta o monederos generalmente admitidos no prueban que puedan utilizarse en una compra concreta. Las opciones y totales pueden cambiar en el checkout; no sume la estimación de una opción al total mostrado del carrito para presentarlo como importe final a pagar. Consulte la Cart API y la creación de carritos de Shopify.

7. Verifique la experiencia completa​

Pruebe con sus propios registros Shopify conocidos, no con inventario supuesto:

• Busque un producto conocido y lea su variante exacta. Compare título, opción, importe, moneda y cantidad con el mismo mercado/canal en Shopify.
• Combine un precio máximo, una cantidad mínima y una opción de variante. Una variante debe cumplir todo; pruebe también un producto cuyas variantes diferentes cumplan condiciones individuales distintas.
• Compruebe anterior/siguiente, coincidencias dispersas, un producto realmente ausente y resultados explícitos de búsqueda incompleta con la plantilla Deployment Access v1.0.130. Incluya búsquedas por palabras clave con disponibilidad y cantidad mínima. No deduzca ausencia en todo el catálogo a partir de una sola página e inicie una búsqueda nueva después de actualizar el backend.
• Solicite un presupuesto de envío. El formulario visible debe aparecer antes de crear un carrito y abandonarlo no debe crear ninguno. Envíelo solo con un destino de prueba aprobado deliberadamente y pruebe después la actualización pendiente.
• Pruebe permisos ausentes, cantidades desconocidas y destinos no admitidos. No deben convertirse en inventario inventado, envío gratuito ni garantías.
• Pregunte en otro idioma sin cambiar el del sitio. Verifique por separado idioma de respuesta, etiquetas traducidas por catálogo y datos de producto de origen.

La demo puede probarse directamente en WordPress tras superar su protección de acceso. No requiere un frontend estático. En sitios exportados por separado, vuelva a publicar los recursos del frontend después de actualizar el plugin; las respuestas guardadas y exportaciones antiguas no se reescriben retroactivamente.

Resolución de problemas​

Síntoma	Qué comprobar
El asistente usa datos genéricos o dice que no puede comprobar el envío	Confirme que las herramientas tipadas estén activas en el perfil guardado, tengan finalidades distintas y que el consentimiento de envío esté habilitado en la fuente de la variante verificada. UCP por sí solo no basta. Revise la actividad de herramientas; una respuesta del modelo no demuestra una ejecución.
El token funciona en otro sitio, pero aquí falla	Compruebe tienda exacta, propiedad/tipo del parámetro de ejecución, permisos instalados y tipo de token. Los tokens Admin y Storefront privados no son intercambiables con el Storefront público configurado por la UI.
Falta un producto	Revise publicación por canal, disponibilidad de mercado, términos y filtros de Search & Discovery. Compare la misma fuente y mercado, no solo la página Online Store.
La cantidad disponible es desconocida	Verifique el permiso de inventario y el campo devuelto. El inventario ausente debe seguir siendo desconocido; la disponibilidad no demuestra diez unidades en stock.
Aparecen dos resultados en una página de tres y quedan páginas de origen	Puede ocurrir con la validación por página de la plantilla Deployment Access v1.0.129. Actualice la pila de Deployment Access a la plantilla v1.0.130 o posterior e inicie una búsqueda nueva; actualizar solo el plugin no activa el comportamiento completo de páginas lógicas del backend.
«Next results» falla después de actualizar	Inicie una búsqueda nueva en vez de reutilizar una continuación caducada o de un protocolo anterior. Si una petición nueva también falla, recopile su ID de correlación y el estado del backend sin datos sensibles; no oculte un ciclo de cursores del proveedor como resultado vacío.
La búsqueda es explícitamente incompleta	Acote la consulta o resuelva los datos necesarios ausentes. El recorrido limitado no pudo demostrar una página completa ni el agotamiento de resultados; no significa «sin resultados».
El presupuesto sigue pendiente o no disponible	Revise permisos de carrito, tarifas/destinos del comercio y estado del backend sin datos sensibles. Actualice solo el carrito pendiente conocido. No cree carritos repetidamente tras un resultado incierto.
Las etiquetas de las tarjetas y la respuesta tienen distinto idioma	Es normal si el idioma de la UI difiere del de la pregunta. Añada las etiquetas redactadas al catálogo compartido; sin traducción se mantiene la etiqueta de origen.
El cambio parece guardado, pero los visitantes ven el comportamiento anterior	Aplique los borradores anidados, guarde el perfil, confirme el backend/sitio previsto y vuelva a publicar los recursos estáticos cuando corresponda. Inicie una conversación de prueba nueva.

Para soporte, recopile identificador de despliegue/versión, ID y operación de la herramienta, revisión del perfil, hora, ID de correlación de la petición y categoría de fallo sin datos sensibles. No incluya credenciales, IDs privados de carrito ni direcciones de entrega en registros o capturas de diagnóstico.