Saltar al contenido principal

Conecta tu tienda BigCommerce a Clione

Planes: Starter ✓ · Growth ✓ · Pro ✓ · Agency ✓

Tiempo requerido: ~5–10 minutos (incluyendo el paso del Schema Injector si estás en Stencil).

Necesitas: acceso al admin de BigCommerce como propietario de la tienda, O como usuario con el permiso "Manage API Accounts". Si no ves Settings → API Accounts en el sidebar del admin, a tu usuario le falta ese permiso — pide al propietario que lo añada vía Settings → Users → [tu nombre] → Permissions.

Esta es la guía completa de extremo a extremo para darle a Clione el acceso que necesita para leer tu catálogo de BigCommerce, enriquecerlo, propagar las señales optimizadas de vuelta e instalar el Schema Injector de JSON-LD en tu storefront. Está escrita para merchants no técnicos — cada ruta de UI está descrita, cada nombre de campo es el que realmente verás en el admin de BC, y cada scope está explicado.

Clione nunca ve datos de clientes, pedidos, información de pagos, datos de fulfillment, inventario ni ningún PII. Los scopes de abajo dan acceso únicamente a tu catálogo de productos, pages de contenido y un pequeño set de settings de solo lectura.

Si estás conectando Shopify en su lugar, consulta Conectar Shopify.

¿Por qué una Store API Account y no la app pública?​

Clione no usa OAuth de BigCommerce ni el flujo público del App Marketplace. En su lugar, creas una Store API Account dentro de tu propia tienda. Tres ventajas concretas:

  • Inmediato. Sin cola de revisión de apps, sin espera de aprobación.
  • Scope reducido. Concedes exactamente los scopes que Clione necesita (Paso 3) — nada más.
  • Revocable con un clic. Borra la API Account desde tu admin de BC y cada petición de Clione a tu tienda devuelve 401 en segundos.

El trade-off es un paso extra de configuración. El resto de esta guía es ese paso, detallado.

Paso 1 — Abre el panel de API Accounts​

  1. Entra en el admin de tu tienda BigCommerce: https://store-<your-hash>.mybigcommerce.com. (El "store hash" es el segmento alfanumérico en tu URL de admin — cópialo ahora, lo necesitarás en el Paso 5.)
  2. Desde el sidebar izquierdo, pulsa Settings.
  3. Desplázate por la página Settings hasta encontrar la sección API.
  4. Pulsa API Accounts.
  5. Pulsa Create API Account (arriba a la derecha) → elige V2/V3 API token.
    • (captura: BigCommerce admin → Settings → API → API Accounts → menú desplegable Create API Account)
    • Verás dos opciones: V2/V3 API token (esta) y Stencil-CLI Token. Elige V2/V3.

Paso 2 — Nombra la cuenta​

CampoValor
NameClione AI (cualquier nombre vale; esta etiqueta aparece en la lista de API Accounts y en tu rastro de auditoría).
OAuth scopesSe configuran en el Paso 3 de abajo.

Deja todo lo demás en valores por defecto. El nombre es para tu propio rastro de auditoría — elige algo que te permita distinguirla de cualquier otra API account más adelante (p. ej. Clione AI — production).

Paso 3 — Configura los scopes​

Clione necesita tres scopes. El resto debe quedarse en None.

ScopeNivel requeridoPor qué lo necesita Clione
ProductsModifyLeer todos los productos, categorías, marcas, variantes y product options. Escribir el nuevo meta_title (page_title), meta_description, meta_keywords, search_keywords, custom_url (canónica) y la configuración del widget de structured-data de vuelta. Modify cubre tanto lectura como escritura — Read-only no es suficiente.
ContentModifyLeer y actualizar pages de contenido (About, Shipping, pages personalizadas). Instalar y eliminar el script gestionado del Schema Injector vía la API Content > Scripts de BC. Sin Modify la tarjeta del Schema Injector en Settings dirá "Cannot install — Content scope missing".
Information & SettingsRead-onlyLeer nombre de la tienda, divisa, zona horaria, channels. Necesario para el JSON-LD consciente de divisa (priceCurrency), la detección multi-canal usada por el Schema Injector para detectar storefronts headless (Catalyst, Next.js, custom), y la consulta /v2/store que arregla la URL del storefront automáticamente. Clione nunca escribe aquí.

