Importación de objetos personalizados mediante SFTP y sincronización con almacenes de datos

Objetivos del artículo

Puedes importar registros de objetos personalizados de forma masiva mediante 2 métodos: SFTP y Importación desde almacén de datos. Ambos métodos cargan registros sin procesar en una fuente de datos. Puedes usar los registros importados con un nuevo objeto personalizado o con un objeto existente configurado con esa fuente de datos.

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

Antes de importar, revisa Primeros pasos con objetos personalizados y la descripción general de interfaz de programación de aplicaciones (API) de objetos personalizados.

Ten en cuenta estos conceptos al configurar una importación:

• Una fuente de datos de objetos personalizados almacena los datos sin procesar que importas. Un registro de fuente de datos es un registro individual en esa fuente de datos. Estos registros se conservan en Klaviyo, para que puedas usar datos importados previamente para configurar objetos personalizados adicionales.
• 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 SFTP, necesitas el ID de una fuente de datos existente en la cuenta. Puedes crear una fuente de datos a través de la interfaz de programación de aplicaciones (API) o al configurar un nuevo objeto personalizado en Klaviyo. Para Importación desde almacén de datos, puedes crear una fuente de datos o seleccionar una existente durante la configuración de sincronización.

Método 1: importación con SFTP

Antes de subir los datos, agrega una clave pública SSH a Klaviyo y conecta el cliente SFTP con las credenciales que proporciona Klaviyo. Consulta Importar datos a través de 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

1. 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.
2. Copia el archivo config.json, que contiene data_source_id, en la nueva carpeta.
3. Después de cargar el archivo de configuración, carga los archivos de datos en la misma carpeta. Se procesarán los archivos *.csv y *.jsonl.

{company_id}/imports/custom_objects/pets/
  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. Usa nombres de columna a los que hacen referencia las asignaciones de objetos personalizados.
• Si una celda de CSV contiene texto JSON, encierra la celda entre comillas dobles y duplica cada comilla interna (p. ej., ""). El valor se importa como una cadena. Usa JSONL para conservar objetos anidados o arreglos.
• Las celdas vacías de un CSV se importan como cadenas vacías.

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 (p. ej., arreglos o valores primitivos) se omiten y se cuentan como filas omitidas.
• 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. Klaviyo extrae registros del archivo y luego los escribe en el origen de datos en lotes de hasta 500.
4. Los registros se agregan a la fuente de datos mediante el mismo proceso de ingesta de objetos personalizados que se usa para los registros enviados a través de la interfaz de programación de aplicaciones (API).
5. Recibirás una notificación de finalización (por correo electrónico o en el producto) cuando finalice la tarea.

Manejo de errores

• Klaviyo omite las filas de CSV con una cantidad incorrecta de columnas y las líneas de JSONL no válidas, y luego continúa el procesamiento. Si no se puede analizar una parte de un archivo CSV, se omiten todas las filas de esa parte.
• Revisa la notificación de finalización para ver el recuento de filas procesadas y omitidas. Las líneas JSONL no válidas se cuentan como filas omitidas; no se crea ningún archivo de errores descargable a nivel de fila para archivos JSONL.
• 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 desde almacén de datos

Resumen

Si usas Snowflake, Databricks o BigQuery, puedes configurar una sincronización con un almacén de datos para importar directamente registros de objetos personalizados. Conecta el almacén de datos, selecciona una tabla o vista y elige Objetos personalizados como el tipo de objeto de datos. Luego, elige la fuente de datos de Klaviyo que recibirá los registros.

Antes de comenzar, conecta tu almacén de datos a Klaviyo y asegúrate de que la tabla o vista que quieres sincronizar sea accesible. Para conocer los requisitos del plan y las guías de conexión, consulta Comprender la Importación desde almacén de datos en Klaviyo.

Configurando la sincronización

1. Ve a Administración de datos > Sincronización y abre la conexión de tu almacén de datos.
2. Haz clic en Agregar fuente para crear una nueva sincronización. Para editar una sincronización, abre el menú de la fila y selecciona Editar.
3. Ingresa un Nombre de sincronización y selecciona la tabla o vista del almacén en Fuente de datos. En Tipos de objetos de datos, selecciona Objetos personalizados.
4. Elige la cadencia. Para importaciones automáticas, selecciona Programar ejecución y configura la programación. Para las importaciones que inicies, selecciona Manual. Si vas a crear una sincronización nueva, haz clic en Siguiente.
5. En Detección de cambios, selecciona una columna en Detección de filas nuevas que indique cuándo se agregó o modificó cada fila. La columna debe contener un valor de fecha y hora o un valor que se pueda convertir en un valor de fecha y hora.
6. En Fuente de datos de objetos personalizados, elige el modo de fuente de datos:
   • Sincronizar con una fuente de datos existente: selecciona el destino en Selecciona una fuente de datos. Asegúrate de que los nombres de las columnas del almacén de datos coincidan con los nombres de las propiedades de la fuente usados en las asignaciones de objetos personalizados. Cambiar la fuente de datos redirige los registros sincronizados futuros a esa fuente.
   • Crear nueva fuente de datos: ingresa un Nombre de la fuente de datos único. Klaviyo sugiere Data Sync: {table_name}, que puedes cambiar. La fuente de datos se crea cuando guardas la sincronización.
7. Haz clic en Listo para crear la sincronización o en Guardar si estás editando una sincronización existente. Una nueva sincronización queda con actividad cuando se guarda. Para iniciar una importación por tu cuenta, abre la sincronización y haz clic en Ejecutar sincronización.

Comportamiento de sincronización

• Los registros se procesan en lotes de hasta 500 por llamada.
• La Importación desde almacén de datos para objetos personalizados no genera un archivo descargable de errores a nivel de fila.
• Abre la pestaña Ejecuciones de la sincronización para revisar el estado de la ejecución y el progreso del procesamiento. Abre Registros para ver detalles sobre errores de sincronización.

Después de importar

Si uno o más objetos personalizados ya están con actividad con esa fuente de datos, los registros importados se procesan usando las asignaciones de esos objetos, tal como se haría si agregaras registros de fuentes de datos a través de la interfaz de programación de aplicaciones (API).

Si todavía ningún objeto personalizado usa el origen de datos, puedes crear uno con los registros importados. Importar al menos 1 registro primero te permite obtener una vista previa de sus campos durante el mapeo. Al crear el objeto, selecciona el origen de datos usado para esta importación. Sigue Primeros pasos con objetos personalizados para terminar de configurar y publicar el objeto.