Importación masiva (CSV / JSON)

La importación masiva permite cargar datos en Joryio desde un archivo: perfiles de usuario, eventos históricos o filas de entidades personalizadas. Abre Datos → Importación masiva - /users/import - en el panel, sube un archivo CSV o JSON, asigna las columnas y Joryio lo procesa en segundo plano mientras ves el progreso.

No es lo mismo que Importación de datos

Esta página trata de cargas de archivos. El conector independiente Importación de datos, en Datos → Importación de datos, incorpora datos de usuarios desde almacenes de datos - Snowflake y BigQuery - mediante una conexión que configuras una vez. Usa la importación masiva para archivos puntuales - una exportación de CRM, una lista heredada o una carga histórica de eventos - y la importación de datos cuando la fuente de verdad está en un almacén.

Requisitos del archivo

Formatos	.csv - la primera fila contiene los encabezados - o .json - una matriz de objetos; se rechaza cualquier otro formato - .
Tamaño de carga	Hasta 100 MB por archivo desde el panel.
Filas	Hasta 1 000 000 de filas por importación; las filas por encima del límite no se procesan.
Simultaneidad	Una importación a la vez por espacio de trabajo; se rechaza iniciar una segunda mientras se procesa otra.

Los archivos se suben directamente al almacenamiento mediante una URL prefirmada y, después, un worker en segundo plano procesa el trabajo. Los archivos se eliminan después de procesarse y caducan tras 24 horas en cualquier caso.

Tipos de importación

Elige el tipo antes de cargar el archivo; cambia los destinos disponibles para asignar campos:

• Usuarios: crea o actualiza perfiles de contacto.
• Eventos: carga eventos históricos en el almacén de analítica.
• Entidades: carga filas en una de tus entidades personalizadas; tú eliges cuál.

Asignación de columnas

Después de seleccionar un archivo, puedes añadir asignaciones de campos: cada fila vincula una columna de origen - escrita exactamente como aparece en el archivo - con un campo de destino elegido de una lista.

Si no añades asignaciones, las importaciones de usuarios detectan automáticamente los campos: externalId, external_id, userId y user_id se convierten en el ID externo; email y phone se asignan a sí mismos; las columnas que parecen estados de suscripción - prefijo de canal y sufijo de estado, como email_subscription_status o sms_opt_in - establecen el consentimiento del canal, y todas las demás columnas se convierten en atributos personalizados con su propio nombre.

Con asignaciones explícitas, solo se importan las columnas asignadas. Campos de destino para importaciones de usuarios:

Destino	Significado
externalId	Tu ID de usuario estable; es el identificador preferido.
email / phone	Identificadores de contacto. El email se convierte a minúsculas y se recorta; el teléfono se normaliza a E.164.
attributes.firstName, attributes.lastName, attributes.<anything>	Atributos de perfil; selecciona Atributo personalizado... y escribe la clave.
subscriptions.email / sms / whatsapp / push	Estado de consentimiento a nivel de canal.
Group: <name> (<channel>)	Consentimiento por grupo: establece el estado del contacto en un grupo de suscripción o categoría de consentimiento concreta - se guarda como subscriptions.list.<listId>.<channel> - . Consulta Gestión de suscripciones.

Cómo se vinculan los usuarios (deduplicación e identificación)

Cada fila de usuario debe incluir un externalId o un email. Las filas que no incluyan ninguno se omiten y aparecen en el informe de errores.

• Si la fila tiene externalId, Joryio busca coincidencia con él dentro del espacio de trabajo.
• De lo contrario, busca coincidencia con el email normalizado.
• Una coincidencia actualiza el perfil existente: solo se escriben los campos presentes en la fila y los atributos que no están en el archivo no cambian. Si no hay coincidencia, se crea un contacto nuevo.

El resumen del trabajo informa ambos resultados por separado como Creados y Actualizados. Puedes volver a importar el mismo archivo sin problemas: las filas se resolverán como actualizaciones.

