Manual de usuario — Xabia Woo (addon WooCommerce)
Addon: Xabia Woo v1.0.4 · Core requerido: ≥ 1.0.166 (recomendado)
Guía rápida de instalación
- Instale y active Xabia Agent Core (
v1.0.166o superior recomendado). - Instale y active Xabia Woo (
xabia-woo-1.0.4.zip) desde Plugins → Añadir nuevo → Subir plugin. - En Xabia Agent → Addons, active o sincronice la suscripción xabia-woo hasta ver Hub Polar: activa.
- Si la tienda está en el mismo WordPress, confirme que WooCommerce está activo y tiene productos publicados.
- Si la tienda está en otra web, rellene las credenciales SQL remotas y la URL pública de la tienda Woo (remoto) en el agente.
- En el agente, elija Fuente de información → Addon nativo → WooCommerce y pulse Conectar y Mapear.
- Guarde, pulse Sincronizar datos y, si usa búsqueda vectorial, Entrenar IA.
- Pruebe en Playground consultas de producto, stock, ofertas y botones de carrito antes de publicar.
Asistente CPT (≥ Core 1.0.162): con fuente addon Woo lista solo product. Remoto híbrido (≥ 1.0.163): host SQL o URL de tienda remota → catálogo remoto aunque WC esté instalado. Deep schema / curación CPT muestra metas Woo (_price, _sku, stock, etc.).
Parte 1 — Qué es y para qué sirve
1.1 Definición breve
Xabia Woo es un complemento (plugin independiente) que se instala junto a Xabia Agent Core y WooCommerce. Conecta su asistente con el catálogo de productos de la tienda para:
- Sincronizar productos publicados hacia la base de conocimiento del agente (texto y, si lo configura, vectores para búsqueda semántica).
- Responder con títulos, precios, ofertas, stock, SKU, categorías y enlaces de ficha tomados de WooCommerce.
- Gestionar productos variables (atributos y variaciones con precio/stock en el campo Resumen enriquecido).
- Mostrar botones «Añadir al carrito» a partir del tag
[ACTION:CART:ID], donde ID es el identificador numérico de la fila del producto (columna ID del conector). - Sugerir cupones publicados y vigentes cuando la IA lo considere oportuno (solo códigos reales obtenidos de la tienda; la IA no debe inventarlos).
- Registrar conversiones ligadas al chat (cuando el visitante compra tras una recomendación en la misma sesión) en la tabla de conversiones del Core.
No sustituye al ajuste de impuestos, envíos, pasarelas ni políticas legales de WooCommerce; es una capa de conversación y venta asistida sobre los datos que ya tiene en WordPress.
1.2 Qué problema resuelve
Sin este addon, un asistente puede inventar precios o productos. Con Xabia Woo, las respuestas se apoyan en consultas SQL coordinadas a product publicados y metadatos estándar (_price, _stock_status, etc.), en reglas de contexto («Oferta especial», uso de ADDON DISCOVERY) y en el carrito AJAX del tema y WooCommerce.
1.3 Identificación del producto (referencia útil)
- Tienda Polar (suscripción): https://polar.sh/xabia
- El slug del addon ante el Hub suele ser
xabia-woo(también se reconocen alias comowoo/woocommercesegún configuración del proveedor).
1.4 Requisitos imprescindibles
| Requisito | Qué significa para usted |
|---|---|
| WordPress funcionando | El Core y Xabia Woo son plugins de WordPress. |
| Xabia Agent Core instalado y activo | Sin el Core, Xabia Woo muestra un aviso y no carga la integración. |
| WooCommerce instalado y activo | Necesario cuando la tienda está en el mismo WordPress. En catálogo remoto, WooCommerce puede estar solo en la web origen y Xabia Woo lee por SQL remoto. |
| Plugin Xabia Woo instalado y activo | El conector SQL, el enriquecimiento de filas variables y el AJAX de carrito viven en xabia-woo/xabia-woo.php. |
| Suscripción Polar / Hub para el slug xabia-woo | La sincronización «premium» y las reglas de catálogo quedan validadas contra el Hub desde Xabia Agent → Addons. Sin suscripción activa, puede ver «Hub Polar: inactiva» y el botón «Sincronizar datos» deshabilitado cuando el agente usa la fuente Addon WooCommerce. |
Parte 2 — Instalación paso a paso
2.1 Antes de empezar
- Tenga los ZIP o paquetes: Xabia Agent Core, WooCommerce (desde WordPress.org o su distribuidor) y Xabia Woo.
- Confirme que su hosting permite REST / admin-ajax para el carrito y la licencia.
2.2 Orden recomendado de activación
- Xabia Agent Core → Activar.
- WooCommerce → Activar y completar el asistente mínimo de tienda si aún no lo hizo.
- Xabia Woo → Activar después del Core.
Si activa Xabia Woo sin el Core, verá un aviso en el escritorio: debe activar primero Xabia Agent Core.
2.3 Instalar Xabia Woo desde ZIP
- Entre como administrador.
- Plugins → Añadir nuevo → Subir plugin.
- Elija el ZIP de Xabia Woo.
- Instalar ahora → Activar plugin.
2.4 Comprobar que WordPress reconoce el plugin
En Plugins debe aparecer Xabia Woo. En Xabia Agent → Addons, la tarjeta «Xabia — WooCommerce» debe mostrar el estado WordPress (activo / instalado / no instalado) junto al archivo xabia-woo/xabia-woo.php.
Parte 3 — Pantalla «Addons»: suscripción Polar y licencia
Abra Xabia Agent → Addons. Allí gestiona todas las opciones comerciales del addon Woo.
3.1 Textos generales de la pantalla
- Insignia «Hub Polar: activa / inactiva» indica si la licencia incluye el addon xabia-woo según el Hub (no confundir con el solo hecho de tener el ZIP activo).
- Botón «Sincronizar licencias con el hub» fuerza una nueva comprobación para todas las tarjetas.
- «Contratar suscripción» (cuando el Hub está inactivo) abre la tienda Polar del producto Woo (no confundir con el checkout del addon MEC).
- Si ve «Add-on no incluido en el plan» con licencia Core válida: el hub no tiene
xabia-wooenaddon_activationspara su clave (falta compra del producto Woo en Polar o falta mapear el UUID del producto en el servidor del hub).
3.2 Tras comprar o renovar
- Pegue la clave de licencia si su flujo la usa en la tarjeta del addon.
- Pulse Activar / Actualizar suscripción o Sincronizar licencia.
- Recargue Addons y confirme Hub Polar: activa para Woo.
Parte 4 — Configuración del agente (fuente «Addon WooCommerce»)
Edite el agente que debe informar del catálogo o asistir la venta.
4.1 Tipo de fuente
En «Fuente de información»:
- Elija «Addons Nativos (Conector externo)» cuando el Core detecte Xabia Woo y la licencia Hub sea válida.
4.2 Selector de addon
En el desplegable de addon, elija «WooCommerce — catálogo y ventas» (slug interno woo).
4.3 Botón «Conectar y Mapear»
- Pulse «Conectar y Mapear» para una consulta de prueba (una fila) y listar columnas.
- Si Hub Polar: inactiva para Woo, verá error de licencia; corrija Addons antes de continuar.
- Aplique el preset de columnas sugerido para productos (ver tabla siguiente).
4.4 Campos típicos del preset de mapeo
| Columna SQL | Rol sugerido | ENTÉ | Notas |
|---|---|---|---|
| ID | — | Sí (identidad) | ID del post product; imprescindible para [ACTION:CART:ID]. |
| Titulo | Título | No | Nombre comercial. |
| Resumen | — | No | Extracto; en variables se amplía con opciones y stock por variante. |
| tipo_producto | — | No | Por ejemplo simple, variable. |
| SKU | — | No | Referencia. |
| Precio | — | No | Precio actual (_price). |
| Precio_regular / Precio_oferta | — | No | Para calcular descuento_porcentaje y destacar Oferta especial. |
| descuento_porcentaje | — | No | Calculado en SQL; la IA debe presentarlo como promoción explícita. |
| Stock_estado / Stock_cantidad | — | No | instock, outofstock, etc. |
| Link | URL | No | En sincronización se sustituye por permalink real. |
| Imagen_URL | Imagen | No | Se enriquece con tamaño adecuado cuando es posible. |
| Categorias | — | No | Categorías y etiquetas de producto. |
4.5 Guardar
Pulse «Guardar agente» para persistir source_type, addon_slug, mapeo y credenciales SQL si las usara en un escenario remoto.
4.6 Tienda remota sin WooCommerce local
Xabia Woo puede funcionar como catálogo remoto: el sitio del chat tiene Xabia Woo activo y licencia Hub, pero la tienda real vive en otro WordPress con WooCommerce.
En ese caso:
- Mantenga Fuente de información → Addon nativo → WooCommerce.
- Rellene las credenciales SQL remotas (Host, DB, Usuario, Contraseña y Prefijo si no es
wp_). - Rellene URL pública de la tienda Woo (remoto), por ejemplo
https://tu-tienda.com. - Pulse Conectar y Mapear, guarde y sincronice.
El chat usará los productos de la base remota. Cuando genere un botón [ACTION:CART:ID], el frontend mostrará un enlace de compra directa hacia la tienda remota (?add-to-cart=ID) en lugar de intentar añadir al carrito del WordPress local. Los productos variables normalmente llevarán a la ficha para que el visitante elija variante.
Parte 5 — Memoria, sincronización y playground
| Control | Función |
|---|---|
| «1. Sincronizar datos» | Ingesta desde el SQL Woo (y enriquecimiento de variables / enlaces). Bloqueado si Hub inactivo para este addon. |
| «2. Entrenar IA» | Embeddings según configuración del Core. |
| Playground | Pruebe preguntas de catálogo, ofertas y «añadir al carrito» antes de publicar el shortcode. |
Tras cambiar precios o stock en masa, vuelva a sincronizar (y entrene si usa vectores).
Parte 6 — Buenas prácticas en WooCommerce
- Mantenga productos publicados coherentes (precios, impuestos visibles según su plantilla).
- En variables, defina atributos claros para que el Resumen enriquecido liste combinaciones útiles.
- Los cupones que la IA puede mencionar son solo los publicados, con límite de uso y fecha no caducada; no sustituye reglas de elegibilidad por producto o email en WooCommerce.
Parte 7 — Experiencia del visitante en el chat
- La IA recibe reglas de ventas y un resumen de productos recientes cuando el proyecto usa Woo.
- Si recomienda un producto con acción de carrito, el frontend muestra un botón para añadir al carrito (requiere WooCommerce activo en la página del chat).
- Productos variables: a veces hace falta elegir variación en la ficha; el Resumen puede incluir líneas que oriente al visitante.
- Tras añadir al carrito, el visitante puede completar el pedido en WooCommerce; si la compra sigue a una recomendación en sesión, puede registrarse una conversión interna (véase la siguiente parte).
- Si el catálogo está en una tienda remota, las fichas, carrito y cupones se resuelven en el dominio configurado como URL pública de la tienda Woo (remoto).
- El Core puede traducir automáticamente fichas y contexto de producto cuando el visitante pregunta en otro idioma; el idioma del shortcode queda como respaldo de interfaz, no como bloqueo de respuesta.
Parte 8 — Conversiones y ROI (referencia)
Al activar el addon, Xabia prepara un registro ligero de conversiones (agente, pedido, importe, productos y fecha) cuando una compra en WooCommerce sigue a una recomendación reciente del chat. Sirve para análisis interno de ROI; no sustituye a los informes nativos de WooCommerce.
Parte 9 — Problemas frecuentes
| Síntoma | Qué revisar |
|---|---|
| Hub Polar: inactiva y sync bloqueado | Comprar producto Woo en Polar; en el hub configurar el producto Woo. Addons → Sincronizar licencia. |
| «Add-on no incluido en el plan» (licencia válida) | La clave Core no tiene el addon Woo activado en el hub; revise con soporte o el portal del cliente. |
| Sin productos en vista previa | ¿Hay productos publicados? ¿Prefijo SQL correcto si usa base remota? |
| El botón de carrito no hace nada | Consola del navegador; ¿WooCommerce activo en la página del chat? |
| Variable no se añade | Compruebe si falta elegir atributos; use enlace a ficha o variación según Resumen. |
Checklist rápido: Core activo → WooCommerce activo → Xabia Woo activo → Hub activa → Fuente addon + woo → Conectar y Mapear → Guardar → Sincronizar → Entrenar (si aplica) → Playground.
Parte 10 — Soporte
- Xabia / Digixop (licencias, Hub, Xabia Woo): help@xabia.ai.
- WooCommerce (pagos, envíos, temas, conflictos de terceros): soporte de su proveedor o WooCommerce.com según el caso.
Para licencia principal, tokens y cartera, consulte el Manual del Core.
Xabia AI — La web viva
Sabiduría natural con inteligencia artificial
Xabia AI está especialmente indicada para empresas y asociaciones del sector del turismo, instituciones, empresas y tiendas online que quieran incrementar su conversión.
Xabia AI está desarrollada por Digixop.
Xabia AI · Garaizar, 2 · 48004 Bilbao (SPAIN)