Cargar los datos de tu empresa

Cómo encaja esta función

La carga de datos permite que Kaleidr responda utilizando los datos de tu organización. Es una función Enterprise. El asistente de Kaleidr Studio utiliza las cargas publicadas para los miembros que han iniciado sesión. Para llevar esos datos a tu sitio web o backend se requieren tres pasos adicionales: crear una clave con permiso de lectura, realizar consultas con esa clave y comprobar que tus lugares aparezcan en las respuestas. Respuestas con tus propios datos explica todo el proceso y cómo se utilizan los datos cargados. Esta página es la referencia de la carga: solicitudes, campos, límites, errores y operaciones para retirar una versión publicada.

Esta página no trata de los archivos que añades a un mapa desde el panel Datos de Kaleidr Studio (hojas de cálculo, GeoJSON o rutas GPX). Es otra función disponible en todos los planes: consulta Conjuntos de datos en un mapa.

Hay dos formas de cargar datos; ambas utilizan el mismo proceso:

• La interfaz: la sección Datos para respuestas de IA, al final del panel Datos de cualquier mapa de Kaleidr Studio. Es la única interfaz de carga y sus controles solo se muestran a propietarios o administradores de organizaciones autorizadas. Consulta Cargar datos en Kaleidr Studio.
• La API de esta página: la interfaz realiza las mismas solicitudes. Por tanto, los formatos, límites, estados y errores descritos aquí se aplican a ambos métodos. Las versiones creadas mediante uno también aparecen en el otro.

Antes de empezar, conviene conocer tres características de la carga:

• Los datos se consultan cuando se responde una pregunta. Kaleidr consulta en ese momento la versión publicada, por lo que retirarla de publicación impide inmediatamente que las respuestas sigan utilizándola.
• Los datos solo se devuelven a tu organización. Se aíslan por organización y nunca aparecen en respuestas del mapa público de Kaleidr ni de otras organizaciones.
• Los valores nunca se inventan. Un asistente opcional propone una correspondencia de columnas utilizando el encabezado y un máximo de cinco filas de ejemplo. Después, cada fila se transforma según la correspondencia que apruebes. Si es incorrecta, debes corregirla y repetir el proceso; no se inventan precios, fechas ni nombres.

Disponibilidad

Requisito	Detalle
Plan	Enterprise. En Free y Pro, las solicitudes para cargar, publicar, volver a ejecutar y proponer correspondencias devuelven 403 vendor_data_not_on_plan. Se aplica el plan de Kaleidr de la organización, contratado y modificado en kaleidr.com/billing; Studio no tiene un plan independiente.
Rol	Propietario o administrador de la organización. En caso contrario: 403 org_admin_required.
Límites	Los establecidos en el acuerdo de tu organización: consulta Límites. GET /shared-api/datahub/limits devuelve los valores propios de tu organización.
Interfaz	La sección Datos para respuestas de IA del panel Datos de Kaleidr Studio, o la API de esta página. Ambas usan el mismo proceso y las mismas comprobaciones.

Qué plan requiere cada operación:

Operaciones	Rol	Plan
Proponer correspondencias, cargar, publicar y volver a ejecutar	Propietario o administrador	Enterprise
Consultar límites, estado de una carga y lista de versiones	Propietario o administrador	Cualquiera
Despublicar o eliminar una versión	Propietario o administrador	Cualquiera

Las operaciones de la segunda y la tercera fila siguen disponibles en cualquier plan. Así, una organización que cambie a un plan sin posibilidad de carga todavía puede ver sus datos cargados y retirarlos.

El uso de los datos también exige Enterprise, tanto en Studio como mediante integraciones. El asistente de Kaleidr Studio solo responde con la versión publicada mientras la organización tenga Enterprise. Leer esos datos en respuestas obtenidas mediante una clave API o el SDK requiere un permiso independiente: el ámbito vendor, disponible únicamente para organizaciones Enterprise. Consulta Respuestas con tus propios datos.

El contenido de la sección Datos para respuestas de IA en Studio depende del plan y de tu rol: consulta Qué muestra la sección cuando no puedes cargar datos.

Qué puede cargar tu organización

Consulta los límites antes de cargar. Esta es la solicitud que realiza la sección de Studio al abrirse.

Solicitud	GET /shared-api/datahub/limits
Quién	Propietario o administrador, en cualquier plan
Consulta	org_id, opcional: organización que se desea consultar si administras varias

curl https://api.kaleidr.com/shared-api/datahub/limits \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

Para una organización Enterprise. Se omiten deliberadamente los tres límites del ejemplo: son los establecidos en el acuerdo de cada organización, por lo que ninguna cifra genérica correspondería necesariamente a la tuya. limits siempre contiene los tres campos enteros de la tabla siguiente.

{
  "can_upload": true,
  "plan": "enterprise",
  "limits": { "…": "places, documents and artifact_mb: three integers, described below" },
  "reason": null
}

En Free y Pro, la solicitud también devuelve 200 e indica el motivo:

{
  "can_upload": false,
  "plan": "pro",
  "limits": { "places": 0, "documents": 0, "artifact_mb": 0 },
  "reason": "vendor_data_not_on_plan"
}

Campo	Tipo	Significado
can_upload	booleano	Indica si la organización puede realizar una carga.
plan	cadena o null	Plan del que proceden los límites: free, pro o enterprise.
limits.places	entero	Lugares por carga. En CSV, filas de datos.
limits.documents	entero	Documentos por carga.
limits.artifact_mb	entero	Tamaño del archivo en MiB.
reason	cadena o null	vendor_data_not_on_plan cuando can_upload es false; de lo contrario, null. Los límites son entonces todos 0.

Estas cifras son propias de tu organización: las establecidas en su contrato. Ningún límite puede superar el máximo que admite una carga: la plataforma tiene un límite técnico para cada una de las tres magnitudes y un contrato no puede elevarlo.

Estado	Significado
200	Siempre para un propietario o administrador, en cualquier plan. Por debajo de Enterprise, la respuesta contiene can_upload: false; no es un rechazo.
401	Falta el token de acceso, ha caducado o no es un token de acceso.
403 org_admin_required	La cuenta no pertenece a un propietario ni a un administrador de la organización.

