API de recomendaciones

Documentación para obtener recomendaciones personalizadas usando machine learning.

Visión general

La API de recomendaciones de Rayuela utiliza algoritmos de machine learning para generar recomendaciones personalizadas basadas en el comportamiento del usuario, preferencias y características de los productos.

Personalización avanzada

Filtros flexibles

Respuesta en tiempo real

Recomendaciones personalizadas

POST/recommendations/personalized/query

Obtiene recomendaciones personalizadas para un usuario específico basadas en su historial de interacciones y preferencias. El cuerpo coincide con el esquema público del backend (OpenAPI: GET /api/v1/public-openapi.json). El entrenamiento LTR con target_scores y group_ids es interno al servidor; no se envía desde este endpoint.

Parámetros del request

{
  "external_user_id": "user_123",
  "recommendation_goal": "user_engagement",
  "model_variant": "standard",
  "strategy": "hybrid",
  "include_explanation": false,
  "limit": 10,
  "skip": 0,
  "context": {
    "page_type": "product_detail",
    "device": "mobile",
    "source_external_product_id": "prod_789"
  },
  "filters": {
    "logic": "and",
    "filters": [
      { "field": "category", "op": "eq", "value": "electronics" },
      { "field": "price", "op": "lt", "value": 1000 }
    ]
  }
}

Ejemplo de request

curl -X POST "https://rayuela-backend-e7apihrdoa-uc.a.run.app/api/v1/recommendations/personalized/query" \
     -H "X-API-Key: sk_prod_tu_api_key" \
     -H "Content-Type: application/json" \
     -d '{
       "external_user_id": "user_123",
       "recommendation_goal": "user_engagement",
       "model_variant": "standard",
       "strategy": "hybrid",
       "limit": 5,
       "filters": {
         "logic": "and",
         "filters": [
           { "field": "category", "op": "eq", "value": "electronics" }
         ]
       }
     }'

Respuesta

{
  "items": [
    {
      "externalId": "prod_789",
      "name": "Auriculares Bluetooth",
      "score": 0.95,
      "source": "personalized",
      "explanation": "Usuarios con patrones similares interactuaron con este producto"
    },
    {
      "externalId": "prod_456",
      "name": "Mouse Inalámbrico",
      "score": 0.87,
      "source": "trending",
      "explanation": "Producto relevante dentro de tu contexto de navegación"
    }
  ],
  "total": 2,
  "skip": 0,
  "limit": 5
}

Estrategias de recomendación

Diferentes algoritmos disponibles para generar recomendaciones

hybrid

Estrategia híbrida equilibrada para combinar relevancia y descubrimiento.

content_based

Basada en similitud de contenido y atributos de catálogo.

collab

Filtrado colaborativo basado en patrones de usuarios similares.

popularity

Productos populares y con tendencia al alza. Útil para usuarios nuevos sin historial.

Filtros disponibles

Parámetros para refinar las recomendaciones

Filtros de producto

category — categoría específica
price_min / price_max — rango de precios
brand — marca específica
in_stock — solo productos en stock
rating_min — calificación mínima

Filtros de contexto

page_type — tipo de página (home, product_detail, cart)
device — dispositivo (mobile, desktop, tablet)
location — ubicación geográfica
time_of_day — momento del día

Siguientes pasos