Scopes que NO debes activar​

Concederlos expondría datos que Clione nunca lee. Déjalos en None:

  • Customers, Customer logins
  • Orders, Order Transactions
  • Carts, Checkout content, Shipping
  • Themes, Sites & Routes, Channel Settings, Storefront API Tokens
  • Payments, Marketing, Promotions (Promotions se añadirá en un módulo futuro con su propio scope; hoy Clione no lo usa.)

Qué significa "Modify" vs "Read-only" en BC​

Los niveles de scope de BigCommerce son anidados — Modify implica Read-only. No hay un nivel separado "Write". Si por error eliges Read-only para Products o Content, el sync funcionará pero la propagación, la instalación del Schema Injector y cualquier operación de escritura fallará con 403 Forbidden. Tendrás entonces que volver aquí, cambiar el nivel y Save — BC aplica el nuevo comportamiento, pero el token existente se reutiliza (no necesitas volver a pegarlo en Clione).

Paso 4 — Guarda y descarga las credenciales​

  1. Pulsa Save arriba a la derecha.
  2. BigCommerce muestra un diálogo de confirmación de una sola vez con tus nuevas credenciales y ofrece una descarga de archivo .txt.
  3. Descarga el archivo .txt y guárdalo bien. BigCommerce nunca volverá a mostrar estas credenciales. Si las pierdes, debes borrar esta API account y crear una nueva desde cero.

El archivo contiene cuatro valores:

Client ID:       <algo como p9z4x...>                 ← no lo usa Clione
Client Secret:   <string aleatorio largo>             ← no lo usa Clione
Access Token:    <string aleatorio largo — esto es lo que Clione necesita>
API Path:        https://api.bigcommerce.com/stores/<YOUR_STORE_HASH>/v3/

Solo el Access Token y el API Path importan para Clione. El Client ID y el Client Secret se usan solo si quisieras generar tokens OAuth adicionales más adelante — Clione no los necesita.

El store hash en el API Path es el mismo hash de tu URL de admin (Paso 1). Confirma que coinciden — si tienes varias tiendas en BC y copiaste el incorrecto, la integración fallará después con 404 Not Found.

