Conceptos

Estos son los terminos que vas a encontrar en toda la documentación. Tenerlos claros desde el principio ahorra confusión.

Tenant

Tu instancia de Mibizum. Un tenant tiene:

• Un slug único (tu-tienda), inmutable tras crearlo.
• Sus propias API keys (live y test).
• Su propio catalogo, sinónimos, reglas y métricas.
• Aislado del resto de comercios.

Un comercio = un tenant en producción. Si necesitas staging, usa la mb_pk_test_ key del mismo tenant (apunta a una base de datos aislada).

Data source

Un catalogo dentro de un tenant. Por defecto cada tenant arranca con un data source productos. Si tu tienda tiene varios catalogos independientes (e.g. productos + recetas + blog), creas un data source por cada uno.

Cada data source tiene:

• Un slug (productos, recetas, posts).
• Su propio índice en el motor de búsqueda.
• Sus propios sinónimos y reglas de curación.
• Comparte API keys con su tenant.

Item

Un elemento indexado. Tiene un id único dentro del data source. La estructura es flexible (puedes tener tus propios campos), pero hay un set base que Mibizum entiende:

interface Item {
  id:            string;
  name:          string;
  description?:  string;
  price?:        number;
  image_url?:    string;
  url?:          string;
  in_stock?:     boolean;
  categories?:   string[];
  // ... cualquier campo custom que quieras anadir
}

Sinónimo

Una relación word -> [variantes]. Cuando el cliente busca cualquier variante, Mibizum aplica la word.

Tres origenes:

• manual: lo creas tu desde el panel.
• learned: lo creo el aprendizaje IA en automático (modo auto o hybrid).
• suggested: el aprendizaje IA lo propone pero no lo aplica todavia; tu decides en Aprende del cliente.

Ver Guía: Sinónimos.

Regla de curación

Una intervención manual sobre el ranking. Dos modos:

• pin: fija un producto en un puesto concreto (e.g. "para regalo, el item A va en posición 1").
• override: reemplaza completamente los resultados con una lista curada.

Útil para campanas, promos, decisiones de marketing que el ranking automático no captura. Ver API > Reglas.

Smart Mibizum

El aprendizaje IA del buscador. Cada noche analiza las búsquedas del día, detecta typos y propone sinónimos. Cuatro modos:

• off: apagado.
• shadow: detecta pero no aplica. Útil para evaluar.
• hybrid: aplica las sugerencias de alta confianza; las dudosas las propone para que confirmes.
• auto: aplica todo lo que cruce el umbral configurado.

Ver API > Sugerencias IA y Guía: Corpus.

Sessión ID

Identificador opaco de la sesión del cliente. Lo genera el SDK JS, vive en localStorage con TTL 24h. Permite que Mibizum relacione varias búsquedas del mismo cliente para detectar typos (X fallo, Y fue exito = candidato a sinónimo).

No es un identificador personal: no incluye IP, email, ni nada que identifique al cliente fuera de la sesión del navegador. Ver Aviso de privacidad.

API key publica vs privada

• Publica (mb_pk_*): lectura. Se puede exponer en frontend. Permite buscar y trackear.
• Privada (mb_sk_*): escritura. NUNCA en frontend. Permite indexar items, gestionar sinónimos, reglas.

Ver API > Autenticación.

Motor de búsqueda

El componente que indexa items y devuelve resultados rankeados. Mibizum abstrae el motor: tu hablas con el API Mibizum, no con el motor directamente. Esto permite cambios internos sin romper integraciones.

Algunas guías mencionan limitaciones del motor (e.g. tokens). Son detalles técnicos que afectan a como configurar sinónimos correctamente.