Saltar al contenido principal

Conecta tu tienda BigCommerce a Clione

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

Tiempo: ~5–10 minutos, incluido el paso del Schema Injector.

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 la barra lateral del admin, a tu usuario le falta ese permiso: pídele al propietario que te lo añada en Settings → Users → [tu nombre] → Permissions.

Esta guía le da a Clione el acceso que necesita para leer tu catálogo de BigCommerce, enriquecerlo, publicar las señales optimizadas de vuelta e instalar el Schema Injector en tu storefront. Cada ruta de la interfaz está explicada paso a paso, cada campo se llama como lo verás en el admin de BigCommerce y cada scope tiene su porqué.

Clione lee tu catálogo (con los niveles de stock), tus páginas de contenido y unos pocos ajustes de solo lectura. Si además concedes el scope opcional Orders — Read-only, lee tus pedidos para la Atribución (Pro y Agency). Clione nunca ve cuentas de clientes ni datos de pago.

Si lo que vas a conectar es Shopify, mira Conectar Shopify.

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

Clione se conecta a BigCommerce con una Store API Account que creas dentro de tu propia tienda. Tres ventajas concretas:

  • Inmediato. Sin cola de revisión de apps ni esperas de aprobación.
  • Acotado. Concedes exactamente los scopes que Clione necesita (Paso 3), ni uno más.
  • Revocable en un clic. Borras la API Account en el admin de BigCommerce y cualquier petición de Clione a tu tienda se rechaza.

Paso 1 — Abre el panel de API Accounts​

  1. Entra en el admin de tu tienda BigCommerce. El store hash es el segmento alfanumérico de la URL del admin (store-<hash>.mybigcommerce.com); lo necesitarás en el Paso 5.
  2. En la barra lateral, haz clic en Settings.
  3. Baja hasta la sección API y haz clic en API Accounts.
  4. Haz clic en Create API Account → elige V2/V3 API token (no Stencil-CLI Token).

Paso 2 — Ponle nombre a la cuenta​

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

Deja todo lo demás por defecto.

Paso 3 — Configura los scopes​

Clione necesita tres scopes, más uno opcional para la Atribución. El resto tiene que quedarse en None.

ScopeNivelPara qué lo necesita Clione
ProductsModifyLeer productos, categorías, marcas, variantes y opciones. Escribir de vuelta el meta title, la meta description y las meta keywords, y las search keywords de las categorías (los productos nunca llevan search keywords). Read-only no basta.
ContentModifyLeer y actualizar páginas de contenido (About, Shipping, páginas propias), escribir los widgets de datos estructurados con la Widget API de BigCommerce e instalar o quitar el script del Schema Injector a través de la Scripts API de BigCommerce.
Information & SettingsRead-onlyLeer el nombre de la tienda y el dominio del storefront. Clione nunca escribe aquí.
Orders (opcional)Read-onlySolo para la Atribución (Pro y Agency): leer tus pedidos para comparar las ventas referidas por IA y las de productos enriquecidos con el resto. Déjalo en None si no usas la Atribución.

Scopes que NO debes activar​

Darlos expondría datos que Clione no lee jamás. Déjalos en None:

  • Customers, Customer logins
  • Order Transactions
  • Carts, Checkout content, Shipping
  • Themes, Sites & Routes, Channel Settings, Storefront API Tokens
  • Payments, Marketing, Promotions

Qué significa "Modify" frente a "Read-only" en BigCommerce​

Los niveles de BigCommerce son anidados: Modify incluye Read-only. Si eliges Read-only en Products o Content, la sincronización funciona, pero publicar, instalar el Schema Injector y cualquier otra escritura fallan con 403 Forbidden. Vuelve aquí, cambia el nivel y pulsa Save: el token sigue valiendo, así que no hay que volver a pegarlo en Clione.

Paso 4 — Guarda y descarga las credenciales​

  1. Haz clic en Save, arriba a la derecha.
  2. BigCommerce muestra una única vez un diálogo con las credenciales nuevas y te ofrece descargar un .txt.
  3. Descarga el .txt y guárdalo en un sitio seguro. BigCommerce no vuelve a enseñar estas credenciales. Si las pierdes, borra la API Account y crea otra.