Autenticación

Todas las solicitudes utilizan el token de acceso de tu cuenta de Kaleidr con sesión iniciada como token bearer:

Authorization: Bearer <account access token>

• No es una clave API. Se rechazan las claves kld_pk_… y kld_sk_…. Las claves identifican integraciones; cargar datos es una acción administrativa de la organización y requiere autenticar a una persona con un rol adecuado.
• Debe ser el token de acceso, no el token de identificación.
• Corresponde a un propietario o administrador que ha iniciado sesión y caduca con esa sesión. Esta API todavía no dispone de credenciales de larga duración. Si necesitas automatizar las cargas, contacta con Kaleidr antes de implementarlas.
• La interfaz de Studio no requiere gestionar estos tokens: utiliza la sesión del miembro conectado.

Todas las rutas de esta página dependen de https://api.kaleidr.com. Los ejemplos leen el token de una variable de entorno:

export KALEIDR_ACCESS_TOKEN='<account access token>'

Si administras varias organizaciones, añade org_id (en el cuerpo de la solicitud de carga o como parámetro de consulta ?org_id= en las demás) para seleccionar una. Si no lo indicas, se usa tu organización principal.

Datos que puedes cargar

Cada carga consiste en un archivo de texto enviado como cadena dentro de una solicitud JSON. La extensión del nombre de archivo determina cómo se interpreta.

Lo que tienes	Qué enviar	Contenido
Una lista de lugares	Un .csv con nombres de columnas fijos, sin correspondencia	Lugares
Una exportación de hoja de cálculo con una fila por noche, habitación o tarifa	Un .csv con mapping_spec	Lugares, tipos de habitación, planes tarifarios, tarifas por noche y disponibilidad
Todo estructurado de antemano	Un paquete .json	Todo lo anterior, además de horarios y documentos

Toda carga debe contener al menos un lugar.

CSV de lugares

La fila de encabezados utiliza estos nombres de columna:

Columna	Obligatoria	Notas
name	Sí	Una fila sin nombre hace fallar la carga y se identifica por número de línea.
timezone	Sí	Una zona IANA, por ejemplo Europe/London.
lat, lng	Una de las dos formas	Coordenadas que se utilizan tal como se proporcionan.
address	Una de las dos formas	Permite obtener las coordenadas cuando faltan lat y lng.
category	No	Etiqueta breve, como hotel o restaurant.
ref	No	Identificador propio de la fila; si falta, se utiliza el número de línea.

name,timezone,lat,lng,address,category
Harbor Hotel,Europe/London,51.5079,-0.0877,"1 Example Street, London",hotel
Canal House,Europe/Amsterdam,,,"Example Gracht 12, Amsterdam",hotel

Hoja con correspondencia de columnas

Una hoja con una fila por observación (propiedad, habitación, plan, fecha o precio) no puede procesarse mediante nombres de columna fijos. Envíala junto con mapping_spec, que indica qué columna corresponde a cada campo.

Property,Address,Room,Plan,Date,Nightly Rate,Available
Harbor Hotel,"1 Example Street, London",Double,Flexible,2026-11-06,189.00,4
Harbor Hotel,"1 Example Street, London",Suite,Flexible,2026-11-06,320.00,1

{
  "places": {
    "ref_from": ["Property"],
    "fields": {
      "name": "Property",
      "address": "Address",
      "timezone": { "const": "Europe/London" },
      "category": { "const": "hotel" }
    }
  },
  "room_types": { "ref_from": ["Room"], "fields": { "name": "Room" } },
  "rate_plans": { "ref_from": ["Plan"], "fields": { "name": "Plan" } },
  "daily_rates": {
    "fields": {
      "stay_date": "Date",
      "price_amount": "Nightly Rate",
      "price_currency": { "const": "GBP" }
    }
  },
  "daily_inventory": {
    "fields": { "stay_date": "Date", "units_available": "Available" }
  }
}

Reglas de correspondencia:

Parte	Significado
Secciones	places (obligatoria), room_types, rate_plans, daily_rates y daily_inventory. Incluye solo las que tengan datos en tu hoja.
ref_from	Columnas que identifican una entidad. Las filas con los mismos valores en estas columnas representan el mismo lugar, tipo de habitación o plan.
fields	Cada campo obtiene su valor de una columna. Algunos admiten una constante expresada como { "const": "value" }.

Una correspondencia solo puede establecer los campos de esta tabla. La última columna indica cuáles admiten una constante.

Sección	Campos que puede establecer la correspondencia	Admiten constante
places	name, address, timezone, category, lat, lng, overture_id	timezone, category
room_types	name	name
rate_plans	name, currency, cancellation_policy, board_basis	name, currency
daily_rates	stay_date (fecha ISO), price_amount (número no negativo), price_currency (tres letras)	price_currency
daily_inventory	stay_date, units_available (entero no negativo)	Ninguno

De esto se derivan dos reglas; incumplir cualquiera genera un error de validación:

• Se rechazan los campos que no aparecen en la tabla. El error identifica el campo e indica los admitidos por esa sección: room_types.fields.beds: not a field a mapping can set -- room_types takes name. Los datos que no pueden asignarse desde las celdas, como el número de camas o los atributos libres, deben enviarse en un paquete JSON.
• Las constantes se rechazan en los demás campos. Precios, fechas, cantidades, nombres de lugares y posiciones deben proceder de una columna del archivo: daily_rates.fields.price_amount: must name a column -- a constant cannot supply this field. Una constante solo representa un valor común a toda la hoja, como la zona horaria o la moneda.

Estos errores aparecen en la lista errors de una propuesta y en error_report cuando se procesa una carga con dicha correspondencia. La ingesta falla y no se prepara ningún dato.

Si incluyes daily_rates, también debes incluir room_types y rate_plans, porque cada tarifa pertenece a un tipo de habitación y a un plan. Si la hoja no tiene una columna de planes, asigna una constante al nombre del plan.

Las correspondencias solo se aplican a archivos .csv. Si se envía una con un .json, la ingesta falla.

Paquete JSON

