Conceptos

Estos son los terminos que vas a encontrar en toda la documentacion. Tenerlos claros desde el principio ahorra confusion.

Tenant

Tu instancia de Mibizum. Un tenant tiene:

• Un slug unico (tu-tienda), inmutable tras crearlo.
• Sus propias API keys (live y test).
• Su propio catalogo, sinonimos, reglas y metricas.
• Aislado del resto de comercios.

Un comercio = un tenant en produccion. 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 indice en el motor de busqueda.
• Sus propios sinonimos y reglas de curacion.
• Comparte API keys con su tenant.

Item

Un elemento indexado. Tiene un id unico 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
}

Sinonimo

Una relacion 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 automatico (modo auto o hybrid).
• suggested: el aprendizaje IA lo propone pero no lo aplica todavia; tu decides en Aprende del cliente.

Ver Guia: Sinonimos.

Regla de curacion

Una intervencion manual sobre el ranking. Dos modos:

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

Util para campanas, promos, decisiones de marketing que el ranking automatico no captura. Ver API > Reglas.

Smart Mibizum

El aprendizaje IA del buscador. Cada noche analiza las busquedas del dia, detecta typos y propone sinonimos. Cuatro modos:

• off: apagado.
• shadow: detecta pero no aplica. Util 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 Guia: Corpus.

Session ID

Identificador opaco de la sesion del cliente. Lo genera el SDK JS, vive en localStorage con TTL 24h. Permite que Mibizum relacione varias busquedas del mismo cliente para detectar typos (X fallo, Y fue exito = candidato a sinonimo).

No es un identificador personal: no incluye IP, email, ni nada que identifique al cliente fuera de la sesion 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 sinonimos, reglas.

Ver API > Autenticacion.

Motor de busqueda

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 guias mencionan limitaciones del motor (e.g. tokens). Son detalles tecnicos que afectan a como configurar sinonimos correctamente.