API Reference

La API REST de Mibizum es la base sobre la que se construyen el widget, el SDK JS, los adapters de plataforma y tus integraciones a medida. Esta sección documenta los endpoints publicos.

URL base

Produccion : https://api.mibizum.io/v1
Staging    : https://api.staging.mibizum.io/v1

Todos los endpoints siguen el patrón:

/v1/{tenant_slug}/{recurso}

Donde tenant_slug identifica tu instancia en Mibizum (lo defines al crear la cuenta).

Autenticación

Mibizum usa API keys con scope (publica / privada). Ver Autenticación para el detalle.

# Publica - solo lectura, segura en el navegador
curl https://api.mibizum.io/v1/tu-tienda/search?q=hidratante \
  -H "Authorization: Bearer mb_pk_live_..."

# Privada - lectura + escritura, NUNCA en frontend
curl -X POST https://api.mibizum.io/v1/tu-tienda/items/bulk \
  -H "Authorization: Bearer mb_sk_live_..."

Versionado

El segmento /v1/ es la versión mayor del API. Los breaking changes van a /v2/. Dentro de una versión mayor:

• Añadir campos nuevos es non-breaking: tu código sigue funcionando.
• Quitar campos o cambiar tipos es breaking y solo ocurre en cambio de versión mayor.

Formato de respuestas

Todas las respuestas son JSON. Las exitosas devuelven directamente el recurso o un objeto con rows + metadatos para listados:

{
  "rows": [
    { "id": "sku-001", "name": "..." }
  ],
  "total": 234,
  "page": 1,
  "page_size": 20
}

Las de error siguen un formato único:

{
  "error": "code_machine_readable",
  "message": "Descripcion humana del problema",
  "details": { /* opcional, contexto adicional */ }
}

Ver Errores para la lista completa.

Rate limiting

Por defecto cada API key tiene un rate limit de 300 requests por minuto. Las respuestas devuelven cabeceras estándar:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1716740400

Si superas el límite, recibes 429 Too Many Requests con Retry-After en segundos. Si necesitas más throughput, contacta soporte.

Endpoints principales

Recurso	Auth	Descripción
/search	publica	Buscar items
/widget/default-results	publica	Hits que el modal muestra al abrirlo sin query
/track	publica	Reportar evento (click, conversión)
/items	privada	CRUD de items del catalogo
/synonyms	privada	Gestionar sinónimos
/rules	privada	Reglas de curación (pin, override)
/smart/suggestions	privada	Sugerencias del aprendizaje IA

Cada recurso esta documentado en su sección del menu izquierdo.

Idempotencia

Las operaciones POST que crean recursos aceptan una cabecera opcional:

Idempotency-Key: tu-uuid-unico

Si envias dos veces el mismo Idempotency-Key dentro de 24h, Mibizum reconoce el segundo intento y devuelve la respuesta original sin duplicar la operación. Útil para retries seguros.

Webhooks

Mibizum no envia webhooks salientes por defecto. Si necesitas notificaciones (sync fallido, runs IA, etc.), configura un endpoint en Ajustes > Webhooks del panel. Ver Webhooks (proximamente).