Un archivo .json es un objeto que contiene cualquiera de estas listas. Los elementos se relacionan mediante ref.

{
  "places": [
    {
      "ref": "harbor",
      "name": "Harbor Hotel",
      "timezone": "Europe/London",
      "lat": 51.5079,
      "lng": -0.0877,
      "address": "1 Example Street, London",
      "category": "hotel"
    }
  ],
  "room_types": [{ "ref": "double", "place_ref": "harbor", "name": "Double" }],
  "rate_plans": [{ "ref": "flex", "place_ref": "harbor", "name": "Flexible" }],
  "daily_rates": [
    {
      "place_ref": "harbor",
      "room_type_ref": "double",
      "rate_plan_ref": "flex",
      "stay_date": "2026-11-06",
      "price_amount": 189.0,
      "price_currency": "GBP"
    }
  ],
  "daily_inventory": [
    { "place_ref": "harbor", "room_type_ref": "double", "stay_date": "2026-11-06", "units_available": 4 }
  ],
  "hours": [
    { "place_ref": "harbor", "weekday": 0, "opens": "07:00", "closes": "23:00" },
    { "place_ref": "harbor", "valid_from": "2026-12-25", "valid_through": "2026-12-25", "is_closed": true }
  ],
  "documents": [
    { "title": "Cancellation policy", "text": "Free cancellation until 18:00 on the day before arrival." }
  ]
}

Lista	Campos obligatorios	Notas
places	name, timezone y lat con lng, o address	ref debe ser único. Debe haber al menos un lugar.
room_types, rate_plans	place_ref, name	ref debe ser único dentro de la lista.
daily_rates	place_ref, room_type_ref, rate_plan_ref, stay_date, price_amount, price_currency
daily_inventory	place_ref, room_type_ref, stay_date, units_available
hours	place_ref y weekday o una fecha valid_from	weekday va de 0 a 6, donde 0 corresponde al lunes. opens y closes son horas del día.
documents	title, text	Solo texto incluido directamente.

Las listas también admiten campos opcionales con límites de tamaño: consulta Límites de campos.

Acerca de los documentos:

• Un documento se compone de title y text incluido directamente. Se ignora cualquier ubicación o clave de almacenamiento añadida: un documento no puede apuntar a un archivo.
• El campo opcional mime describe el texto. Se conserva si contiene text/plain, text/markdown o text/html; cualquier otro valor se registra como text/plain.

Los números deben ser finitos. NaN e Infinity no se aceptan como coordenadas, precios, cantidades ni dentro de campos JSON libres: la fila se identifica como errónea.

Proceso de carga

Una carga genera una ingesta (el trabajo) y una versión (el resultado versionado). Una versión tiene estado draft hasta su publicación. Al publicar, la nueva versión sustituye a la anterior de una sola vez: los lectores nunca ven datos a medio actualizar, ni existe un intervalo sin datos por el simple hecho de sustituir una versión. Para quedarse sin versión publicada es necesario despublicar la actual.

propose a mapping  ─►  stage a preview  ─►  check the result  ─►  publish
   (optional,            POST /ingests        GET /ingests/{id}     POST /ingests/{id}/publish
    for a sheet)         preview: true

later, to take a release back out:   unpublish  ─►  delete
                                      POST /releases/{id}/unpublish    DELETE /releases/{id}

1. Proponer una correspondencia (opcional)

Utiliza esta opción si tienes una hoja sin correspondencia definida. Envía el principio del archivo: el encabezado y algunas filas de datos, no toda la exportación.

Solicitud	POST /inference-api/vendor/mapping/propose
Quién	Propietario o administrador de una organización Enterprise, es decir, las mismas cuentas que pueden cargar datos.
Cuerpo	{ "csv_head": "<the first characters of your file>" }
Límite	csv_head admite entre 1 y 16 384 caracteres. Hasta 30 propuestas por cuenta y hora.
Coste	Cada propuesta consume créditos de IA de tu organización, según los tokens utilizados. Las demás solicitudes de esta página no consumen créditos.

curl -X POST https://api.kaleidr.com/inference-api/vendor/mapping/propose \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"csv_head":"Property,Address,Room,Plan,Date,Nightly Rate,Available\nHarbor Hotel,\"1 Example Street, London\",Double,Flexible,2026-11-06,189.00,4\nHarbor Hotel,\"1 Example Street, London\",Suite,Flexible,2026-11-06,320.00,1\n"}'

{
  "mapping_spec": { "places": { "ref_from": ["Property"], "fields": { "name": "Property", "address": "Address", "timezone": { "const": "Europe/London" } } }, "room_types": { "ref_from": ["Room"], "fields": { "name": "Room" } } },
  "notes": "Time zone inferred from the addresses.",
  "columns": ["Property", "Address", "Room", "Plan", "Date", "Nightly Rate", "Available"],
  "sample_result": { "places": 1, "room_types": 2, "rate_plans": 1, "daily_rates": 2, "daily_inventory": 2 },
  "errors": []
}

Cómo interpretar la respuesta:

• Comprueba especialmente sample_result. La correspondencia propuesta se aplica a las filas de ejemplo y sample_result indica cuántos elementos produjo por sección. Así detectarás una correspondencia aparentemente válida que no genera resultados antes de cargar el archivo completo.
• errors puede contener entradas incluso con una respuesta 200. Una propuesta que no se puede aplicar se devuelve igualmente con todos sus problemas a la vez, para que puedas corregirla. Ejemplos: campo obligatorio sin columna, nombre de columna inexistente, zona horaria IANA inválida o moneda que no tiene tres letras.
• Solo se toman muestras de filas completas, con un máximo de cinco. La última línea de csv_head se descarta salvo que el texto termine con un salto de línea, ya que no se puede distinguir una fila truncada de una completa.
• No se almacena nada. Puedes modificar la propuesta y enviarla en el siguiente paso.

