Volver a Documentación

API de Ingesta Masiva

Carga grandes volúmenes de datos de forma eficiente usando el endpoint de ingesta masiva.

Visión General

El endpoint de ingesta masiva permite cargar múltiples productos, usuarios e interacciones en una sola operación, optimizando el rendimiento para grandes volúmenes de datos.

Hasta 1000 elementos por tipo
Procesamiento asíncrono
Operación atómica
Endpoint Principal
POST
/ingestion/batch

Carga múltiples tipos de datos en una sola operación.

Estructura del Request

{
  "products": [
    {
      "externalId": "prod_001",
      "name": "Producto 1",
      "description": "Descripción del producto",
      "price": 99.99,
      "category": "electronics",
      "brand": "Apple",
      "inStock": true,
      "attributes": {
        "color": "black",
        "storage": "128GB"
      }
    }
  ],
  "users": [
    {
      "externalId": "user_001",
      "preferredCategories": ["electronics"],
      "priceRangeMin": 50,
      "priceRangeMax": 1000,
      "attributes": {
        "age": 28,
        "location": "Madrid"
      }
    }
  ],
  "interactions": [
    {
      "external_user_id": "user_001",
      "external_product_id": "prod_001",
      "interaction_type": "purchase",
      "value": 1.0,
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ]
}

Ejemplo de Request

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": "smartphone_001",
           "name": "iPhone 15 Pro",
           "price": 1199.99,
           "category": "electronics/smartphones",
           "brand": "Apple"
         }
       ],
       "interactions": [
         {
           "external_user_id": "user_123",
           "external_product_id": "smartphone_001",
           "interaction_type": "view",
           "value": 1.0
         }
       ]
     }'
Formato de Respuesta

Respuesta Exitosa (200)

{
  "message": "Batch ingestion initiated successfully",
  "status": "processing",
  "jobId": 123,
  "taskId": "task_abc123",
  "totalUsers": 75,
  "totalProducts": 150,
  "totalInteractions": 500
}

Respuesta con Errores Parciales (207)

{
  "message": "Batch ingestion completed with errors",
  "status": "completed_with_errors",
  "jobId": 124,
  "totalUsers": 70,
  "totalProducts": 140,
  "totalInteractions": 480,
  "errors": [
    {
      "recordType": "product",
      "externalId": "prod_invalid",
      "errorMessage": "Invalid price: must be greater than 0"
    }
  ]
}
Límites y Restricciones

Límites por Request

  • • Máximo 1000 productos
  • • Máximo 1000 users
  • • Máximo 1000 interacciones
  • • Tamaño máximo: 10MB

Límites de Rate

  • • 10 requests por minuto
  • • 100 requests por hora
  • • 1000 requests por día

Importante

Para volúmenes mayores a los límites, divide los datos en múltiples requests. La operación es atómica: si falla, ningún dato se procesa.

Reglas de Validación

Productos

  • • externalId: Requerido, único, máximo 255 caracteres
  • • name: Requerido, máximo 200 caracteres
  • • price: Requerido, debe ser mayor a 0
  • • category: Requerido, máximo 50 caracteres

Usuarios

  • • externalId: Requerido, único, máximo 255 caracteres
  • • priceRangeMin / priceRangeMax: Opcional, debe ser mayor o igual a 0

Interacciones

  • • external_user_id y external_product_id: Requeridos
  • • interaction_type: Debe ser uno de los tipos permitidos por contrato (ej: VIEW, CLICK, PURCHASE, CART, RATING)
  • • value: Requerido, debe ser mayor a 0
Códigos de Error
400
Bad Request - Datos inválidos o límites excedidos
401
Unauthorized - API Key inválida
413
Payload Too Large - Excede 10MB
429
Rate Limit Exceeded - Demasiadas requests
500
Internal Server Error - Error del servidor
Siguientes Pasos
Guía de DatosObtener RecomendacionesEjemplos de CódigoVer Dashboard