Guía de ingesta de datos

Aprende a estructurar y cargar tus datos en Rayuela para obtener las mejores recomendaciones posibles.

Los payloads de API pública (recomendaciones, interacciones) siguen el OpenAPI en GET /api/v1/public-openapi.json. El modelo de datos multi-tenant y el pipeline interno de entrenamiento LTR están descritos en rayuela_backend/docs/DATA_ARCHITECTURE.md (§11.1–11.2: LTR interno vs contrato HTTP público).

Tipos de Datos

Rayuela necesita tres tipos principales de datos para generar recomendaciones efectivas:

Productos

Catálogo de productos con características, precios y metadatos.

Usuarios

Perfiles de usuarios con preferencias y características demográficas.

Interacciones

Historial de comportamiento: vistas, compras, ratings, etc.

Estructura de Productos

Campos requeridos y opcionales para productos

Campos Requeridos

{
  "externalId": "prod_123",         // ID único en tu sistema
  "name": "Smartphone XYZ",        // Nombre del producto
  "description": "Descripción...",  // Descripción detallada
  "price": 599.99,                 // Precio actual
  "category": "electronics"        // Categoría principal
}

Campos Opcionales (Recomendados)

{
  "brand": "Apple",
  "inStock": true,
  "averageRating": 4.5,
  "numRatings": 1250,
  "tags": ["smartphone", "5g", "premium"],
  "attributes": {
    "color": "black",
    "storage": "128GB",
    "screen_size": "6.1",
    "weight": "174g"
  }
}

Tip: Cuantos más atributos proporciones, mejores serán las recomendaciones basadas en contenido.

Estructura de Usuarios

Información de usuarios para personalización

Campos Requeridos

{
  "externalId": "user_456"  // ID único en tu sistema
}

Campos Opcionales (Mejoran Personalización)

{
  "preferredCategories": ["electronics", "books"],
  "priceRangeMin": 50,
  "priceRangeMax": 1000,
  "attributes": {
    "age": 28,
    "gender": "M",
    "location": "Madrid",
    "interests": ["technology", "gaming"],
    "subscription_tier": "premium"
  }
}

Estructura de Interacciones

Eventos de comportamiento del usuario

Campos Requeridos

{
  "external_user_id": "user_456",
  "external_product_id": "prod_123",
  "interaction_type": "view",  // view, purchase, rating, cart_add
  "value": 1.0                 // Intensidad (1.0 para view, 5.0 para rating)
}

Tipos de Interacción

view

Usuario vio el producto (value: 1.0)

purchase

Usuario compró el producto (value: cantidad)

rating

Usuario calificó el producto (value: 1-5)

cart_add

Usuario agregó al carrito (value: 1.0)

Carga Masiva

POST

/ingestion/batch

Para cargar grandes volúmenes de datos, usa el endpoint de ingesta masiva:

curl -X POST "https://rayuela-backend-e7apihrdoa-uc.a.run.app/api/v1/ingestion/batch" \
     -H "X-API-Key: sk_prod_tu_api_key" \
     -H "Content-Type: application/json" \
     -d '{
       "products": [
         {
           "externalId": "prod_001",
           "name": "Producto 1",
           "price": 99.99,
           "category": "electronics"
         }
       ],
       "users": [
         {
           "externalId": "user_001",
           "preferredCategories": ["electronics"]
         }
       ],
       "interactions": [
         {
           "external_user_id": "user_001",
           "external_product_id": "prod_001",
           "interaction_type": "purchase",
           "value": 1.0
         }
       ]
     }'

⚠️ Límites: Máximo 1000 elementos por tipo en cada request. Para volúmenes mayores, divide en múltiples requests.

Mejores Prácticas

Evitar

• IDs externos que cambien con el tiempo
• Productos sin categoría o con categorías muy genéricas
• Cargar solo interacciones de compra (incluye vistas)
• Atributos con valores inconsistentes

Siguientes Pasos

API de Ingesta Masiva Ejemplos de Código Obtener Recomendaciones Ver Dashboard