Estado	Significado
403 org_admin_required	Tu cuenta no es propietaria ni administradora de ninguna organización.
403 vendor_data_not_on_plan	Tienes un rol de propietario o administrador, pero ninguna de tus organizaciones tiene Enterprise, el plan que permite las cargas.
422	csv_head supera los 16 384 caracteres, no incluye encabezado, repite un nombre de columna o no tiene filas completas. detail indica el motivo.
429, límite de frecuencia	La cuenta ha solicitado más de 30 propuestas en la última hora.
429, créditos de IA	Tu organización ha agotado los créditos de IA del período.
502 mapping proposal unavailable	No se pudo generar la propuesta. Inténtalo otra vez o escribe la correspondencia manualmente.

Cómo distinguir los dos errores 429

Ambos rechazos devuelven el estado 429. Examina el cuerpo de la respuesta:

	Límite de frecuencia	Créditos de IA agotados
Cuerpo	{ "detail": "at most 30 mapping proposals per hour" }	El cuerpo de cuota estándar
Cómo reconocerlo	No hay campo error; detail contiene el mensaje anterior.	"error": "quota_exceeded", con limit, used, remaining y reset_at
Qué hacer	Esperar; el límite se calcula sobre la última hora por cuenta.	Esperar hasta reset_at, añadir créditos de IA o escribir la correspondencia manualmente.

{
  "error": "quota_exceeded",
  "detail": "Usage limit reached. Please try again later.",
  "tier": "enterprise",
  "remaining": 0,
  "reset_at": "2026-11-01T04:00:00+00:00",
  "period": "month",
  "reset_in_seconds": 1296000
}

El ejemplo omite cuatro campos presentes en la respuesta. limit y used reflejan la asignación y el consumo de tu organización según su acuerdo. product y meter identifican el contador de Kaleidr Studio, no el de la API, porque la carga es una función de Studio. Ambos utilizan los mismos créditos de IA de tu organización. Comprueba error, igual que con cualquier otro rechazo por cuota.

Cómo se cobra una propuesta:

• Una solicitud rechazada (403, 422 o 429 por límite de frecuencia) no consume créditos. Una solicitud rechazada con 422 por su muestra también cuenta para el límite de 30 por hora.
• Una propuesta que no pudo generarse porque no llegó ninguna respuesta (502) no consume créditos.
• Una propuesta cuya respuesta no se pudo utilizar (también 502) consume los tokens de esa respuesta.
• Una propuesta devuelta con entradas en errors sí se generó y se cobra como cualquier otra.

En Studio, los mensajes son «Has alcanzado el límite horario de propuestas de correspondencia. Inténtalo más tarde o edítala manualmente» y «Los créditos de IA de tu organización para este período se han agotado. Todavía puedes definir la correspondencia manualmente». Una correspondencia escrita manualmente no requiere propuesta ni consume créditos de IA.

2. Preparar una vista previa

Solicitud	POST /shared-api/datahub/ingests
Quién	Propietario o administrador, Enterprise
Encabezado	Idempotency-Key, de 8 a 128 caracteres, obligatorio

Campo del cuerpo	Tipo	Valor predeterminado	Significado
filename	cadena, hasta 200 caracteres	Obligatorio	Debe terminar en .csv o .json. La extensión determina cómo se procesa.
artifact	cadena	Obligatorio	Texto original del archivo.
source	"csv", "api" o "manual"	"csv"	Etiqueta que indica la procedencia; no selecciona el analizador. "json" no es válido y devuelve 422.
mapping_spec	objeto, hasta 64 KB	Ninguno	Correspondencia de columnas de una hoja. Omítelo en un CSV de lugares o un paquete JSON.
preview	booleano	false	true prepara los datos y se detiene para permitir su revisión. false publica al terminar de procesarlos.
org_id	UUID	Tu organización principal	Organización para la que se realiza la carga.

curl -X POST https://api.kaleidr.com/shared-api/datahub/ingests \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: places-2026-10-10-a" \
  -d '{
    "filename": "places.csv",
    "source": "csv",
    "preview": true,
    "artifact": "name,timezone,lat,lng,address,category\nHarbor Hotel,Europe/London,51.5079,-0.0877,\"1 Example Street, London\",hotel\n"
  }'

{
  "ingest_id": "5f0c2a1e-…",
  "release_id": "a81d77b0-…",
  "status": "pending",
  "status_url": "/shared-api/datahub/ingests/5f0c2a1e-…",
  "dispatched": true
}

Idempotency-Key se aplica a tu organización. Reenviar la misma clave devuelve la ingesta que ya se creó con ella, con dispatched: false, en vez de crear otra. Utiliza una clave nueva cuando quieras preparar otra vista previa, por ejemplo después de modificar una correspondencia: reutilizarla devolvería la ingesta anterior.

dispatched indica si esta solicitud inició el procesamiento. En una ingesta nueva, false significa que no ha empezado y permanece en pending; iníciala con la operación de reejecución.

Utiliza preview: true en la primera carga y siempre que cambie la correspondencia.

Una carga cada vez y un límite por hora. Se rechaza una nueva carga mientras se procesa otra de la misma organización o cuando la organización ya ha iniciado 30 cargas en la última hora:

Estado	detail	Significado	Qué hacer
409	org_ingest_in_progress	Otra ingesta de tu organización tiene el estado running.	Consulta su estado hasta que pase a succeeded o failed; luego reenvía la carga con la misma Idempotency-Key.
429	ingest_rate_limited	Tu organización creó 30 ingestas durante la última hora. Las vistas previas cuentan.	Espera y vuelve a enviar. Para comprobar una correspondencia, utiliza la solicitud de propuesta, en lugar de preparar vistas previas repetidamente.
413	request_body_too_large	La solicitud completa supera los 32 MiB.	Envía un archivo más pequeño. Consulta Límites.

Enviar de nuevo un Idempotency-Key ya utilizado no constituye otra carga: devuelve la ingesta existente y nunca se rechaza con los códigos 409 o 429 indicados arriba. El cuerpo no se compara con el primero; por eso, se descarta cualquier archivo diferente enviado con una clave reutilizada. Sin embargo, la solicitud se valida antes de buscar la clave, por lo que una repetición puede rechazarse con 413, con 403 org_admin_required o vendor_data_not_on_plan, o con 422 por cualquiera de los límites. La clave se recuerda mientras exista su versión de datos. Cuando se elimina o se retira automáticamente, la misma clave inicia una carga nueva.

