Saltar al contenido principal

Sincroniza tu catálogo

Planes: Starter ✓ · Growth ✓ · Pro ✓ · Agency ✓ (el cap de catálogo varía por plan — consulta Planes)

El sync descarga tus productos, categorías (o collections, en Shopify), content pages y FAQs desde tu tienda hacia Clione. Aún no se enriquece nada — el sync simplemente construye la copia de trabajo de Clione para que el resto de la plataforma tenga algo sobre lo que operar.

Sincronizas por tienda, y por tipo de entidad. Abre cualquier tienda en el sidebar, luego pulsa Sync.

La página Sync tiene cuatro pestañas:

  • Products
  • Categories (BigCommerce) / Collections (Shopify)
  • Pages
  • FAQs (solo si tu plataforma guarda páginas de FAQ nativas — la mayoría no, así que esta pestaña es informativa)

Cada pestaña corre independientemente. Puedes sincronizar solo lo que cambió sin volver a descargar todo el catálogo.

Cuándo lanzar un sync​

  • La primera vez que conectas una tienda. Lanza las tres (Products, Categories/Collections, Pages) para que Clione tenga la foto completa.
  • Tras cambios masivos en el admin de tu e-commerce. Nueva línea de productos, reorganización de categorías, reescritura de pages — sincroniza después para poner Clione al día.
  • Antes de un bulk-enrich. Si acabas de importar 200 SKUs, sincronízalos antes de enriquecer, o Clione solo enriquecerá lo que ya conocía.
  • Cuando aparezcan sospechas de "datos viejos". Cuando el dashboard muestra un title o description desactualizado para una entidad que sabes que cambiaste en el admin de tu tienda, lanza un sync para ese tipo de entidad.

NO necesitas sincronizar para usar el editor de FAQ, el URL Verifier, los Reports ni ninguna de las herramientas a nivel plataforma. El sync solo toca el espejo del catálogo.

BigCommerce​

Products​

  1. Abre la tienda → Sync → pestaña Products.
  2. Pulsa Sync products.
  3. El chip de progreso en la barra superior muestra el estado en tiempo real (ejecutándose, páginas procesadas, errores). Sobrevive a la navegación — puedes salir de la página y volver.

Qué se descarga por producto:

  • ID, name, SKU, vendor, brand
  • Price + currency
  • Description (HTML), short description
  • Categorías a las que pertenece el producto
  • Todos los metadatos SEO: page_title, meta_description, search_keywords, meta_keywords, custom_url, todos los campos open_graph_*
  • URLs de imágenes (principal + variantes)

Categories​

  1. Sync → pestaña Categories → Sync categories.
  2. Se descarga el árbol completo de categorías (los parent IDs se preservan). También vienen categorías de solo lectura y flags de visibilidad.

Nota: el custom_url de category en BigCommerce es solo lectura vía la API pública y llega como { url, is_customized }. Clione respeta lo que la tienda tenga actualmente — no reescribe URLs de categoría.

Pages​

  1. Sync → pestaña Pages → Sync pages.
  2. BigCommerce devuelve content pages (About, Contact, pages personalizadas — no posts de blog).

FAQs​

BigCommerce no expone entidades nativas de FAQ, así que esta pestaña muestra solo texto informativo. La funcionalidad de FAQ de Clione vive bajo FAQs (en el sidebar de cada tienda) y es agnóstica de plataforma — consulta Editor de FAQ + widget de embed.

Shopify​

Products​

  1. Abre la tienda → Sync → pestaña Products.
  2. Pulsa Sync products.

Qué se descarga por producto:

  • ID, title, handle, vendor, product type, tags
  • Price + currency (variante por defecto)
  • Description (HTML)
  • Todos los metafields SEO bajo el namespace global (title_tag, description_tag)
  • URLs de imágenes
  • Lista de variantes (el soporte multi-divisa está previsto — consulta Planes)

Collections​

  1. Sync → pestaña Collections → Sync collections.
  2. Se descargan tanto las collections manuales (custom) como las smart (automatizadas). Las rules de las smart collections se guardan para que Clione sepa qué productos pertenecen sin volver a preguntar a Shopify en cada petición.

Pages​

  1. Sync → pestaña Pages → Sync pages.
  2. Shopify devuelve content pages (About, Contact, Help — no artículos de blog).

FAQs​

Igual que BigCommerce — esta pestaña es informativa. Usa el Editor de FAQ para FAQs gestionadas.

Ver el progreso​

Mientras un sync está corriendo:

  • Un chip aparece arriba a la derecha del dashboard con el tipo de entidad y un spinner.
  • Pasar el ratón muestra "synced N / total" y cualquier error.
  • El chip persiste entre navegaciones (puedes cambiar de pestaña y volver).
  • Cuando el sync termina, el chip se pone verde y se cierra automáticamente tras unos segundos. Las páginas de listado (Products, Categories, Pages) se refrescan automáticamente para que veas los datos nuevos sin recargar manualmente.

