Tu primer índice

Esta guía es para integradores que indexan vía API REST (no Magento, no vía adapter). Te lleva de catalogo vacio a buscador funcional en ~15 minutos.

1. Estructura tu catalogo

Decide que campos quieres exponer al buscador. El mínimo para que funcione:

interface Item {
  id:    string;  // unico, inmutable
  name:  string;  // lo principal que se indexa
}

Recomendado:

interface Item {
  id:           string;
  name:         string;
  description:  string;
  price:        number;
  currency:     string;
  image_url:    string;
  url:          string;
  in_stock:     boolean;
  categories:   string[];
  brand?:       string;
  tags?:        string[];
  // campos custom para filtros / facetas
  attributes?: Record<string, string | number | boolean>;
}

TIP

Indexa la descripción completa, no solo el name. Es lo que distingue un buscador "que solo busca por nombre" de uno que entiende contexto. En cosmetica, por ejemplo, los clientes buscan por ingrediente (que esta en la descripción), no por nombre del producto.

2. Subir items en bulk

Para el primer indexado:

curl -X POST https://api.mibizum.io/v1/tu-tienda/items/bulk \
  -H "Authorization: Bearer mb_sk_live_..." \
  -H "Content-Type: application/json" \
  -d @items.json

Donde items.json:

{
  "items": [
    {
      "id": "sku-001",
      "name": "Crema hidratante facial",
      "description": "Para piel seca con acido hialuronico al 2%",
      "price": 24.90,
      "currency": "EUR",
      "image_url": "https://...",
      "url": "https://...",
      "in_stock": true,
      "categories": ["facial", "hidratacion"]
    }
  ]
}

Lotes razonables

Recomendado: lotes de 500-1000 items por request. Lotes mayores aumentan el riesgo de timeout o memory pressure. Si tienes 50.000 items, pagina en 50-100 requests.

3. Sincronización incremental

Para mantener el índice al día tras el primer bulk:

Opción A - Eventos al editar

Cuando el cliente edita un producto en tu admin, llama a /items/{id} con PUT:

curl -X PUT https://api.mibizum.io/v1/tu-tienda/items/sku-001 \
  -H "Authorization: Bearer mb_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Crema hidratante facial intensiva", ... }'

Para borrar:

curl -X DELETE https://api.mibizum.io/v1/tu-tienda/items/sku-001 \
  -H "Authorization: Bearer mb_sk_live_..."

Opción B - Cron periodico

Si no tienes hooks de edición, lanza un cron cada N horas que re-sube TODO vía /items/bulk. Mibizum hace upsert (no duplica, no ralentiza).

# crontab: cada 6h
0 */6 * * * /usr/local/bin/mibizum-sync.sh

4. Verificar

Tras el bulk, espera ~30 segundos para que el motor indexe (timing depende del tamaño). Luego prueba:

curl "https://api.mibizum.io/v1/tu-tienda/search?q=hidratante&limit=5" \
  -H "Authorization: Bearer mb_pk_live_..."

Si devuelve hits, todo funciona. Si devuelve 0, revisa:

1. El campo name o description contiene la palabra que buscas?
2. El item esta marcado in_stock=true? (default: solo se muestran los en stock).
3. Han pasado al menos 30 segundos desde el bulk?

5. Optimizaciones tipicas

TIP

Añade categories siempre. Mibizum las usa para facetas y para el matching extendido. Sin categorías, pierdes la capacidad de filtrar "muestrame solo los hidratantes facial".

TIP

Indexa el HTML strippeado de la descripción, no el HTML crudo. Mibizum lo intenta strippear pero es mejor que llegue limpio. Así el <p>Para piel seca</p> se indexa como Para piel seca.

TIP

Usa attributes para los campos custom de tu industria. Lo que cuente como faceta filtrable. Cosmetica: { inci: '...', tipo_piel: 'seca' }. Moda: { talla: 'M', color: 'azul' }.

Siguiente paso

• Configura sinónimos iniciales en el panel para casos obvios de tu sector.
• Activa Smart Mibizum en modo shadow y deja correr 1-2 semanas. Después, sube a hybrid cuando confies en las sugerencias.
• Lee las guías de producción para evitar los anti-patrones comunes.