3. Comprobar el resultado

Solicitud	GET /shared-api/datahub/ingests/{ingest_id}
Quién	Propietario o administrador, cualquier plan

curl https://api.kaleidr.com/shared-api/datahub/ingests/5f0c2a1e-… \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

{
  "ingest_id": "5f0c2a1e-…",
  "release_id": "a81d77b0-…",
  "status": "succeeded",
  "attempts": 1,
  "row_counts": {
    "places": 1,
    "room_types": 0,
    "rate_plans": 0,
    "daily_rates": 0,
    "daily_inventory": 0,
    "hours": 0,
    "documents": 0
  },
  "error_report": null,
  "created_at": "2026-10-10T09:12:04Z",
  "started_at": "2026-10-10T09:12:20Z",
  "finished_at": "2026-10-10T09:12:41Z"
}

status pasa de pending a running y después a succeeded o failed.

• Cuando el estado es succeeded, row_counts muestra la cantidad de datos interpretados por tipo. Compárala con la prevista antes de publicar.
• Cuando el estado es failed, error_report.errors enumera las filas que no pudieron leerse y explica el motivo. Se muestran hasta 200 entradas y error_report.error_count contiene el total. Una ingesta fallida no modifica la versión publicada.

{
  "status": "failed",
  "error_report": {
    "errors": [
      "places[1]: missing lat/lng -- supply coordinates, or an address to geocode from",
      "places[2]: unknown timezone 'London'"
    ],
    "error_count": 2
  }
}

Las cargas son indivisibles: si falla la validación de una sola fila, no se prepara ningún dato. Corrige el archivo y vuelve a cargarlo con una Idempotency-Key nueva.

4. Publicar

Solicitud	POST /shared-api/datahub/ingests/{ingest_id}/publish
Quién	Propietario o administrador, Enterprise
Cuerpo	Ninguno

curl -X POST https://api.kaleidr.com/shared-api/datahub/ingests/5f0c2a1e-…/publish \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

La respuesta tiene el mismo formato que la preparación, con status: "pending". Solo pueden publicarse las ingestas preparadas con preview: true que hayan alcanzado succeeded.

Al publicar, el archivo se procesa de nuevo. Se utiliza el mismo archivo y la misma correspondencia, por lo que las cantidades y los identificadores coinciden con la vista previa. Solo puede cambiar la posición de un lugar definido únicamente por dirección, ya que se geocodifica de nuevo y sus coordenadas pueden variar ligeramente si se encuentra una coincidencia mejor.

Vuelve a consultar el estado. La ingesta regresa a pending, se procesa y termina en succeeded. En ese momento se publica la versión y la anterior pasa a estar sustituida.

Interpreta aquí un 409 como «ya está en marcha», no como un fallo que deba reintentarse. La solicitud de publicación no utiliza Idempotency-Key ni la necesita. Si la primera solicitud agotó el tiempo de espera en tu lado pero se completó en Kaleidr, el reintento devuelve 409 ingest_is_not_a_preview, o 409 publish_already_in_progress si las solicitudes coincidieron. Ambos significan que la publicación ya está en proceso o ha terminado. Comprueba el estado de la ingesta en vez de volver a solicitar la publicación.

Hay un 409 diferente: org_ingest_in_progress indica que se está procesando otra carga de tu organización, por lo que esta publicación no comenzó. Espera a que la otra ingesta alcance succeeded o failed y vuelve a solicitar la publicación.

Publicación en un solo paso

Envía preview: false u omite preview para publicar al terminar de leer el archivo, sin solicitud de publicación independiente. Es útil para cargas periódicas cuya correspondencia ya se ha comprobado.

Reiniciar una ingesta bloqueada

Solicitud	POST /shared-api/datahub/ingests/{ingest_id}/dispatch
Quién	Propietario o administrador, Enterprise

Utilízalo cuando una ingesta permanezca en pending (por ejemplo, porque dispatched era false) o tenga failed por motivos ajenos a los datos. Una ingesta se procesa como máximo tres veces.

Estado	Significado
409 ingest_already_succeeded	No hace falta hacer nada.
409 ingest_already_running	Ya se está procesando.
409 ingest_attempts_exhausted	Se han utilizado los tres intentos. Vuelve a cargar con una Idempotency-Key nueva.
409 org_ingest_in_progress	Se está procesando otra ingesta de tu organización. Espera a que termine y vuelve a intentarlo.
404 ingest_not_found	No existe ninguna ingesta con ese identificador en tu organización, o su versión está eliminándose o ya se ha eliminado. No hay nada que reiniciar.

Consultar las versiones

Solicitud	GET /shared-api/datahub/releases
Quién	Propietario o administrador, cualquier plan
Consulta	status, opcional: draft, published, superseded, failed o deleting. Cualquier otro valor devuelve 422 unknown_release_status. org_id es opcional.

curl "https://api.kaleidr.com/shared-api/datahub/releases?status=published" \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

[
  {
    "id": "a81d77b0-…",
    "status": "published",
    "published_at": "2026-10-10T09:15:02Z",
    "superseded_at": null,
    "created_at": "2026-10-10T09:12:04Z",
    "state": "published",
    "ingest_id": "5f0c2a1e-…"
  }
]

Campo	Tipo	Significado
id	UUID	Identificador de la versión. Se usa en las solicitudes para despublicar y eliminar.
status	cadena	draft, published, superseded, failed o deleting.
published_at	fecha y hora o null	Momento de publicación.
superseded_at	fecha y hora o null	Momento en que dejó de ser la versión actual: sustitución, despublicación o caducidad de la vista previa.
created_at	fecha y hora	Momento en que se aceptó la carga.
state	cadena	Acciones disponibles para la versión. Consulta la tabla siguiente.
ingest_id	UUID o null	Ingesta que produjo la versión. Se usa para consultar el estado y publicar.

state es similar a status, pero distingue dos tipos de borrador para que el cliente sepa qué acciones ofrecer sin otra consulta:

