Entender el enriquecimiento
Planes: Starter (créditos limitados) · Growth · Pro · Agency
Para instrucciones paso a paso de cómo enriquecer (single, bulk, wizard) para productos, categorías/collections y pages tanto en BigCommerce como en Shopify, consulta Enriquece tu catálogo. Esta página cubre el modelo conceptual de lo que produce el enriquecimiento y las diferencias en inputs entre plataformas.
Cada vez que Clione enriquece una entidad (bajo demanda desde cualquier listado o página de detalle), genera seis categorías de artefactos a partir de una única llamada al LLM más una llamada al embedding.
El mismo modelo aplica a los cuatro tipos de entidad: products, BC categories, Shopify collections y pages de contenido. Donde esta página menciona "product" más abajo, lo mismo aplica a los demás tipos (el set de artefactos es idéntico — la única diferencia es qué campos se muestran al LLM).
| # | Artefacto | Usado por |
|---|---|---|
| 1 | Texto semántico — identidad, razonamiento, objection handler | LLMs, búsqueda interna |
| 2 | Quality scores — durabilidad, calidad, relación calidad-precio, posicionamiento de precio | Dashboard, ranking |
| 3 | Keywords bilingües (EN + ES) | Búsqueda, tag clouds |
| 4 | Vector embedding (1536-dim) | Búsqueda por similitud semántica |
| 5 | JSON-LD (schema.org/Product) | Motores de búsqueda, crawlers LLM |
| 6 | Señales meta SEO — descripción, URL canónica, keywords | Herramientas SEO, storefronts headless |
Qué entra en la llamada al LLM
El title, description, price, vendor, categories de tu producto — eso es todo. Más cualquier pista que añadieras vía el Enrichment Wizard (audiencia objetivo, materiales, nombres de competidores, etc.) si lo rellenaste.
El LLM aún no tiene acceso a tus reviews, devoluciones, conversión o datos de ventas. Eso significa:
- Los campos identity y reasoning son nítidos — el LLM es muy bueno resumiendo el carácter de un producto a partir de títulos y descripciones.
- Los quality scores son conjeturas razonadas — el LLM tiene sentido común sobre mercados (Hermès→luxury, Primark→budget) pero está leyendo el texto de tu catálogo, no datos verificados de rendimiento.
Consulta Entendiendo los Quality Scores para el desglose completo y lo que estamos construyendo para arreglar esto.
Qué se le muestra exactamente al LLM por plataforma
El prompt semántico es el mismo en ambas plataformas. Lo que difiere es la forma del registro de entrada que el sincronizador entrega al LLM, porque cada plataforma organiza el catálogo de forma diferente.
BigCommerce
| Campo del lado BC | Nombre del campo en el prompt | Notas |
|---|---|---|
name | title | Siempre se envía. |
description | description | HTML se limpia a texto plano antes de enviar. |
price + sale_price + cost_price | price, salePrice | Se envía en la divisa por defecto de la tienda. |
brand_id → búsqueda del nombre de la marca | vendor | Resuelto vía /v3/catalog/brands/:id. |
| Categorías (array de IDs) → lista de nombres de categoría | categories | El path se aplana, p. ej. Home > Bedding > Sheets. |
options[] (size, color, etc.) | options | Se envía para que el modelo pueda nombrar variantes en el razonamiento. |
meta_keywords, search_keywords | existingKeywords | El LLM las usa como semillas, no como verdad. |
Imágenes (/products/:id/images) | imageCount | Solo el conteo — el modelo es solo texto. |
Shopify
| Campo del lado Shopify | Nombre del campo en el prompt | Notas |
|---|---|---|
title | title | Siempre se envía. |
bodyHtml | description | HTML se limpia. |
variants[0].price + compareAtPrice | price, salePrice | Divisa por defecto del Market principal de la tienda. |
vendor | vendor | Se envía literal. |
productType + pertenencia a collections | categories | Cuentan tanto las collections manuales como las smart. |
options[] y matriz de variantes | options | Todas las combinaciones se envían de forma compacta. |
tags (separados por coma) | existingKeywords | Se usan como semillas. |
images.edges.length | imageCount | Solo el conteo. |
Al modelo se le muestra para qué plataforma está escribiendo para que pueda evitar edge cases incómodos (p. ej. sabe que no debe inventar un campo gtin si la plataforma no lo expuso).
Qué pasa al re-enriquecer
- Se hace snapshot de una nueva versión del enriquecimiento (la salida anterior se retiene en History)
- Las últimas 3 versiones por producto se conservan automáticamente — las más viejas se purgan
- Puedes restaurar cualquier versión pasada desde la pestaña History del producto
- Si el producto fue editado manualmente, el diálogo de re-enrich te pide que teclees OVERWRITE para confirmar que pierdes las ediciones manuales
Coste y créditos
Cada llamada de enriquecimiento consume un enrichment credit. El bulk enrich consume un crédito por entidad en el batch.
| Plan | Asignación mensual de créditos |
|---|---|
| Starter | 250 |
| Growth | 2.500 |
| Pro | 25.000 |
| Agency | 100.000 (pool compartido entre todas las tiendas del tenant) |
El uso de créditos se muestra en Org → Plan con desglose por tienda y un sparkline de burn-rate diario. Re-enriquecer la misma entidad consume otro crédito — no hay reprocesado gratis.
Si te quedas sin créditos a mitad de mes, los enriquecimientos se encolan pero no se despachan; el dashboard muestra un banner con la sugerencia de upgrade. El contenido enriquecido existente sigue sirviendo — solo las peticiones nuevas se pausan.
Dónde se expone el contenido enriquecido
- Dentro del dashboard — para que tú revises, edites, hagas rollback
- Vía endpoints de API — variantes
.llm,.jsonld,.metapor producto - Vía
/.well-known/llms.txten tu dominio de tenant — un manifiesto de catálogo que los crawlers LLM pueden obtener - Vía el script de embed — widgets de FAQ inyectados + JSON-LD en las páginas de tu storefront
- Vía el Schema Injector — BC Scripts API en BigCommerce, Theme App Extension en Shopify (consulta Schema Injector)
Diferencias por plataforma en lo que se propaga
Una vez enriquecido, el paso de propagación empuja el resultado de vuelta al storefront. Ambas plataformas reciben el mismo contenido, pero los campos destino difieren:
BigCommerce — targets de propagación
page_title(meta title) en/v3/catalog/products/:idmeta_descriptionen el mismo endpointmeta_keywordsysearch_keywords(campo solo de BC)- Metafield personalizado
clione_jsonlden el namespaceclione, escrito vía/v3/catalog/products/:id/metafields - Para categorías: el mismo
page_title/meta_description/meta_keywordsen el recurso category
Shopify — targets de propagación
metafields.global.title_tag(esto mapea al título SEO en el storefront)metafields.global.description_tag(mapea a la meta description)metafields.clione.jsonld(el blob JSON-LD renderizado, servido por la theme app extension)metafields.clione.faq(payload de FAQ consumido por el widget de FAQ)- Los
tagsno se modifican — Shopify usa los tags para merchandising y Clione no los sobrescribe
Consulta Concepts → Signal Propagation para la matriz completa de propagación.
Resolución de problemas
Toast "Out of credits" tras un bulk enrich — El batch se procesó parcialmente; las entidades restantes están encoladas. Sube de plan o espera al reseteo del ciclo de créditos (día 1 del mes natural, UTC).
El re-enrich produce scores muy diferentes — El LLM tiene temperatura > 0 por diseño (para evitar overfitting). Fija tu razonamiento rellenando la sección de evidencia del Enrichment Wizard — consulta Entendiendo los scores.
Enriquecido pero el storefront sigue mostrando meta tags viejos — La propagación corre asíncrona, ~30 segundos tras terminar el enriquecimiento. Haz hard refresh a la página del storefront; si sigue vieja tras 5 minutos, revisa la vista Verification para ver el error de propagación.
La escritura de metafield en BigCommerce falla con 422 — El namespace del metafield debe ser clione. Si creaste un namespace distinto manualmente, bórralo y deja que Clione lo recree. El dashboard lo muestra como error de propagación.
El enriquecimiento de Shopify corre pero el JSON-LD no aparece en la página en vivo — La theme app extension no está activada. Abre Theme Editor → App embeds → activa "Clione JSON-LD". Consulta Schema Injector — Shopify.
Consulta Concepts → Enrichment Pipeline para la referencia técnica completa.
Mapa de artefactos por tipo de entidad
Aunque las categorías de artefactos son las mismas entre products, categories/collections y pages, los campos exactos difieren ligeramente:
| Campo | Product | Category (BC) / Collection (Shopify) | Page |
|---|---|---|---|
core_identity | ✓ | ✓ | ✓ |
recommended_for | ✓ | ✓ (audiencia para la categoría) | — |
decision_logic | ✓ | ✓ | — |
objection_handler | ✓ | — | — |
target_audience | ✓ | ✓ | ✓ |
purchase_intent | ✓ | — | — |
content_purpose | — | — | ✓ |
seasonal_relevance | ✓ | ✓ | — |
meta_title | ✓ | ✓ | ✓ |
meta_description | ✓ | ✓ | ✓ |
search_keywords (EN+ES) | ✓ | ✓ | ✓ |
quality_perception | ✓ | — | — |
value_for_money | ✓ | — | — |
price_positioning | ✓ | — | — |
typical_competitors | ✓ | — | — |
content_freshness | — | — | ✓ |
related_entities | ✓ | ✓ | ✓ |
embedding (1536-dim) | ✓ | ✓ | ✓ |
jsonld (Product) | ✓ | — | — |
Las categorías y pages no obtienen un blob JSON-LD hoy — está previsto. Sí obtienen meta + razonamiento + keywords + embedding, que es lo que usa la propia búsqueda interna de Clione.
Comprobar el enriquecimiento antes de la propagación
El auto-propagator corre ~30 segundos tras terminar el enriquecimiento. Si quieres inspeccionar el resultado antes de que aterrice en tu storefront, puedes pausar la auto-propagación por tienda: toggle Store → Settings → Auto-propagate. Con él desactivado, el enriquecimiento corre pero la propagación queda encolada para aprobación manual — revisa la entidad en la pestaña Propagation y pulsa Push to storefront cuando esté lista.
La auto-propagación está activada por defecto porque la fricción de aprobar cada enriquecimiento mata el throughput. Desactívala solo cuando estás haciendo QA de un catálogo sensible (p. ej. moda de lujo, categorías reguladas).
Idioma y locale del enriquecimiento
El LLM produce salida en el mismo idioma que el input por defecto. Si tu descripción de producto está en inglés, la copia enriquecida está en inglés. Si está en español, la copia está en español.
Para tiendas bilingües:
- Las search keywords siempre son bilingües (EN + ES) sin importar el idioma del input.
- Meta title / meta description coinciden con el idioma del input. Para obtener un meta en español sobre una descripción en inglés, usa el campo Enrichment Wizard → Locale override.
- El JSON-LD usa el mismo idioma que el meta.
La propagación multi-locale (escribir el meta español en un Market locale español de Shopify) está en el roadmap.
Ciclo de vida del chip de enrichment
Mientras un enriquecimiento está corriendo, un chip persistente aparece en la barra superior del dashboard:
- Queued — job aceptado, esperando un worker.
- Running — llamada al LLM en vuelo; progreso mostrado como
N / totalpara bulk. - Propagating — empujando al storefront.
- Done — se cierra automáticamente tras 5 segundos.
- Error — se queda visible hasta que lo cierres; pulsa para ver los detalles del error.
El chip persiste entre navegaciones de página para que puedas salir y volver. Cerrar la pestaña cancela el chip pero no cancela el job de fondo — vuelve a abrir el dashboard para encontrar el resultado.
Side-effects del enriquecimiento
Enriquecer un producto no:
- Cambia el precio o el inventario del catálogo upstream.
- Dispara una notificación de oferta o webhook a tus clientes.
- Afecta el ranking en motores de búsqueda inmediatamente (Google tarda semanas en re-crawlear).
- Modifica tu tema.
Enriquecer sí:
- Escribe el meta title y meta description de vuelta a la plataforma vía Admin API.
- Escribe el metafield JSON-LD (BC: namespace
clione; Shopify: namespaceclione). - Dispara una comprobación automática de Verification 30 segundos después.
- Consume un enrichment credit.
- Crea un snapshot de versión.
- Actualiza el vector index de Clione para búsqueda semántica.
Enriquecimiento por-tienda vs cross-store
El enriquecimiento es por tienda. El mismo SKU en una tienda BC y en una tienda Shopify se enriquece por separado, y el contenido resultante puede diferir ligeramente porque los inputs (descripción, nombre del vendor, etc.) difieren.
Si quieres enriquecimiento consistente entre tiendas con catálogos solapados (común en setups de agencia), el flujo es:
- Enriquece en la tienda principal.
- Exporta el enriquecimiento desde la pestaña Raw JSON del detalle del producto.
- Usa la API para escribir el mismo enriquecimiento en la tienda secundaria. Consulta developers/products-api.
El clonado de enriquecimiento cross-store está en el roadmap.