El fichero tiene cuatro valores:

Client ID:       <algo como p9z4x...>               ← Clione no lo usa
Client Secret:   <cadena aleatoria larga>           ← Clione no lo usa
Access Token:    <cadena aleatoria larga — esto es lo que necesita Clione>
API Path:        https://api.bigcommerce.com/stores/<TU_STORE_HASH>/v3/

A Clione solo le importan el Access Token y el store hash del API Path. Comprueba que el hash coincide con el de la URL de tu admin: si tienes varias tiendas BigCommerce y copiaste la que no era, la conexión falla con 404 Not Found.

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

  1. Entra en tu dashboard de Clione en app.clione.ai.
  2. Haz clic en + Añadir tienda. Se abre el asistente con tres pasos: Plataforma, Detalles, Conectar.
  3. Plataforma: haz clic en la tarjeta BigCommerce.
  4. Detalles:
    • Nombre de la tienda: lo que te ayude a reconocerla en el dashboard.
    • Hash de la tienda: el hash alfanumérico del API Path (p. ej. abc123xyz). Sin el prefijo store- y sin barra final.
    • URL del escaparate: la URL pública que visitan tus clientes. Si usas dominio propio, pégalo (https://tienda.ejemplo.com); si no, la URL mybigcommerce.com. Solo el dominio raíz, nunca la URL de api.bigcommerce.com. Es donde Clione verifica tus señales.
    • Moneda: la misma moneda principal que usa tu tienda BigCommerce.
  5. Haz clic en Siguiente.
  6. Conectar: pega el Access Token del .txt en Token de acceso a la API. También puedes saltarte este paso y añadir el token más tarde en Ajustes de la tienda → Credenciales.
  7. Haz clic en Crear y conectar.

Si ya has llegado al límite de tiendas de tu plan, el asistente te lo dice y te ofrece Mejorar plan o el complemento que conecta una tienda más.

Paso 6 — Instala el Schema Injector​

A tu storefront de BigCommerce llegan dos cosas distintas, y conviene saber qué hace cada una:

  • JSON-LD (datos estructurados). Cuando publicas una entidad, Clione instala para ella un placement de la Widget API de BigCommerce. Stencil lo renderiza en el HTML en el servidor, así que los crawlers que no ejecutan JavaScript lo ven en la primera petición. No tienes que instalar nada para esto: lo hace la publicación.
  • El script del Schema Injector. Un script pequeño, que en el Script Manager de BigCommerce se llama "Clione FAQ Renderer", que pinta el acordeón de FAQs visible en tus páginas, aplica tu CSS de FAQs y añade dos etiquetas <link> de descubrimiento para agentes de IA (llms-txt y agents-json). No emite JSON-LD.

Instálalo (Stencil)​

  1. Abre la tienda en Clione → Ajustes de la tienda → pestaña Inyector de Schema.
  2. Haz clic en Instalar.

Lo que hace Clione al pulsarlo:

  1. Busca en tu storefront un embed de Clione que hayas puesto a mano. Si lo encuentra, se para y muestra Embed manual de Clione detectado con Descartar e Instalar igualmente (forzar).
  2. Lee tus canales de BigCommerce para saber si estás en Stencil, en headless o en ambos. Una tienda solo headless recibe las instrucciones de @clione/seo y no se instala nada. Una tienda con Stencil y además un canal headless recibe el script en Stencil y un aviso de que el storefront headless necesita @clione/seo.
  3. Genera una API key de solo lectura para este storefront, restringida al hostname de tu storefront. No tienes que pegar nada.
  4. Registra el script con la Scripts API de BigCommerce con location: head, load_method: async (nunca bloquea el renderizado de tu página), visibility: storefront y consent_category: essential. El script se carga desde https://api.clione.ai/api/v1/public/embed/schema-injector/<id-de-tu-tienda>.js.

La pestaña pasa a mostrar Instalado con el UUID del script, su ubicación, el método de carga y la visibilidad. Refrescar estado lo vuelve a leer.

Si tu storefront es headless (Catalyst, Next.js o cualquier frontend propio), la Scripts API no llega a él: usa el SDK @clione/seo.

Compruébalo​

  1. Abre una página de producto publicada en una ventana de incógnito y mira el código fuente (Ctrl/Cmd + U).
  2. Busca data-clione="schema-graph". Deberías encontrar un bloque <script type="application/ld+json"> con el @graph: Organization, WebSite, BreadcrumbList, Product y FAQPage cuando el producto tiene FAQs aprobadas. Si no está, esa entidad todavía no se ha publicado.
  3. Si quieres, pulsa Previsualizar JSON-LD en la pestaña Inyector de Schema para ver el JSON-LD de la tienda sin salir del dashboard.

Desinstalar​

Pulsa Desinstalar en la pestaña Inyector de Schema y confirma. Clione revoca la API key del script y lo quita de tu tienda. Desinstala siempre desde aquí, no borrando el script en el Script Manager, para que los registros de Clione sigan cuadrando.

Tienes más detalle en la referencia del Schema Injector.

Comprobación rápida (opcional)​

Para comprobar el token antes de pegarlo en Clione, ejecuta esto en una terminal (sustituye los dos marcadores):

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

Lo esperado: un JSON con uno de tus productos. {"status":401,...} significa que el token está mal copiado: cópialo otra vez del .txt sin espacios delante ni detrás. {"status":404,...} significa que el store hash no corresponde al token.

Problemas frecuentes​

401 Unauthorized: el Access Token está mal copiado o la API Account se borró en BigCommerce. Copia el Access Token otra vez tal cual, sin espacios ni comillas, y pégalo en Ajustes de la tienda → Credenciales.

403 Forbidden al leer productos: el scope Products está en None. En el admin de BigCommerce → Settings → API Accounts, edita la cuenta de Clione, pon Products en Modify y guarda.

403 Forbidden solo al escribir: Products o Content están en Read-only. Súbelos a Modify y guarda. El token sigue valiendo.

404 Not Found: el Store Hash no corresponde a la tienda. Compara el API Path del .txt con la URL de tu admin.

Falla la instalación del Schema Injector: comprueba que Content está en Modify y vuelve a pulsar Instalar.

No hay JSON-LD en el código fuente: la entidad todavía no se ha publicado. Abre su pestaña Publicar y publícala. Mira Publicar.

La verificación no llega a una tienda sandbox o protegida con contraseña: en la pestaña Publicar de la entidad, introduce tu Código de vista previa de BigCommerce (admin de BigCommerce → Storefront → My Themes → Advanced en tu tema activo → copia el Preview Code). Mira Verificar señales.

La sincronización funciona pero faltan productos: puede que algunos estén ocultos o en un canal inactivo. Compara con el mismo filtro en el listado de productos de BigCommerce.

429 Too Many Requests: BigCommerce limita las peticiones por token y Clione espera y reintenta solo. Si te pasa a menudo, seguramente otra integración comparte la misma API Account: crea una API Account solo para Clione.

Revocar el acceso​

  1. En Clione, desinstala primero el Schema Injector (Ajustes de la tienda → Inyector de Schema → Desinstalar). Una vez borrada la API Account, Clione ya no puede quitar el script por ti.
  2. Admin de BigCommerce → Settings → API Accounts.
  3. Busca la cuenta de Clione → menú de los tres puntos → Delete.

A partir de ahí, cualquier petición de Clione a tu tienda se rechaza. Si te saltaste el paso 1, borra a mano el script Clione FAQ Renderer en Storefront → Script Manager.

Si además quieres borrar la tienda y sus datos enriquecidos de Clione, usa Eliminar tienda en la pestaña Zona de peligro de los Ajustes de la tienda. Mira Ajustes de la tienda — Zona de peligro.

Qué viene después​

  1. Primera sincronización. Clione trae tus productos, categorías y páginas. Mira Sincroniza tu catálogo.
  2. Primer enriquecimiento. El enriquecimiento siempre pide confirmación antes de gastar créditos: la sincronización nunca enriquece por su cuenta. Mira Enriquece tu catálogo.
  3. Publicar. Enriquecer no escribe nada en tu storefront; publicar sí. Mira Publicar.
  4. Verificar. Desde Growth, abre Verificación en la barra lateral de la tienda para confirmar que el storefront en vivo coincide con Clione. Mira Verificar señales.

La matriz completa por señal está en Capacidades por plataforma.