state	status	Significado	Acción disponible
processing	draft	Carga en cola o en procesamiento, incluso una publicación directa o una vista previa cuya publicación está en curso.	Esperar. Se puede eliminar.
preview	draft	Vista previa preparada y pendiente de una decisión.	Publicar o eliminar.
published	published	Versión utilizada para responder consultas.	Despublicar.
superseded	superseded	Sustituida, despublicada o vista previa caducada.	Eliminar.
failed	failed	No se pudo leer la carga.	Eliminar.
deleting	deleting	Eliminación en curso.	Ninguna.

La lista contiene las 50 versiones más recientes, comenzando por la más nueva. Como máximo puede existir una versión published por organización, o ninguna después de despublicar. Una versión en eliminación no figura en la lista salvo que consultes ?status=deleting y desaparece de todas las listas cuando la eliminación termina.

Retirar una versión

Existen dos operaciones distintas: despublicar retira la versión publicada del servicio, mientras que eliminar borra una versión que no está publicada. Ambas pueden realizarlas propietarios o administradores con cualquier plan, para que una organización pueda retirar sus datos incluso si ya no tiene permiso de carga. No requieren cuerpo ni Idempotency-Key, y pueden repetirse sin riesgo.

En Kaleidr Studio

Cada fila de la lista Versiones de la sección Datos para respuestas de IA ofrece la acción apropiada y solicita confirmación antes de ejecutarla. Las organizaciones que abandonaron Enterprise conservan esta lista y las dos acciones para sus propietarios y administradores mientras tengan versiones almacenadas; los pasos de carga se sustituyen por el mensaje «La carga de datos forma parte del plan Enterprise».

Etiqueta de fila	Acción	Confirmación	Resultado visible
Publicada	Despublicar	«¿Despublicar esta versión? Kaleidr AI dejará de responder con estos datos hasta que publiques otra versión. Esta versión no podrá volver a publicarse».	«Despublicando…» y luego «Despublicada. Kaleidr AI ya no responde con estos datos». La fila pasa a Sustituida.
Borrador, Sustituida, Fallida	Eliminar	«¿Eliminar esta versión? Se eliminarán la versión y todo lo generado a partir de ella. Esta acción no puede deshacerse».	«Eliminando…» y luego «Versión eliminada». La fila desaparece.
En procesamiento	Ninguna

Cada confirmación incluye el botón de la acción correspondiente y otro de Cancelar. La interfaz no ofrece Eliminar para una versión publicada; la API muestra: «Esta versión está publicada. Despublícala antes de eliminarla». La lista de Versiones se describe en detalle.

Despublicar una versión

Solicitud	POST /shared-api/datahub/releases/{release_id}/unpublish
Quién	Propietario o administrador, cualquier plan
Cuerpo	Ninguno
Consulta	org_id, opcional

curl -X POST https://api.kaleidr.com/shared-api/datahub/releases/a81d77b0-…/unpublish \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

{ "release_id": "a81d77b0-…", "status": "superseded" }

La versión deja de estar en servicio en cuanto se devuelve la respuesta. Esto implica lo siguiente:

• Tu organización no tendrá ninguna versión publicada hasta que publique otra. La versión anterior no se restaura. Las respuestas siguen basándose en conocimiento general y no indican que se han retirado tus datos.
• La versión no puede volver a publicarse. Para recuperar los mismos datos, vuelve a cargar el archivo y publícalo.
• La versión permanece en la lista como superseded, desde donde ya puedes eliminarla. Si no lo haces, se elimina automáticamente.

Estado	detail	Significado
200		La versión pasa a superseded. Repetir la operación devuelve el mismo 200, también si ya estaba en superseded, por ejemplo porque una publicación más reciente la sustituyó.
403	org_admin_required	La cuenta no es de un propietario ni administrador de la organización.
404	release_not_found	No existe una versión con ese identificador en tu organización o se está eliminando.
409	release_not_published	La versión es un borrador o ha fallado; nunca estuvo en servicio y no se puede despublicar.

Eliminar una versión

Solicitud	DELETE /shared-api/datahub/releases/{release_id}
Quién	Propietario o administrador, cualquier plan
Cuerpo	Ninguno
Consulta	org_id, opcional

curl -X DELETE https://api.kaleidr.com/shared-api/datahub/releases/a81d77b0-… \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

HTTP/1.1 202 Accepted

{ "release_id": "a81d77b0-…", "status": "deleting", "dispatched": true }

La eliminación borra la versión, el archivo cargado y todo lo generado a partir de él por Kaleidr. No puede deshacerse.

• Antes de eliminar una versión publicada hay que despublicarla. El intento devuelve 409 release_is_published. Se pueden eliminar las demás versiones: vistas previas, versiones sustituidas o fallidas y cargas todavía en procesamiento.
• La respuesta es 202 y la eliminación termina poco después. Desde que se devuelve, la versión tiene estado deleting: deja de aparecer en la lista, no se puede publicar y su ingesta devuelve 404 ingest_not_found. Esto también se aplica a la consulta de estado y al reintento de procesamiento.
• dispatched indica si la solicitud inició la eliminación. Si es false, empezará automáticamente poco después; también puedes reenviar la solicitud.
• Repetir la operación es seguro. Mientras se elimina, devuelve el mismo 202. Al completarse, la versión deja de existir y devuelve 404 release_not_found. Interpreta ese 404 como «ya eliminada».

Estado	detail	Significado
202		La versión está deleting. Un reintento devuelve el mismo estado hasta que termina.
403	org_admin_required	La cuenta no pertenece a un propietario ni administrador.
404	release_not_found	No existe una versión con ese identificador, incluidas las que ya se eliminaron.
409	release_is_published	La versión está publicada. Despublícala antes de eliminarla.

Para confirmar que ha terminado la eliminación, consulta las versiones con ?status=deleting: una lista vacía indica que ya no hay eliminaciones pendientes.

Las versiones antiguas se eliminan automáticamente

No necesitas eliminar manualmente una versión que ya no está activa. Kaleidr lo hace de forma equivalente a la solicitud de eliminación:

Versión	Momento de eliminación
superseded: sustituida o despublicada	30 días después de su sustitución o despublicación
Vista previa nunca publicada	Caduca a los 14 días y se elimina 30 días después
failed	30 días después de finalizar su último intento de procesamiento
published	Nunca, mientras siga publicada

