Ingesta masiva de objetos personalizados

Puedes importar registros de objetos personalizados de forma global utilizando dos métodos: SFTP e Importación de almacenes de datos (DWH).  Ambos métodos te permiten cargar registros sin procesar en una fuente de datos, que luego conectas a un tipo de objeto personalizado en la interfaz de usuario de Klaviyo.

Este artículo aborda cómo funciona cada método, cómo formatear tus archivos y qué esperar durante y después de la importación.

Antes de empezar

Familiarízate con los objetos personalizados. Consulta Primeros pasos con objetos personalizados y la descripción general de interfaz de programación de aplicaciones (API) de objetos personalizados.

Hay algunas partes de la función de objetos personalizados que debes tener en cuenta al configurar la ingesta/sincronización en lote:

• Una fuente de datos de objetos personalizados es un esquema flexible, definido por el usuario. Un registro de fuente de datos representa un registro en una fuente de datos. Ten en cuenta que estos permanecen en Klaviyo, lo que te permite crear diferentes esquemas/objetos en el futuro a partir de registros de fuente de datos que cargaste en el pasado.
• Un objeto personalizado en sí consiste en un esquema de objeto y un esquema de asignación entre una fuente de datos y el objeto.
• Se pueden asignar diferentes objetos personalizados a una sola fuente de datos, utilizando la misma o diferentes asignaciones de campos.

Para importar objetos personalizados desde SFTP, necesitarás el ID de la fuente de datos donde deseas crear los registros de la fuente de datos. Puedes crearlo mediante la API o en la interfaz de usuario web al crear un nuevo objeto personalizado. Ten en cuenta que esto también se puede crear automáticamente durante el primer ciclo de sincronización de un almacén de datos para objetos personalizados.

Método 1: Importación SFTP

Fuente de datos

Identifica el ID de la fuente de datos de objetos personalizados a la que quieras dirigir la importación y crea un archivo config.json con el ID, así:

{
  "data_source_id": "01KTMWCZ8ZMNZS0HG5HQNX0H6E"
}

Estructura del directorio

Desde la raíz de SFTP, crea una nueva carpeta en /imports/custom_objects/. El nombre de la carpeta no afecta la forma en que se procesan los datos.

Copia el archivo config.json, que contiene data_source_id, en la nueva carpeta.

Coloca los archivos de datos que deseas subir en la nueva carpeta. Se procesarán los archivos *.csv y *.jsonl.

{company_id}/
  imports/
    profiles/           
    events/             
    custom_objects/     
      pets/            ← User-defined folder
     config.json        ← Configuration file with data_source_id
     pet_records.csv    ← CSV file to process
     pet_records.jsonl    ← JSONL file to process

Se rechazarán los archivos colocados directamente en custom_objects/ sin un subdirectorio. Cada importación de objetos personalizados debe estar dentro de una subcarpeta con nombre.

Formatos de archivo compatibles

Se recomienda encarecidamente usar JSONL cuando tus registros contengan datos o matrices anidados.

Formato CSV

• La primera fila debe ser una fila de encabezado. Los nombres de las columnas deben corresponder a la definición de la fuente de datos.
• El JSON anidado dentro de una celda CSV debe ir entre comillas dobles y las comillas internas deben escaparse con caracteres de comillas dobles (p. ej., "").
• Las celdas vacías se tratan como campos ausentes, no como valores nulos.

Ejemplo de CSV:

subscription_id,product_name,status,start_date
sub_001,Premium Plan,active,2025-01-15
sub_002,Basic Plan,inactive,2024-06-01

Formato JSONL

• Cada línea debe ser un objeto JSON válido ({...}).
• Las líneas que no son objetos (por ejemplo, matrices o primitivas) se omiten y cuentan como errores.
• Las líneas vacías se ignoran silenciosamente.
• Los objetos y matrices anidados se pasan y almacenan por completo.

Ejemplo de JSONL:

{"subscription_id": "sub_001", "product_name": "Premium Plan", "status": "active", "start_date": "2025-01-15"}
{"subscription_id": "sub_002", "product_name": "Basic Plan", "status": "inactive", "start_date": "2024-06-01", "metadata": {"source": "shopify", "tags": ["vip", "annual"]}}

Qué ocurre durante la importación

1. Klaviyo detecta la ruta del subdirectorio y determina que el tipo de recurso es custom_objects.
2. Klaviyo revisa si en la cuenta existe una fuente de datos de objetos personalizados con el data_source_id en config.json.
3. Los registros se extraen y procesan en lotes de hasta 500 registros por lote.
4. Cada lote se escribe en la fuente de datos a través de la misma canalización utilizada por la API en lote.
5. Recibirás una notificación de finalización (por correo electrónico o en el producto) cuando finalice la tarea.

Manejo de errores

• Se omitirán filas no válidas (CSV con formato incorrecto o líneas JSONL imanalizables). El trabajo continúa procesando el resto del archivo.
• La notificación de finalización incluye un recuento de filas omitidas y un resumen de los errores encontrados.
• Si la carpeta no tiene .config.json o el ID de la fuente de datos en la configuración no es válido, el archivo no se procesará. Para volver a intentarlo, debes subir el archivo otra vez con un nombre diferente. Los archivos antiguos se eliminarán después de 30 días.

Método 2: Importación de almacenes de datos

Resumen

Si utilizas Snowflake, Databricks o BigQuery, puedes configurar la sincronización de un almacén de datos para importar objetos personalizados directamente. El flujo de configuración es el mismo que para los perfiles y eventos: conecta tu almacén, selecciona una tabla o vista y elige Objeto personalizado como tipo de recurso.

Configurando la sincronización

1. Ve a Integraciones > Almacén de datos y abre la conexión de tu almacén.
2. Crea una nueva importación, sincroniza o edita una existente.
3. En Tipo de recurso, selecciona Objeto personalizado.
4. Selecciona la fuente de datos a la que deseas enrutar los registros.
   1. Para una fuente de datos existente: los nombres de las columnas del almacén de datos deben coincidir con la definición de la fuente de datos.
   2. Si aún no existe ninguna fuente de datos, se creará una automáticamente en la primera ejecución de sincronización y se llamará "Sincronización de datos: {sync_name}". Puedes modificar este nombre como desees. Ten en cuenta que no podrás configurar nuevos objetos hasta que se haya importado al menos un registro (para establecer el esquema de la fuente de datos).
5. Guarda y activa la sincronización.

Comportamiento de sincronización

• Los registros se procesan en lotes de hasta 500 por llamada.
• Las filas fallidas se escriben en un archivo de error descargable con detalles a nivel de fila (por ejemplo, valores con formato incorrecto, identificadores faltantes).
• Cada ejecución de sincronización genera una entrada de registro que se puede ver en la pestaña Registros de sincronización, con detalles sobre la extracción, la transformación, el progreso de la carga y cualquier error.

Después de la importación: si se utiliza una fuente de datos existente

Si uno o más objetos personalizados ya están configurados con esa fuente de datos, se crearán a partir de los nuevos registros de la fuente de datos tal como lo harían si añadieras registros de la fuente de datos a través de la API.

Si todavía no hay objetos personalizados que usen esa fuente de datos, usa el asistente de Nuevos objetos para crear un nuevo objeto y seleccionar la fuente de datos utilizada en tu sincronización. Asegúrate de que se haya importado al menos un registro para que se establezca el esquema de la fuente de datos.