Estados de suscripción y seguridad del consentimiento

Las celdas de estado se interpretan de forma flexible: subscribed, true, yes y 1 significan suscrito; unsubscribed, false, no, 0 y opt_out significan no suscrito; opted_in, double_opt_in y confirmed significan aceptación confirmada. Los valores vacíos o no reconocidos no cambian el canal.

De forma predeterminada - casilla desmarcada - se aplican reglas de protección del consentimiento por canal y por grupo:

• Las bajas incluidas en el archivo siempre se aplican.
• Una importación nunca vuelve a suscribir silenciosamente una baja previa.
• Una aceptación confirmada nunca se degrada a una suscripción simple.

Al marcar «Aplicar el estado de suscripción a todas las filas...», el archivo se trata como fuente de verdad: puede volver a suscribir bajas previas y degradar aceptaciones confirmadas. Confirmas que tienes consentimiento para contactar a esas personas. En todos los casos, cada cambio que haga una importación se registra en el historial de suscripción del contacto con el origen import.

Importaciones de eventos

Los campos de destino son userId - se compara con externalId - , email, eventName, timestamp y properties.<key> para propiedades de evento. El worker aplica estas reglas:

• Cada fila necesita un eventName y un userId o email, y el usuario debe existir ya en el espacio de trabajo. Si no, la fila se omite; importa primero los usuarios.
• timestamp es opcional. Un valor que no se pueda analizar hace fallar la fila; los valores poco plausibles - más de unos 2 años en el pasado o 1 hora en el futuro - se ajustan a la hora actual, igual que en el seguimiento de eventos en vivo.
• Las propiedades tienen las mismas protecciones que la ruta /track en vivo: límites de tamaño, número de claves y profundidad, y enmascaramiento de PII.
• Las importaciones son seguras ante reintentos: volver a ejecutar el mismo trabajo no duplica eventos.

Los eventos importados llegan al mismo flujo de eventos que los eventos en vivo, por lo que son visibles para segmentos y analítica.

Importaciones de entidades

Primero elige la entidad de destino; sus campos se convierten en destinos de asignación. Sin asignaciones, las columnas se comparan directamente con los nombres de campo de la entidad. Las filas sin un campo de entidad obligatorio se omiten con un error. Si una fila tiene una columna _id o id, hace upsert - actualiza el registro existente o lo crea - ; de lo contrario, inserta un registro nuevo. El versionado y la eliminación lógica siguen los ajustes de la entidad.

Supervisar una importación

La tabla Importaciones recientes muestra cada trabajo con su tipo, formato, barra de progreso, estado y la persona que lo inició. Se actualiza automáticamente mientras haya trabajos en curso. Estados:

Estado	Significado
Pendiente / Procesando	En cola y, después, procesando el archivo por lotes.
Completado	Finalizado; revisa los contadores por fila.
Error	El trabajo falló - por ejemplo, no se encontró el archivo cargado - y se muestra el mensaje de error. Los trabajos fallidos se reintentan una vez automáticamente antes de aparecer aquí.
Caducado	Trabajo completado antiguo cuyo archivo e informe de errores se han limpiado después de 24 horas.

Haz clic en Ver en un trabajo para abrir el detalle: total de filas, contadores de Creadas / Actualizadas / Omitidas / Con error y, cuando haya problemas, un enlace Descargar errores con cada número de fila fallido y el motivo - los valores identificativos aparecen ocultos - . El enlace al informe de errores está disponible durante 24 horas después de completarse.

Una fila queda omitida al no superar la validación - identificador ausente, usuario desconocido en una importación de eventos o campo de entidad obligatorio ausente - ; con error cuenta errores de escritura reales.

Páginas relacionadas

• Importación de datos (almacenes): sincronización programada desde Snowflake o BigQuery.
• Segmentos: los atributos importados están disponibles de inmediato para segmentar.
• Gestión de suscripciones: grupos y categorías de consentimiento en los que escriben los destinos de importación por grupo.