Qué no abarca la eliminación

Una versión eliminada deja de utilizarse en las respuestas generadas después de completar la eliminación. Sin embargo, la eliminación no afecta a las respuestas almacenadas temporalmente en caché, las transcripciones guardadas, las copias de seguridad ni al texto ya enviado a un proveedor de modelos cuando se procesaron tus datos. Consulta Qué no abarca la eliminación.

Límites

Límites definidos en tu acuerdo

El tamaño y las cantidades permitidas por carga están definidos en el acuerdo de tu organización. La plataforma establece un máximo técnico para cada límite; tu contrato no puede superar esos máximos.

Límite	Enterprise	Si se supera
Tamaño de artifact	Establecido en el acuerdo	422 al cargar
Filas de CSV, sin contar el encabezado	Establecido en el acuerdo	422 al cargar
Lugares en un paquete JSON	Establecido en el acuerdo	422 al cargar
Documentos en un paquete JSON	Establecido en el acuerdo	422 al cargar

• GET /shared-api/datahub/limits devuelve los límites de tu organización.
• Free y Pro no tienen límites de carga porque no pueden cargar datos. Las solicitudes devuelven 403 vendor_data_not_on_plan.
• Los límites se aplican por organización. Publicar sustituye por completo la versión anterior, por lo que cada límite afecta tanto a una carga como a sus datos publicados.

Una carga que supera cualquiera de estos límites devuelve 422 con los motivos, cada uno indicando el límite y el plan. Se usa <count> para la cantidad enviada y <limit> para el límite de tu organización:

{ "detail": { "errors": ["<count> places exceed the limit of <limit> (enterprise plan)"] } }

Los otros tres mensajes tienen el mismo formato: <count> documents exceed the limit of <limit> (enterprise plan), csv has more than <limit> rows; the places limit is <limit> (enterprise plan) y artifact is <size> MB; the limit is <limit> MB (enterprise plan). Si el archivo supera el tamaño máximo, no se sigue procesando y solo se devuelve ese motivo.

Límites para todas las organizaciones

Límite	Valor	Si se supera
Tamaño total de la solicitud de carga	32 MiB	413 request_body_too_large
Tipos de habitación por carga	10 000	422 al cargar un paquete JSON; ingesta fallida en una hoja con correspondencias
Planes tarifarios por carga	10 000	422 al cargar un paquete JSON; ingesta fallida en una hoja con correspondencias
Filas de horarios en un paquete JSON	25 000	422 al cargar
Filas de tarifas nocturnas y disponibilidad juntas por carga	200 000	Ingesta fallida: daily facts: <count> rows exceed the cap of 200000
Texto total de los documentos por carga	Aproximadamente 600 000 caracteres como máximo; menos si se reparten entre muchos documentos	Ingesta fallida: documents: chunk count exceeds the cap of 500
Anidamiento del JSON enviado	Se rechazan estructuras demasiado anidadas	422 al cargar
mapping_spec	64 KB	422 al cargar
filename	200 caracteres, con extensión .csv o .json	422 al cargar
Cargas en procesamiento por organización	1	409 org_ingest_in_progress (al cargar, publicar y reejecutar)
Cargas nuevas por organización	30 por hora	429 ingest_rate_limited
csv_head de una propuesta	16 384 caracteres	422
Propuestas	30 por cuenta y hora; cada una consume créditos de IA	429: consulta Cómo distinguir los dos errores 429
Intentos de procesamiento por ingesta	3	409 al reejecutar
Vista previa nunca publicada	14 días	409 al publicar
Versión que ya no está activa	30 días	Eliminación automática

El límite de la solicitud es mayor que el del archivo porque este se envía como cadena dentro de JSON y los caracteres de escape aumentan su tamaño. Las solicitudes que superan 32 MiB se rechazan con 413 antes de procesarse. Si el archivo supera el límite de tu organización, aunque la solicitud quepa, se devuelve 422.

Superar un límite de tamaño o cantidad devuelve 422 con una lista de hasta 200 motivos. Por ejemplo, el error al superar un límite de filas común a todas las organizaciones es:

{ "detail": { "errors": ["10001 room_types exceed the cap of 10000"] } }

Un JSON demasiado anidado para analizarlo devuelve la misma estructura:

{ "detail": { "errors": ["upload is nested too deeply"] } }

El límite CSV cuenta todas las filas, independientemente de su contenido. Una hoja con una fila por noche puede llegar rápidamente al máximo; envía conjuntos mayores de tarifas y disponibilidad como paquete JSON, donde los lugares, documentos, tipos de habitación, planes tarifarios y horarios se cuentan al cargar.

Límites de campos

Cada valor tiene un tamaño máximo. El texto se mide en caracteres. Los valores JSON libres (objetos o matrices que proporcionas) se miden en bytes una vez serializados como JSON.

Lista	Campo	Límite
Todas las listas	ref, place_ref, room_type_ref, rate_plan_ref	128 caracteres
places	name	200 caracteres
places	category	100 caracteres
places	timezone	64 caracteres
places	overture_id (opcional)	128 caracteres
places	address	2048 bytes como JSON
places	schema_org (objeto opcional)	16 384 bytes como JSON
room_types	name	200 caracteres
room_types	amenities (matriz opcional), attributes (objeto opcional)	8192 bytes como JSON, cada uno
rate_plans	name	200 caracteres
rate_plans	currency (opcional)	3 caracteres
rate_plans	cancellation_policy (opcional)	2000 caracteres
rate_plans	board_basis (opcional)	100 caracteres
rate_plans	attributes (objeto opcional)	8192 bytes como JSON
hours	note (opcional)	500 caracteres
documents	title	300 caracteres

El momento en que se informa de un límite depende de los datos enviados:

• Un paquete JSON se valida durante la carga. La solicitud devuelve 422 y cada motivo identifica la fila y el campo, por ejemplo places[3]: name is longer than 200 characters o room_types[0]: amenities is larger than 8192 bytes as JSON.
• Un CSV de lugares o una hoja con correspondencias se valida al procesar la ingesta. La ingesta termina en failed y muestra los mismos motivos en error_report.errors.

