Tu primer indice

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

1. Estructura tu catalogo

Decide que campos quieres exponer al buscador. El minimo 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 descripcion 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 descripcion), 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. Sincronizacion incremental

Para mantener el indice al dia tras el primer bulk:

Opcion 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_..."

Opcion B - Cron periodico

Si no tienes hooks de edicion, lanza un cron cada N horas que re-sube TODO via /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 tamano). 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

Anade categories siempre. Mibizum las usa para facetas y para el matching extendido. Sin categorias, pierdes la capacidad de filtrar "muestrame solo los hidratantes facial".

TIP

Indexa el HTML strippeado de la descripcion, no el HTML crudo. Mibizum lo intenta strippear pero es mejor que llegue limpio. Asi 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 sinonimos iniciales en el panel para casos obvios de tu sector.
• Activa Smart Mibizum en modo shadow y deja correr 1-2 semanas. Despues, sube a hybrid cuando confies en las sugerencias.
• Lee las guias de produccion para evitar los anti-patrones comunes.