Conecta tu tienda Shopify a Clione
Planes: Starter ✓ · Growth ✓ · Pro ✓ · Agency ✓
Tiempo requerido: ~5–10 minutos (incluyendo el paso del theme app extension).
Necesitas: acceso al admin de Shopify como propietario de la tienda O como miembro del staff con permiso para desarrollar apps. La capacidad "Develop apps" viene desactivada por defecto para cuentas de staff — si no ves el menú en el paso 1.4 de abajo, pide al propietario que la active en Settings → Users → permissions antes de continuar.
Esta es la guía completa de extremo a extremo para darle a Clione el acceso que necesita para leer tu catálogo Shopify, enriquecerlo, propagar los resultados y renderizar el JSON-LD de Clione en el storefront. Está escrita pensando en merchants no técnicos — cada ruta de UI está descrita exactamente como aparece en el admin de Shopify, cada nombre de campo es el que realmente verás, y cada scope está explicado.
Clione nunca ve datos de clientes, pedidos, información de pagos, datos de fulfillment, inventario, localizaciones, draft orders, gift cards ni ningún PII. Los scopes de abajo dan acceso únicamente a tu catálogo de productos, páginas de contenido, metafields y archivos de tema.
Si estás conectando BigCommerce en su lugar, consulta Conectar BigCommerce.
¿Por qué una Custom App y no la app pública?
Clione no envía actualmente una App pública de Shopify a la Shopify App Store, así que la conexión se hace mediante una Custom App que creas dentro de tu propia tienda. Esto tiene tres ventajas concretas frente a un flujo OAuth con app pública:
- Inmediato. Sin cola de revisión de apps, sin aprobaciones pendientes. La conexión está activa en el momento que pulsas "Install app".
- Scope reducido. Una app pública pediría la unión de cada scope que cualquier merchant pudiera necesitar. La Custom App que creas aquí pide solo los scopes que Clione realmente usa — ver Paso 3.
- Revocable desde tu admin con un clic. Desinstalar la Custom App invalida inmediatamente el access token. No necesitas esperar a que Clione retire nada.
El trade-off es un paso extra de configuración (crear la app). El resto de esta guía es ese paso, detallado.
Paso 1 — Abre la página de Custom Apps
- Entra en tu admin de Shopify:
https://<your-store>.myshopify.com/admin. - Desde abajo a la izquierda del sidebar, pulsa Settings.
- En el sidebar de Settings, pulsa Apps and sales channels.
- Arriba a la derecha, pulsa Develop apps.
- Si nunca lo has usado, Shopify muestra una pantalla intermedia: "Allow custom app development". Púlsala y confirma con Allow custom app development en el modal. Esto desbloquea la página; solo lo verás una vez por tienda.
- (captura: Shopify admin → Settings → Apps and sales channels → Develop apps → banner Allow custom app development)
- Pulsa Create an app arriba a la derecha.
Si Develop apps no aparece en la página, tu usuario no tiene la capacidad Custom App Development. El propietario de la tienda puede activarla en Settings → Users → [tu nombre] → Permissions → Develop apps.
Paso 2 — Nombra la app
En el diálogo Create app:
| Campo | Valor |
|---|---|
| App name | Clione AI (cualquier nombre vale; esta etiqueta se muestra en tu admin y en los logs de peticiones a la API, así que ponle algo reconocible). |
| App developer | Déjalo en el valor por defecto (tu usuario). |
Pulsa Create app. Aterrizas en la pantalla de detalle de la app, que tiene las pestañas Overview, Configuration y API credentials.
Paso 3 — Configura los scopes de la Admin API
En la pantalla de la app verás una tarjeta titulada Admin API integration. Pulsa Configure Admin API scopes dentro de ella.
Aparece una lista larga de scopes, agrupados por recurso. Marca los de abajo — deja todo lo demás desmarcado. El selector de scopes admite búsqueda: escribe el nombre del scope en la caja Filter para saltar a él.
Scopes requeridos
| Scope | Por qué lo necesita Clione |
|---|---|
read_products | Leer tus productos, variantes, opciones, vendors, product types y tags. Requerido para sync y enriquecimiento. |
write_products | Escribir los metafields enriquecidos metafields.global.title_tag, metafields.global.description_tag y el namespace de metafields de Clione (clione.jsonld, clione.faq). Requerido para la propagación. |
read_content | Leer tus pages de contenido (About, Contact, Shipping, etc. — no blog posts). |
write_content | Actualizar los metafields de esas pages para que el meta_title y meta_description enriquecidos se propaguen. |
read_themes | Detectar qué temas están instalados y si el theme app embed Clione JSON-LD está activado. El dashboard usa esto para la tarjeta de estado del Schema Injector. |
write_themes | Requerido solo si Clione debe poder instalar / desinstalar el theme app embed por ti en el futuro. Sin él, el embed se activa manualmente en el theme editor (Paso 6). Es seguro concederlo — Clione no modificará los archivos de tu tema. |
read_online_store_pages | Leer URLs y handles del storefront para que Clione apunte a la URL correcta al verificar. |
read_locales | Leer el idioma principal de la tienda y los adicionales para que el contenido enriquecido se genere en el locale correcto. |
Scopes de la Storefront API
Puedes dejar la tarjeta entera de Storefront API integration sin tocar. Clione no usa la Storefront API hoy.
Webhooks (opcional)
En Configuration → Webhooks, opcionalmente puedes suscribirte a products/update, products/delete, collections/update, collections/delete y pages/update para que el espejo del catálogo de Clione se mantenga sincronizado sin un re-sync manual. Esto no es necesario para conectar — siempre puedes lanzar un sync manualmente desde el dashboard. Si quieres montarlo más adelante, consulta Webhooks para desarrolladores.
Scopes que NO debes activar
Concederlos expondría datos que Clione nunca lee. Déjalos en None:
read_customers,write_customers,read_customer_addressesread_orders,write_orders,read_draft_orders,read_order_editsread_fulfillments,write_fulfillmentsread_inventory,write_inventory,read_locationsread_discounts,write_discounts,read_price_rules,read_gift_cardsread_shipping,read_checkouts,read_payment_methodsread_reports,read_analytics,read_marketing_events
Pulsa Save arriba a la derecha. Verás un banner breve confirmando que los scopes se han actualizado.
Paso 4 — Instala la app y captura las credenciales
Cambia a la pestaña API credentials arriba de la pantalla de la app.
- Pulsa Install app arriba a la derecha.
- Shopify muestra una confirmación listando los scopes que acabas de configurar. Pulsa Install para concederlos.
- La página recarga mostrando Access tokens. Bajo Admin API access token, pulsa Reveal token once.
- Aparece un token
shpat_.... Cópialo ahora — Shopify no volverá a mostrarlo nunca. Si cierras el modal sin copiar, tienes que Uninstall app e Install app otra vez para generar uno nuevo.
También verás (más abajo en la página):
- API key — identificador público de la app.
- API secret key — se usa solo si más adelante cambias a flujo OAuth. No es necesario para la conexión por Custom App.
Opcional: pega el token en un gestor de contraseñas (1Password, Bitwarden) para guardarlo. Trátalo igual que la contraseña de admin de Shopify — cualquiera con el token puede llamar a la Admin API contra tu tienda con los scopes que has concedido.
Paso 5 — Añade la tienda en el dashboard de Clione
- Entra a tu dashboard de Clione en app.clione.ai.
- Desde el sidebar de la izquierda, pulsa + Add Store (o abre
/stores/newdirectamente). Se abre el asistente de 3 pasos. - Paso 1 — Elige la plataforma: pulsa la tarjeta Shopify.
- Paso 2 — Datos de la tienda:
- Store name — cualquier cosa que te ayude a distinguir tiendas en el sidebar (p. ej.
EgoShoes EU,EgoShoes US). Es solo interno. - Shopify store URL — tu dominio
myshopify.com. Puedes pegar el nombre corto (egoshoes-eu) o el dominio completo (egoshoes-eu.myshopify.com); Clione normaliza ambos. No incluyashttps://ni ningún path. - Currency — la misma divisa que usa tu tienda Shopify. Esto rellena
priceCurrencyen el JSON-LD hasta que Clione lea multi-divisa desde Shopify Markets (previsto).
- Store name — cualquier cosa que te ayude a distinguir tiendas en el sidebar (p. ej.
- Pulsa Next.
- Paso 3 — Credenciales: pega el Admin API access token (
shpat_...) del Paso 4 en el campo Shopify Admin API access token. - Pulsa Create and Connect.
En segundos la tienda aparece en el sidebar de tu dashboard. Ábrela para ver el resumen. La tarjeta del Schema Injector mostrará el estado Theme App Extension (en lugar del estado de la Scripts API de BigCommerce — son diferentes; consulta Schema Injector).
Si saltas el Paso 6, el catálogo se sincroniza bien y los valores enriquecidos aterrizan en metafields, pero no aparecerá JSON-LD nunca en tu storefront, porque el metafield no se renderiza hasta que el theme embed está activo.
Paso 6 — Activa el theme app embed de Clione (requerido para JSON-LD)
Los metafields de Shopify son solo API por defecto — el storefront no los renderiza automáticamente. Clione escribe JSON-LD en el metafield clione.jsonld, pero el storefront solo lo renderiza si el theme app embed Clione JSON-LD está activado en tu tema activo.
Sin este paso, tu JSON-LD enriquecido es invisible para Google, Bing, ChatGPT, Perplexity y cualquier otro crawler. El metafield existe. Los crawlers no lo ven.
El bloque vive en apps/shopify-theme-extension/blocks/clione-jsonld.liquid en el código fuente de Clione y se envía junto con la Custom App que instalaste en el Paso 4. Activarlo es una operación de un clic en el theme editor:
- Shopify admin → Online Store (en el sidebar izquierdo) → Themes.
- Encuentra tu tema activo (el etiquetado como Current theme) → pulsa Customize.
- En el theme editor, pulsa el icono de pieza de puzzle (App embeds) en la columna izquierda. (captura: theme editor de Shopify, columna izquierda, pestaña App embeds abierta)
- Encuentra Clione JSON-LD en la lista. Activa el toggle.
- Pulsa Save arriba a la derecha.
El bloque apunta a <head>, así que el JSON-LD se renderiza server-side por Liquid en cada petición de página. No hay JavaScript involucrado y los crawlers lo ven en la primera petición, incluyendo crawlers tipo curl que no ejecutan JS.
Qué renderiza el bloque
El bloque es Liquid puro (sin scripts) y renderiza:
- JSON-LD de entidad por página — leído desde
product.metafields.clione.jsonld,collection.metafields.clione.jsonldopage.metafields.clione.jsonldsegún el tipo de página. - JSON-LD global Organization — leído desde
shop.metafields.clione.organization. Se renderiza en cada página. - JSON-LD global WebSite — leído desde
shop.metafields.clione.website. Se renderiza en cada página, incluye unSearchActionapuntando a la plantilla de URL/search?q=de Shopify.
Si el metafield de la entidad está vacío (porque la entidad aún no se ha enriquecido) el bloque no emite nada para esa entidad — ni un script tag vacío, ni markup roto. En cuanto enriqueces la entidad en Clione el metafield se rellena y el bloque empieza a renderizar en la siguiente petición.
Reactivación tras cambiar de tema
Los app embeds se guardan por tema, no por tienda. Si cambias a un tema nuevo, duplicas el actual o trabajas en un tema de desarrollo, debes activar Clione JSON-LD en cada uno por separado. Lo mismo aplica tras una actualización de un tema de terceros que resetea los app embeds — vuelve a abrir el theme editor y actívalo de nuevo.
Qué NO requiere el theme embed
| Señal | ¿Necesita theme embed? |
|---|---|
<title> (meta_title) | No — Shopify renderiza global.title_tag nativamente vía {{ page_title }} en theme.liquid. |
<meta name="description"> | No — igual; usa global.description_tag. |
<link rel="canonical"> | No — Shopify lo genera desde la URL canónica del producto. |
| Product / Collection / Page JSON-LD | Sí. |
| FAQPage JSON-LD | Opcional — el widget de FAQ inyecta FAQPage JSON-LD en cliente; si quieres el schema de FAQ renderizado en server, usa el flujo del theme embed más el snippet Liquid de FAQ documentado en Instalación del widget de FAQ — Shopify. |
| OG tags | Parcial — Shopify renderiza OG title/description por defecto desde global.title_tag / global.description_tag. Los campos OG específicos de Clione viajan junto al JSON-LD en el mismo namespace de metafields y requieren el embed. |
Comprobación rápida (opcional)
Si quieres verificar que el token funciona antes de pulsar Create and Connect, ejecuta esto en cualquier terminal (sustituye los dos placeholders por tus valores reales):
curl -s \
-H "X-Shopify-Access-Token: shpat_..." \
"https://<your-store>.myshopify.com/admin/api/2024-10/products.json?limit=1"
Esperado: una respuesta JSON con uno de tus productos. Si ves {"errors":"[API] Invalid API key or access token (unrecognized login or wrong password)"}, el token se ha copiado mal — vuelve a revelarlo y cópialo otra vez, sin espacios al principio o al final.
Resolución de problemas (específica de Shopify)
401 Unauthorized desde Clione — El access token se ha revocado (alguien desinstaló la Custom App), o se copió con espacios, o es el token de otra app. Vuelve a abrir la Custom App Clione AI → pestaña API credentials → pulsa Install app para generar un token nuevo, y luego pégalo en Store → Settings → Credentials en el dashboard de Clione.
403 Forbidden solo cuando Clione escribe metafields — Falta un scope write_*. Abre la app → Configuration → Admin API scopes → marca el scope write_* que falta (lo más común es write_products) → Save → vuelve a API credentials → Install app otra vez para conceder el scope adicional. Los tokens existentes no recogen automáticamente los scopes recién añadidos — tienes que reinstalar.
El theme app embed no aparece en App embeds — La causa más común es que el tema se instaló (o se editó por última vez) antes de instalar la Custom App. Reinstala la Custom App: Settings → Apps and sales channels → Develop apps → Clione AI → API credentials → Uninstall app, y luego Install app otra vez. Recarga el theme editor — Clione JSON-LD debería aparecer ahora bajo App embeds.
El JSON-LD no aparece en el código de la página tras activar el embed — Tres causas posibles:
- El producto aún no está enriquecido. Ábrelo en Clione → revisa la pestaña Enrichment → enriquece. Solo las entidades enriquecidas tienen el metafield
clione.jsonldno vacío, y el bloque Liquid no emite nada para metafields vacíos (intencional — mejor estar en silencio que renderizar<script type="application/ld+json"></script>). - Estás mirando un tema distinto. Shopify renderiza el tema activo por defecto pero una URL
?preview_theme_id=...renderiza otro. Asegúrate de que el embed está activado en el Current theme, no solo en un duplicado. - El metafield se escribió pero el storefront se está sirviendo desde caché de CDN. Haz hard refresh (
Ctrl/Cmd + Shift + R). El TTL de caché paramyshopify.comes ~60 segundos; los dominios personalizados dependen de tu DNS/CDN.
La meta description se ve truncada a 255 caracteres en el storefront — Límite conocido de la plataforma. El tipo de metafield single_line_text_field de Shopify se corta a 255 chars; Clione puede generar hasta 320. El dashboard muestra una advertencia cuando pasa y trunca por el final de frase. Para obtener los 320 chars completos, usa el modo headless de la API con @clione/seo y salta el espejo en metafields — consulta Headless en Hydrogen.
429 Too Many Requests durante el sync — La GraphQL Admin API de Shopify limita el rate por "coste", no por peticiones por segundo. Clione reintenta automáticamente con backoff consciente del coste, así que un catálogo de 5.000 productos puede tardar 5–10 minutos en sincronizar. El chip de progreso en la barra superior se actualiza en vivo; puedes salir de la página y volver.
El sync dice "shop not found" — La URL de la tienda en Store → Settings → General no coincide con el dominio myshopify.com para el que se emitió el token. Vuelve a comprobar el campo Shopify store URL — debe ser your-store.myshopify.com, no tu dominio personalizado.
Revocar el acceso
Si necesitas revocar el acceso de Clione:
- Shopify admin → Settings → Apps and sales channels → Develop apps.
- Abre la app Clione AI.
- Pulsa Uninstall app en la pestaña API credentials.
- Confirma.
En segundos, cada petición de Clione a tu tienda devuelve 401 y tu tienda deja de aparecer como sana en el dashboard de Clione. No se borran datos en ningún lado — puedes reinstalar la app en cualquier momento para generar un token nuevo y reanudar.
Si además quieres borrar la tienda de Clione (y eliminar los datos enriquecidos que tenemos), usa Danger zone → Schedule deletion en Store → Settings en el dashboard de Clione. Consulta Ajustes de la tienda para la ventana de gracia de 7 días.
Qué cambia en Shopify vs BigCommerce
Preguntas habituales de merchants que conectan su segunda plataforma:
| Aspecto | Shopify | BigCommerce |
|---|---|---|
| Tipo de token | Un único Admin API access token shpat_. | Access Token + Store Hash desde una API Account V2/V3. |
| Dónde se crea el token | Custom App dentro del admin de la tienda (Settings → Apps and sales channels → Develop apps). | Página de API Accounts (Settings → API Accounts → Create API Account). |
| JSON-LD en el storefront | Theme App Embed (Liquid server-side). | Schema Injector (BC Scripts API → <script src=...> en <head>). |
| Modelo de variantes | First-class: cada variante es un SKU separado con su propio precio/opciones. | Product Options + SKU generado; las variantes se derivan de las opciones. |
| Equivalente a category | Collections — manuales (tú eliges los productos) y smart (basadas en reglas). | Categories — estructura de árbol con parent IDs. |
| Multi-divisa | Shopify Markets (un producto, precios por mercado). Clione hoy lee la divisa por defecto; el enriquecimiento consciente de Markets está previsto. | BC Channels (un producto, precios por canal). Mismo estado. |
| Reviews nativos | Eliminados en 2023 — necesitas Judge.me / Yotpo / Loox / Stamped para rellenar los metafields reviews.*. | Customer Reviews nativos bajo Settings → Channels. |
| Longitud máxima de meta description | 255 chars (límite del tipo de metafield). | 65535 chars (sin límite práctico). |
| Velocidad de sync (por 1k entidades) | 60–120s (rate limit GraphQL basado en coste). | 30–60s (REST v3). |
Consulta Capacidades por plataforma para la matriz completa por señal.
Qué ocurre una vez Clione tiene el token
- Primer sync (1–10 minutos según el tamaño del catálogo). Clione descarga tus products, collections y pages. Sigue el progreso en el chip de la barra superior o en Sync en el sidebar de la tienda.
- Primer enriquecimiento (depende del cupo de tu plan). Desde cualquier listado (Products, Collections, Pages), selecciona hasta 5 entidades y pulsa Bulk enrich. Clione siempre pide confirmación antes de gastar créditos de enriquecimiento — no hay auto-enrich con el sync. Consulta Enriquece tu catálogo.
- Auto-propagación. En cuanto el enriquecimiento termina, las señales se empujan al storefront en segundo plano. No pulsas nada para esto.
- Verificación. Abre Verification en el sidebar de la tienda para confirmar que lo que hay en Clione coincide con lo que está en el storefront en vivo. Consulta Verifica las señales.
Si una escritura falla (p. ej. el tipo de metafield es incorrecto, una descripción supera los 255 chars, el theme embed está apagado y el JSON-LD es invisible), la página Verification mostrará un Warn amarillo o un Fail rojo con el diff exacto. Cada escritura queda registrada con valores antes/después en la pestaña Propagation de cada entidad.