Un valor JSON libre que contiene NaN o Infinity genera el error <list>[<row>]: <field> holds a non-finite number.

Caducidad de las vistas previas

Una vista previa que nunca se publica se retira 14 días después de terminar su preparación. Pasa a superseded: permanece temporalmente en la lista, pero ya no puede publicarse. Intentar publicarla devuelve 409 no_previewed_release_to_publish. Para continuar, realiza otra carga. Como cualquier versión sustituida, se elimina automáticamente 30 días después, aunque puedes eliminarla antes.

Notas sobre los campos

timezone es obligatorio para cada lugar y afecta a las respuestas. Las tarifas y la disponibilidad se interpretan según el calendario local del lugar: «esta noche» en un hotel de Sídney es una fecha diferente de «esta noche» en Londres. Si tu exportación no tiene columna de zona horaria, asigna una constante:

{ "timezone": { "const": "Australia/Sydney" } }

Elige la zona con cuidado. Una zona incorrecta produce respuestas acertadas durante buena parte del día pero erróneas cerca de la medianoche. Si falta o no es una zona IANA válida, se informa de un error.

Proporciona coordenadas cuando dispongas de ellas. Un lugar con lat y lng se utiliza exactamente como se envió. Cuando solo tiene una dirección, se intenta localizar; si la coincidencia no es suficientemente fiable, se rechaza la fila en vez de adivinar su ubicación, y deberás proporcionar coordenadas. Es preferible declarar una ubicación no resuelta que colocar un marcador en el sitio equivocado.

Volver a cargar la misma exportación es seguro. En una hoja con correspondencias, los identificadores se generan a partir de las columnas indicadas en ref_from; la misma exportación produce los mismos identificadores. Una nueva versión sustituye a la anterior, no se suma a ella.

Cada versión es independiente y completa. No hereda datos de la anterior. Si omites los lugares del mes pasado, dejarán de aparecer en las respuestas cuando publiques el nuevo archivo.

Envía texto en UTF-8. Se rechazan archivos ZIP, comprimidos con gzip o PDF renombrados con extensión .csv o .json.

Errores

Los errores de las solicitudes de carga tienen el formato { "detail": "<code>" }, salvo cuando se devuelve una lista de motivos.

Estado	detail	Significado
401		El token de acceso falta, ha caducado o no es válido como token de acceso.
403	org_admin_required	La cuenta no es de un propietario o administrador de la organización.
403	vendor_data_not_on_plan	La organización no dispone de Enterprise. Se devuelve en cargas, publicaciones y reejecuciones. Las operaciones de lectura, despublicación y eliminación no se rechazan por el plan.
404	ingest_not_found	No existe esa ingesta en tu organización, o su versión se está eliminando o ya se eliminó.
404	release_not_found	No existe esa versión en tu organización. Se devuelve al despublicar o eliminar, también tras una eliminación completada.
409	release_not_published	Se intentó despublicar una versión en borrador o fallida.
409	release_is_published	Se intentó eliminar una versión publicada. Primero hay que despublicarla.
409	ingest_conflict	Coincidieron dos cargas con la misma Idempotency-Key. Reintenta la solicitud.
409	ingest_is_not_a_preview	La ingesta no se preparó como vista previa o ya se solicitó su publicación.
409	ingest_already_running	La ingesta ya se está procesando.
409	no_previewed_release_to_publish	La vista previa falló, no ha terminado o ha caducado.
409	publish_already_in_progress	Coincidieron dos publicaciones. Una de ellas ya está en curso.
409	ingest_already_succeeded	Se solicitó reejecutar una ingesta terminada.
409	ingest_attempts_exhausted	Se solicitó reejecutar tras agotar tres intentos.
409	org_ingest_in_progress	Otra ingesta de la organización se está procesando. Ocurre al cargar o reejecutar; espera a que termine.
413	request_body_too_large	La solicitud de carga supera 32 MiB. Las de publicación, reejecución y lectura tienen un límite de 1 MiB.
422	{ "errors": [ … ] }	El archivo o la correspondencia superan un límite, un campo excede su tamaño máximo, el JSON está demasiado anidado o no se puede leer como CSV o JSON. Cada motivo es una frase. Los límites del plan identifican límite y plan.
429	ingest_rate_limited	La organización inició 30 cargas en la última hora.
422	Lista de validación	Falta un campo o está mal formado: ausencia de Idempotency-Key, extensión incorrecta o source fuera de los tres valores permitidos.
422	unknown_release_status	El filtro status no corresponde a ninguno de los cinco valores admitidos.

Un archivo que supera el límite de tamaño de tu organización devuelve 422 con el motivo en errors. El código 413 indica que la solicitud completa supera su límite y tiene el cuerpo { "detail": "request_body_too_large" }.

La solicitud de propuesta tiene sus propios errores, descritos en Proponer una correspondencia. Se rechaza con 403 org_admin_required o vendor_data_not_on_plan si la cuenta no tiene permiso de carga, y con 429 si se agotaron las propuestas por hora o los créditos de IA de la organización.

Funciones no disponibles actualmente

• Actualizaciones incrementales. No existe una operación de inserción o actualización (upsert), de eliminación de registros individuales ni de «cambios desde». Una versión sustituye por completo a la anterior; una versión entera puede despublicarse o eliminarse.
• Volver a publicar una versión anterior. Una versión sustituida o despublicada no puede volver a activarse. Debes cargar el archivo de nuevo.
• Correspondencias guardadas. La correspondencia se envía en cada carga y no puede guardarse ni reutilizarse mediante un identificador.
• Conectores. Kaleidr no importa automáticamente datos desde bases de datos, sistemas de reservas ni servicios de hojas de cálculo.
• Cargas de archivos binarias o multipartes. El archivo se envía como cadena dentro del cuerpo JSON.

Páginas relacionadas

• Respuestas con tus propios datos: proceso completo, planes, límites, comprobación y función independiente para añadir conjuntos de datos a un mapa en todos los planes.
• Autenticación y ámbitos: crear la clave que permite leer estos datos.
• Errores: catálogo de errores de toda la plataforma.