Importación de objetos personalizados a través de SFTP y sincronización de almacenes de datos

Qué aprenderás

Puedes importar registros de objetos personalizados de forma masiva con 2 métodos: SFTP e importación de 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 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

Antes de importar, revisa Primeros pasos con objetos personalizados y la información general de 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, por lo que puedes usar los 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 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 SFTP, necesitas el ID de una fuente de datos existente en la cuenta. Puedes crear una fuente de datos mediante la API o mientras configuras un nuevo objeto personalizado en Klaviyo. Para la importación de 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 de SFTP

Antes de subirlo, añade una clave pública SSH a Klaviyo y conecta tu cliente SFTP con las credenciales que proporciona Klaviyo. Consulta Importa datos vía 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

1. 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.
2. Copia tu archivo config.json, que contiene data_source_id, en la nueva carpeta.
3. Sube los archivos de datos a la misma carpeta después de subir el archivo de configuración. 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

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. Utiliza los nombres de columna a los que hacen referencia las asignaciones de objetos personalizados.
• Si una celda de un CSV contiene texto JSON, incluye la celda entre comillas dobles y duplica cada comilla interna (p. ej., ""). El valor se importa como una cadena. Usa JSONL para conservar objetos o matrices anidados.
• Las celdas vacías de 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., matrices o valores primitivos) se omiten y se contabilizan como filas omitidas.
• 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. Klaviyo extrae registros del archivo y luego los escribe en el origen de datos en lotes de hasta 500.
4. Los registros se añaden al origen de datos mediante el mismo proceso de ingesta de objetos personalizados que se utiliza para los registros enviados a través de la API.
5. Recibes una notificación de finalización (correo electrónico o en el producto) cuando termina el trabajo.

Gestión de errores

• Klaviyo omite las filas CSV con un número incorrecto de columnas y las líneas 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 los recuentos de filas procesadas y omitidas. Las líneas JSONL no válidas se contabilizan como filas omitidas; no se crea ningún archivo de error descargable a nivel de fila para los 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 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 con un almacén de datos para importar registros de objetos personalizados directamente. 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 empezar, conecta el 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 Información sobre la importación de almacén de datos en Klaviyo.

Configurando la sincronización

1. Ve a Gestión de datos > Sincronización y abre la conexión de almacén de datos.
2. Haz clic en Añadir fuente para crear una nueva sincronización. Para editar una sincronización, abre el menú de fila y selecciona Editar.
3. Introduce 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 Cadence. Para las importaciones automáticas, selecciona Programar ejecución y configura la programación. Para las importaciones que inicies tú, selecciona Manual. Si vas a crear una nueva sincronización, 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 objeto personalizado, elige el Modo de fuente de datos:
   • Sincronizar con un origen de datos existente: selecciona el destino en Seleccionar un origen de datos. Asegúrate de que los nombres de las columnas del almacén coincidan con los nombres de las propiedades de origen utilizados en las asignaciones de objetos personalizados. Cambiar el origen de datos redirige los registros sincronizados futuros a ese origen.
   • Crear nuevo origen de datos: introduce un Nombre del origen de datos único. Klaviyo sugiere Data Sync: {table_name}, que puedes cambiar. El origen 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 está activa cuando se guarda. Para iniciar una importación, 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.
• Las importaciones de almacén de datos de objetos personalizados no generan un archivo de error descargable a nivel de fila.
• Abre la pestaña Ejecuciones de la sincronización para comprobar el estado de la ejecución y el progreso del procesamiento. Abre Registros para ver los detalles sobre los errores de sincronización.

Después de importar

Si uno o más objetos personalizados ya están activos con esa fuente de datos, los registros importados se procesan con las asignaciones de esos objetos, igual que se haría si se añadieran registros de la fuente de datos mediante la API.

Si todavía ningún objeto personalizado usa la fuente de datos, puedes crear uno con los registros importados. Importar al menos 1 registro primero te permite previsualizar sus campos mientras realizas la asignación. Al crear el objeto, selecciona la fuente de datos usada para esta importación. Sigue Primeros pasos con objetos personalizados para terminar de configurar y publicar el objeto.