Paso 5 — Añade la tienda en el dashboard de Clione​

  1. Entra a tu dashboard de Clione en app.clione.ai.
  2. Desde el sidebar izquierdo, pulsa + Add Store (o abre /stores/new directamente). Se abre el asistente de 3 pasos.
  3. Paso 1 — Elige la plataforma: pulsa la tarjeta BigCommerce.
  4. Paso 2 — Datos de la tienda:
    • Store name — cualquier cosa que te ayude a reconocerla en el sidebar (p. ej. EgoShoes US).
    • Store Hash — pega el hash alfanumérico del Paso 4 (el segmento en el API Path, p. ej. abc123xyz). Sin prefijo store-, sin barra final.
    • Storefront URL — la URL pública que ven tus compradores. Si usas dominio personalizado, pégalo (https://shop.example.com). Si no, pega la URL mybigcommerce.com (https://store-abc123xyz.mybigcommerce.com). Las barras finales se eliminan automáticamente. Esta URL es la que Clione consulta durante la Verification y es la referencia canónica para la whitelist de dominios permitidos del Schema Injector.
    • Currency — la misma divisa que usa tu tienda BC. Clione la vuelve a leer en cada sync vía /v2/store (scope Information & Settings), pero el valor que pongas aquí es el fallback si esa lectura falla.
  5. Pulsa Next.
  6. Paso 3 — Credenciales: pega el Access Token (del archivo .txt) en el campo BigCommerce Access Token.
  7. Pulsa Create and Connect.

En segundos la tienda aparece en tu sidebar. Ábrela para ver el resumen. La tarjeta del Schema Injector (cubierta abajo) muestra el estado de instalación.

Si saltas el campo Storefront URL, Clione por defecto usa https://store-<hash>.mybigcommerce.com — vale para un sandbox, pero si tus compradores reales ven un dominio distinto, deberías ponerlo ya. La Verification y la whitelist de dominios del Schema Injector dependen ambas de que este valor sea correcto.

Paso 6 — Instala el Schema Injector (requerido para JSON-LD en storefronts Stencil)​

Si tu storefront corre sobre BigCommerce Stencil (el theme hosted clásico — la mayoría de las tiendas), el Schema Injector es lo que mete el JSON-LD enriquecido de Clione en el <head> de tu storefront en vivo. Sin él, los datos enriquecidos viven en la BD de Clione pero nunca llegan a los crawlers.

Si tu storefront es headless / Catalyst (storefront Next.js construido aparte), el Schema Injector no aplica — usa el SDK @clione/seo en su lugar. La tarjeta del Schema Injector auto-detecta esto vía la API /v3/channels de BigCommerce y muestra la guía correcta.

Instalación de un clic (Stencil)​

  1. Abre la tienda en Clione → Settings.
  2. Desplázate hasta la tarjeta Schema Injector.
  3. Pulsa Install Schema Injector.

Qué pasa entre bastidores:

  1. Clione llama a /v3/channels para detectar si estás en Stencil, headless o mixto. Tiendas solo-headless reciben un panel "usa @clione/seo en su lugar" y se salta la instalación. Las mixtas (Stencil + un canal Next.js) instalan en Stencil y muestran un aviso de que el canal headless aún necesita el SDK.
  2. Clione sondea la homepage de tu storefront buscando un embed Clione existente (embed.clione.ai, atributo data-clione-embed, etc.). Si ya hay un embed manual presente, la instalación pregunta si coexistir o reemplazar — JSON-LD duplicado es penalizado por motores de búsqueda, así que este preflight es intencional.
  3. Clione provisiona una API key interna del lado del servidor (tú no pegas nada). La clave tiene scope products:read y está restringida al dominio del storefront de tu tienda únicamente.
  4. Clione llama a la API /v3/content/scripts de BC para registrar un script tag llamado "Clione Schema Injector" con:
    • location: head (renderiza en el <head> de cada página del storefront).
    • load_method: default (síncrono; corre antes de DOMContentLoaded).
    • visibility: storefront (cada página del storefront, no el admin).
    • consent_category: essential (no sujeto al cookie banner).
    • kind: src con src apuntando a https://api.clione.ai/api/v1/public/embed/schema-injector/<your-store-id>.js.
  5. BigCommerce empieza a servir ese script tag en cada página en segundos.

El trabajo del script en runtime es detectar el contexto de la página actual (product / category / page) a partir de patrones de URL más el input oculto product_id de BC, y luego obtener el JSON-LD enriquecido desde Clione e inyectarlo en <head> como <script type="application/ld+json" data-clione="injector">. Los crawlers que ejecutan JavaScript (Google, Bing moderno, GPTBot, ClaudeBot, PerplexityBot) ven el JSON-LD inyectado en la siguiente carga de página. Para crawlers tipo curl que no corren JS, consulta Stencil — crawlers sin JS.

Verificar la instalación​

  1. Abre cualquier página de producto enriquecido en una ventana de incógnito.
  2. Mira el código fuente (Ctrl/Cmd + U).
  3. Busca data-clione="injector". Deberías encontrar un bloque <script type="application/ld+json"> con el schema Product enriquecido, incluyendo keywords, description y (si los reviews están activos) aggregateRating.
  4. Opcionalmente, abre la tarjeta del Schema Injector → Preview JSON-LD para ver exactamente lo que Clione inyectaría sin salir del dashboard.

Desinstalar​

Pulsa Uninstall en la tarjeta. Clione revoca primero la API key interna, y luego llama a /v3/content/scripts/:uuid DELETE de BC. La tarjeta vuelve a "Not installed" y el storefront deja de servir JSON-LD de Clione en la siguiente carga de página.

Si llevas un rato en el dashboard y la tarjeta sigue diciendo "Not installed" justo después de una instalación correcta, haz hard refresh — el endpoint de estado es no-store y debería estar fresco, pero capas raras de caching del navegador (proxies corporativos, service workers) pueden retener una respuesta vieja.

Consulta la referencia completa del Schema Injector para los flujos headless, la preview de JSON-LD y la resolución de problemas por plataforma.

Comprobación rápida (opcional)​

Si quieres verificar que el token funciona antes de pegarlo en Clione, ejecuta esto en cualquier terminal (sustituye los dos placeholders por tus valores reales):

curl -s -H "X-Auth-Token: <ACCESS_TOKEN>" \
  "https://api.bigcommerce.com/stores/<STORE_HASH>/v3/catalog/products?limit=1"

Esperado: una respuesta JSON con uno de tus productos. Si ves {"status":401,...}, el token se copió mal — vuelve a abrir el archivo .txt del Paso 4 y copia otra vez, sin espacios al principio o al final. Si ves {"status":404,...}, el store hash no coincide con el token.

Resolución de problemas (específica de BigCommerce)​

401 Unauthorized — El Access Token se copió mal, o la API Account fue borrada/rotada del lado BC. Vuelve a abrir el archivo .txt del Paso 4 y copia el valor del Access Token exactamente. Sin espacios al principio o al final, sin comillas. Luego vuelve a pegarlo bajo Store → Settings → Credentials en Clione. (El store hash se guarda aparte — guardar solo el token no borra el hash.)

403 Forbidden cuando Clione intenta leer productos — El scope Products está en None. Abre BC admin → Settings → API Accounts → edita la cuenta Clione AI → pon Products a Modify → Save.

403 Forbidden solo cuando Clione intenta escribir metadatos — El scope Products está en Read-only. Súbelo a Modify y guarda. El token existente se reutiliza; no necesitas volver a pegarlo en Clione.

404 Not Found — El Store Hash no coincide con la tienda real. Abre el .txt del Paso 4 y verifica que el segmento API Path coincide con tu URL de admin. Si tienes varias tiendas BC, puede que cogieras la cuenta equivocada.

El Schema Injector dice "Cannot install — Content scope missing" — El scope Content está en Read-only o None. Ponlo en Modify en el admin de BC y pulsa Install otra vez.

La instalación del Schema Injector devuelve 422 invalid field [html] — Bug histórico, arreglado en la implementación actual (usa kind=src en lugar de HTML inline). Si lo ves en una instalación nueva, tu tenant puede estar pinned a una release antigua — abre un ticket de soporte.

El Schema Injector se instala pero el JSON-LD no aparece en el código de la página — Dos causas habituales:

  1. Estás mirando una página donde el JS aún no ha corrido. La inyección pasa después de que se complete el fetch asíncrono del bootstrap, así que aterriza poco después del HTML inicial. Hard refresh (Ctrl/Cmd + Shift + R) y comprueba otra vez. Los crawlers con JS esperan a que el JS se asiente, así que no es un problema de visibilidad para crawlers — solo un problema óptico de "view-source-before-JS".
  2. La página se cargó con una caché de robots entre tú y tu storefront (p. ej. un proxy corporativo eliminando scripts). Prueba desde una red distinta.

La divisa en el JSON-LD vuelve a USD — Falta el scope Information & Settings o está en None. El endpoint /v2/store que devuelve la divisa de la tienda requiere este scope. Ponlo en Read-only en el admin de BC y vuelve a sincronizar.

Custom URL (canónica) muestra product-not-found-{id} en Verification — platform_metadata viejo de un sync anterior. El adaptador de propagación BC de Clione hace fallback a una llamada getProduct() fresca para recuperar la URL — vuelve a sincronizar el producto (abre el detalle del producto → Refresh from platform) y la URL canónica aparecerá correctamente en la siguiente verificación.

La Verification falla en una tienda sandbox / protegida por contraseña — Pasa un preview code. Abre la entidad que falla en Verification → el panel de detalle tiene un banner con "Storefront unreachable — looks like password-protected"; pega el preview code de BC admin → Settings → Storefront → Sandbox y pulsa Retry verification. Consulta Verificar señales — BigCommerce para más detalle.

El sync corre pero solo aparecen algunos productos — Algunos productos pueden tener is_visible: false o estar en un canal inactivo. Clione sincroniza todo lo que la API devuelve; si tu filtro de admin es "Visible only" los contadores diferirán. Compara como con como en el listado de productos de BC.

429 Too Many Requests — La REST API de BC limita a 20 req/s por token para V2/V3. Clione tiene backoff automático. Si lo ves repetidamente, probablemente tienes una integración paralela en la misma API Account — crea una API Account separada para Clione para evitar contención.

Revocar el acceso​

Si necesitas revocar el acceso de Clione:

  1. BC admin → Settings → API Accounts.
  2. Encuentra la cuenta Clione AI.
  3. Pulsa el menú de tres puntos → Delete.

En segundos, cada petición de Clione a tu tienda devuelve 401 y la tienda deja de aparecer como sana en el dashboard de Clione.

Si además quieres eliminar manualmente el script tag del Schema Injector, lo harías desde Storefront → Script Manager, pero suele ser innecesario — cuando se borra la API Account, el script sigue ahí pero Clione ya no puede obtener JSON-LD para él (el bootstrap no devuelve nada con 401). El script se vuelve un no-op; puedes limpiarlo cuando te venga bien.

Si además quieres borrar la tienda y sus datos enriquecidos de Clione, usa Danger zone → Schedule deletion en Store → Settings en el dashboard de Clione. Consulta Ajustes de la tienda — Danger zone.

Qué cambia en BigCommerce vs Shopify​

Referencia rápida si estás conectando tu segunda plataforma:

AspectoBigCommerceShopify
Tipo de tokenAccess Token + Store Hash desde una API Account V2/V3.Único Admin API access token shpat_.
Dónde se crea el tokenSettings → API → API Accounts → Create API Account.Settings → Apps and sales channels → Develop apps → Create an app.
JSON-LD en el storefrontSchema Injector (script tag inyectado vía BC Scripts API).Theme app embed (bloque Liquid server-side activado en el theme editor).
Modelo de variantesProduct Options + SKUs generados (variantes derivadas).Variantes first-class (cada variante un SKU separado con su propio precio/opciones).
Equivalente a categoryCategories (estructura de árbol, parent IDs).Collections (manuales + smart, basadas en reglas).
Multi-divisaChannels + divisas por channel.Markets + precios por market.
Reviews nativosSettings → Channels → Customer Reviews (built-in).Solo terceros (Judge.me / Yotpo / Loox / Stamped).
Máximo de meta description65535 chars (sin límite práctico).255 chars (límite del tipo de metafield; Clione trunca).
Velocidad de sync por 1k entidades30–60s (REST v3, 20 req/s).60–120s (throttle basado en coste GraphQL).

Consulta Capacidades por plataforma para la matriz completa por señal.

Qué ocurre una vez Clione tiene el token​

  1. Primer sync (1–10 minutos según el tamaño del catálogo). Clione descarga tus productos, categorías y pages. Sigue el progreso en el chip de la barra superior o en Sync en el sidebar de la tienda. Consulta Sincroniza tu catálogo.
  2. Primer enriquecimiento. Selecciona un lote pequeño desde cualquier listado 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.
  3. Auto-propagación. En cuanto el enriquecimiento termina, las señales se escriben de vuelta vía la REST API de BC en segundo plano. No pulsas nada para esto. El script del Schema Injector recoge el nuevo JSON-LD en la siguiente carga de página del storefront — no hay un paso "push" separado.
  4. 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 Verificar señales — BigCommerce.

Cada escritura queda registrada con valores antes/después en la pestaña Propagation de cada entidad. Si una escritura fue rechazada por BC (p. ej. custom_url mal formada, campo demasiado largo), el registro de propagación muestra la respuesta cruda de la API para que puedas diagnosticarlo.