Saltar al contenido principal

Crea una API account de BigCommerce para 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 es la mitad BigCommerce de conectar una tienda: la API account que creas dentro de tu propia tienda, el nivel exacto de cada scope y el Schema Injector. Para el recorrido completo, con la parte de Clione incluida, empieza en Conecta tu tienda BigCommerce y vuelve aquí para el token.

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. Hay tres scopes obligatorios y tres opcionales, uno por funcionalidad: el paso 3 de más abajo es el único sitio que dice cuáles y en qué nivel. Si además concedes el scope opcional Orders — Read-only y estás en Pro o Agency, lee una vez al día tus pedidos de los últimos 30 días para la Atribución. En Starter y Growth no se lee ningún pedido, aunque concedas el scope. BigCommerce envía el pedido entero, con los datos de contacto del comprador; Clione guarda solo los datos del pedido y sus líneas, y nunca guarda el nombre, el email, el teléfono, la dirección, la cuenta de cliente ni los datos de pago de un cliente. Los datos de pedidos se guardan 13 meses desde la fecha del pedido y después se borran automáticamente.

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. Hay tres más opcionales, y cada uno enciende exactamente una funcionalidad. Todo lo demás se queda en None.

Los tres scopes obligatorios​

ScopeNivelPara qué lo necesita Clione
ProductsModifyLeer productos, categorías, marcas, variantes, opciones y sus price lists (ahí viven los precios B2B y los de varias divisas). 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í.

Los tres scopes opcionales​

Si dejas uno en None, esa funcionalidad simplemente queda apagada. No se rompe nada más, y Clione te avisa en el dashboard cuando una funcionalidad está esperando un scope.

ScopeNivelQué enciendeSi lo dejas en None
OrdersRead-onlyLa Atribución en Pro y Agency: Clione lee tus pedidos para comparar las ventas referidas por IA y las de productos enriquecidos con el resto. También es como Clione confirma que un cupón entregado a un agente de IA se ha canjeado de verdad. En Starter y Growth no se lee ningún pedido aunque concedas el scope.Clione no lee pedidos en ningún plan.
Channel SettingsRead-onlyPermite a Clione leer tu lista de canales y distinguir un storefront Stencil de uno headless antes de instalar el Schema Injector.La instalación asume Stencil, que es lo correcto en la gran mayoría de tiendas. Si la tuya es headless, usa el SDK @clione/seo.
MarketingModifySolo para las ofertas de IA: Clione crea la promoción con cupón y su código en tu tienda a través de la Promotions API de BigCommerce, y los borra cuando la oferta termina. BigCommerce exige Modify aquí: su nivel Marketing — Read-only no cubre la Promotions API.Clione no crea ninguna promoción ni entrega ningún código de cupón. Ninguna otra funcionalidad se ve afectada.

No hace falta ningún scope más. Los webhooks —con los que Clione se entera de que has editado un producto en BigCommerce— funcionan con el scope default de BigCommerce, que lleva toda cuenta de API, así que no hay nada que activar para ellos.

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 Listings, Storefront API Tokens
  • Payments

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.

Acierta con los scopes ahora: después no se pueden cambiar

La documentación de BigCommerce lo dice sin rodeos: "You can't change store-level access tokens or OAuth scopes." No hay ninguna pantalla que suba el nivel de una cuenta de API ya creada. Arreglar un scope mal puesto significa crear una cuenta de API nueva con los scopes correctos (los pasos 1–4 otra vez), pegar su token en Clione en Store Settings → Credentials y borrar después la cuenta antigua. Son dos minutos, pero es un token nuevo, no una edición.


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. Los scopes de una cuenta de API ya creada no se pueden cambiar, así que crea una cuenta nueva (pasos 1–4) con Products en Modify, pega su token en Ajustes de la tienda → Credenciales y borra después la antigua.

403 Forbidden solo al escribir: Products o Content están en Read-only. Mismo arreglo: una cuenta de API nueva con ese scope en Modify, su token pegado en Clione y borrar la antigua. No hay forma de subir el nivel sobre la misma cuenta.

403 Forbidden en la Promotions API: Marketing está en None, o en Read-only, que BigCommerce no acepta para Promotions. Solo lo necesitan las ofertas de IA; todo lo demás sigue funcionando.

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: Content tiene que estar en Modify. Si lo está, vuelve a pulsar Instalar. Que falte el scope Channel Settings nunca bloquea la instalación: Clione asume Stencil y sigue.

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.