Endpoint - Búsqueda

El corazon del API. Devuelve resultados rankeados por relevancia + sinónimos aplicados + reglas de curación. Diseñado para llamarse desde el navegador con la API key publica.

GET /v1/{tenant}/search

Parámetros

Parámetro	Tipo	Default	Descripción
q	string	(requerido)	El termino de búsqueda del cliente
limit	int	20	Máximo de hits a devolver (1-100)
offset	int	0	Para paginar
source	string	(default del tenant)	Slug del data source (productos, recetas, etc.)
filter	string	(vacio)	Filtros estilo in_stock=true AND price<50
sort	string	(vacio)	Campos de orden, e.g. price:asc
facets	string	(vacio)	Facetas a calcular separadas por coma

Cabeceras opcionales

Cabecera	Descripción
Accept-Language	Para detectar idioma del cliente (alimenta Smart i18n)
X-Mibizum-Session	UUID de sesión del cliente (lo genera el SDK; permite que Smart relacione queries de la misma sesión)

Ejemplo

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

Respuesta 200

{
  "query": "hidratante",
  "query_norm": "hidratante",
  "hits": [
    {
      "id": "sku-001",
      "name": "Crema hidratante facial con acido hialuronico",
      "description": "Para piel seca...",
      "price": 24.90,
      "currency": "EUR",
      "image_url": "https://cdn.../sku-001.jpg",
      "url": "https://tu-tienda.com/crema-hidratante-facial",
      "in_stock": true,
      "categories": ["facial", "hidratacion"],
      "score": 1.42,
      "highlight": {
        "name": "Crema <mark>hidratante</mark> facial..."
      }
    }
  ],
  "total": 12,
  "limit": 5,
  "offset": 0,
  "facets": {},
  "applied_synonyms": [],
  "applied_rules": [],
  "ms_taken": 18
}

Campos relevantes

• score: relevancia normalizada del motor (mayor = más relevante). No es comparable entre queries distintas.
• highlight: la subcadena que matcheo envuelta en <mark>. Útil para resaltar en la UI.
• applied_synonyms: lista de sinónimos que se aplicaron a esta query (e.g. caguacate -> aguacate). Útil para diagnosticar.
• applied_rules: reglas de curación (pin / override) que afectaron al ranking. Ver Reglas.
• ms_taken: latencia del motor en milisegundos (no incluye red).

POST /v1/{tenant}/search

Misma semantica que el GET, pero acepta el cuerpo como JSON. Útil cuando los parámetros son grandes (filtros complejos):

curl -X POST https://api.mibizum.io/v1/tu-tienda/search \
  -H "Authorization: Bearer mb_pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "q": "hidratante",
    "filter": "in_stock=true AND price<30",
    "facets": ["categories", "brand"]
  }'

Errores

Código	error	Causa
400	missing_query	Falta q
400	invalid_filter	Sintaxis de filter incorrecta
400	query_too_long	q supera 200 chars
401	unauthorized	Sin Bearer o key invalida
404	tenant_not_found	El slug del tenant no existe
429	rate_limited	Has superado 300 req/min

Tips de producción

TIP

Llamar con Accept-Language desde el navegador (navigator.language) prepara el corpus para el aprendizaje IA multi-idioma. No tiene coste y rinde dividendos cuando configures Smart-i18n.

WARNING

No hagas debouncing dentro del navegador. El backend ya tiene su propio debounce configurado en el panel (Ajustes > Buscador). Hacer doble debounce genera lag perceptible.

TIP

Para previews / autocompletar, llama con limit=5 o limit=10. Para la pagina de resultados, limit=20-50. Llamadas con limit=100 rinden peor sin aportar más señal al cliente.