API de Ingesta Masiva
Carga grandes volúmenes de datos de forma eficiente usando el endpoint de ingesta masiva.
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.
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://api.rayuela.ai/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
}
]
}'Respuesta Exitosa (200/202)
El endpoint responde de forma asíncrona: 202 con un jobId para procesar en segundo plano. Consultá el resultado del job para ver los totales finales.
{
"message": "Batch ingestion initiated successfully",
"status": "processing",
"jobId": 123,
"taskId": "task_abc123",
"totalUsers": 75,
"totalProducts": 150,
"totalInteractions": 500
}Respuesta con Errores Parciales (207)
Se devuelve cuando el procesamiento por lotes termina con errores en algunos registros: los válidos se aplican y los inválidos se reportan en errors (no hay rollback total).
{
"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 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 asíncrona y por lotes: el endpoint devuelve un jobId y procesa los datos en segundo plano. Los errores por registro se reportan en el resultado del job (HTTP 207), no de forma atómica.
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_idyexternal_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