Ingesta masiva de objetos personalizados

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

Este artículo cubre 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

Para familiarizarte con los objetos personalizados, consulta Primeros pasos con los objetos personalizados y la descripción general de la API de objetos personalizados.

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

• 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 persisten en Klaviyo, lo que te permite crear diferentes esquemas/objetos en el futuro a partir de los registros de fuentes de datos que hayas cargado en el pasado.
• Un objeto personalizado en sí consiste en un esquema de objeto y un esquema de asignación entre un origen de datos y el objeto.
• Se pueden asignar diferentes objetos personalizados a un solo origen de datos, utilizando la misma o diferentes asignaciones de campos.

Para importar objetos personalizados de SFTP, necesitarás el ID del origen de datos donde quieras crear registros de origen de datos. Puedes crearlo a través de 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 de SFTP

Fuente de datos

Identifica el ID de la fuente de datos de los objetos personalizados al 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 a cómo se procesan los datos.

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

Coloca los archivos de datos que quieras cargar 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

Los archivos colocados directamente en custom_objects/ sin un subdirectorio se rechazarán. Cada importación de objeto personalizado debe estar dentro de una subcarpeta con nombre.

Formatos de archivo admitidos

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

Formato CSV

• La primera fila debe ser una fila de encabezado. Los nombres de las columnas deben coincidir con la definición del origen 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 se almacenan en su totalidad.

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 comprueba si existe en la cuenta 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 el origen de datos a través de la misma canalización utilizada por el API masivo.
5. Recibes una notificación de finalización (correo electrónico o en el producto) cuando termina el trabajo.

Gestión de errores

• Se omiten lasfilas no válidas (CSV mal formado o líneas JSONL no analizables). 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 de nuevo con un nombre diferente. Los archivos antiguos se eliminarán después de 30 días.

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

Introducción

Si usas Snowflake, Databricks o BigQuery, puedes configurar una sincronización de 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. Dirígete a Integrations > Data Warehouse y abre la conexión al almacén.
2. Crea una sincronización de importación o edita una existente.
3. En Tipo de recurso, selecciona Objeto personalizado.
4. Selecciona la fuente de datos a la que quieras dirigir los registros.
   1. Para un origen de datos existente: los nombres de las columnas del almacén de datos deben coincidir con la definición del origen de datos.
   2. Si aún no existe ningún origen de datos, se creará uno automáticamente en la primera ejecución de sincronización y se llamará «Sincronización de datos: {sync_name}». Puedes modificar este nombre como quieras. Ten en cuenta que no podrás configurar nuevos objetos hasta que se haya importado al menos un registro (para establecer el esquema del origen 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 con errores se escriben en un archivo de errores descargable con detalles de nivel de fila (por ejemplo, valores con formato incorrecto o identificadores ausentes).
• Cada ejecución de sincronización genera una entrada de registro visible en la pestaña Registros de la 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 un origen de datos existente

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

Si aún no hay ningún objeto personalizado que use ese origen de datos, usa el asistente para crear un nuevo objeto y selecciona el origen de datos utilizado en tu sincronización. Asegúrate de que se haya importado al menos un registro para que se establezca el esquema del origen de datos.