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 seccion documenta los endpoints publicos.

URL base

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

Todos los endpoints siguen el patron:

/v1/{tenant_slug}/{recurso}

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

Autenticacion

Mibizum usa API keys con scope (publica / privada). Ver Autenticacion 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 version mayor del API. Los breaking changes van a /v2/. Dentro de una version mayor:

• Anadir campos nuevos es non-breaking: tu codigo sigue funcionando.
• Quitar campos o cambiar tipos es breaking y solo ocurre en cambio de version 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 unico:

{
  "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 estandar:

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

Si superas el limite, recibes 429 Too Many Requests con Retry-After en segundos. Si necesitas mas throughput, contacta soporte.

Endpoints principales

Recurso	Auth	Descripcion
/search	publica	Buscar items
/track	publica	Reportar evento (click, conversion)
/items	privada	CRUD de items del catalogo
/synonyms	privada	Gestionar sinonimos
/rules	privada	Reglas de curacion (pin, override)
/smart/suggestions	privada	Sugerencias del aprendizaje IA

Cada recurso esta documentado en su seccion 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 operacion. Util 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).