Si un sync falla a media ejecución (p. ej. un 429 transitorio de la API de la tienda), las entidades ya sincronizadas se quedan. Pulsa Sync de nuevo para reanudar — Clione es idempotente y solo actualiza filas donde el updated_at upstream es más nuevo que lo que está en nuestra BD.

¿Cuánto tarda?​

Estimaciones aproximadas por cada 1.000 entidades (depende de la red y la plataforma):

EntidadBigCommerceShopify
Products30–60s60–120s
Categories / Collections< 5s< 10s
Pages< 5s< 5s

Shopify es más lento por llamada porque su API GraphQL limita por coste, no por requests por segundo. Clione reintenta con backoff automáticamente cuando alcanza el límite de coste, así que un sync de 5.000 productos puede tardar 5–10 minutos en Shopify.

Re-sync vs sync parcial​

Hoy, el sync siempre es full-pass: Clione recorre cada página de la API upstream y hace upsert de cada registro. Es intencional — el sync incremental vía webhooks es una adición prevista pero el modelo actual es más simple y converge garantizadamente.

Si solo cambiaste un puñado de productos en el admin de tu tienda y quieres verlos en Clione sin re-sincronizar miles, puedes:

  1. Abrir la entidad directamente por nombre desde cualquier listado.
  2. Pulsar Refresh from platform en la cabecera del detalle de la entidad. Esto vuelve a descargar esa única entidad desde BC/Shopify y actualiza el espejo.

Resolución de problemas​

El sync dice "no credentials" o "401" — El access token ha sido revocado del lado de la plataforma, o ha expirado. Vuelve a añadir la credencial en Store → Settings → Credentials.

El sync corre pero el conteo de entidades no coincide con mi tienda — Algunas entidades pueden estar ocultas a la API (p. ej. drafts, eliminadas-pero-no-purgadas). Filtra el admin de tu tienda por estado "active / visible" para comparar como con como. Si el gap persiste, contacta a soporte con el store ID y unos SKUs de muestra que deberían aparecer pero no.

El sync se queda en 99% — Una entidad concreta está fallando al hacer upsert (normalmente una URL de imagen mal formada o un campo demasiado largo). Abre la consola del navegador del dashboard (F12 → pestaña Console) y busca la fila que dio error — el mensaje incluye el ID de entidad. Arregla ese registro en el admin de tu tienda y vuelve a sincronizar.

"Enrichment muestra 0/0 incluso tras sincronizar" — Problema conocido (#87). El sync escribió las entidades pero el contador del overview lee desde una caché vieja. Refresca la página una vez; si persiste, este es el bug que estamos rastreando — por favor repórtalo con el store ID.

Endpoints de API tocados por plataforma​

Para resolución de problemas y para entender los scopes requeridos, aquí están los endpoints de plataforma que cada sync toca.

BigCommerce (REST v3)​

  • GET /v3/catalog/products?limit=250&page=N&include=variants,images,custom_fields,bulk_pricing_rules,options,modifiers,videos — recorrido paginado.
  • GET /v3/catalog/brands — para resolución de vendor.
  • GET /v3/catalog/categories?limit=250&page=N — lista plana de nodos de categoría.
  • GET /v3/catalog/categories/tree — forma de árbol para enlaces parent/child.
  • GET /v3/content/pages?limit=250&page=N — content pages.
  • GET /v3/catalog/products/:id/metafields?namespace=clione — para leer de vuelta lo que Clione escribió previamente.

Scopes requeridos (desde la BC Store API account):

  • Products: Read/Write
  • Information & Settings: Read
  • Content: Read
  • Customers: None
  • Orders: None
  • Marketing: Read (solo si se usa Promotions)

Shopify (Admin GraphQL 2024-10)​

  • query { products(first: 250) { ... } } — recorrido paginado con pageInfo.
  • query { collections(first: 250) { ... } } — manuales y smart.
  • query { pages(first: 250) { ... } } — content pages.
  • query { shop { primaryDomain, currencyCode, ... } } — metadatos de la shop.
  • query { metafields(...) } — leer de vuelta el namespace de metafields de Clione.

Scopes requeridos (desde la Custom App de Shopify):

  • read_products, write_products
  • read_content, write_content
  • read_themes, write_themes (write_themes opcional pero recomendado)
  • read_online_store_pages
  • read_locales

Logs de sync​

Tras cada sync, una entrada aparece en el panel Sync history en la página Sync. Cada entrada muestra:

  • Timestamps de inicio + fin
  • Tipo de entidad
  • Entidades procesadas / creadas / actualizadas / con error
  • Filas por error con el entity ID ofensor y la respuesta de la plataforma

Las entradas persisten durante 30 días. Filtra por tipo de entidad o por "errors only" para triajar.

Concurrencia​

Solo puedes ejecutar un sync por tipo de entidad por tienda a la vez. Si pulsas Sync mientras hay uno en progreso, el botón está deshabilitado y un tooltip lo explica. Múltiples tiendas pueden sincronizar en paralelo.

A través de todas las tiendas de tu tenant, la concurrencia global de sync es 4 (uno por core de CPU en nuestros workers de sync). Los syncs 5+ encolados arrancan según terminan los anteriores.