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; separado por comas, punto y coma o tabulaciones; UTF-8, con o sin BOM - 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

La importación tiene dos pasos.

Paso 1 - Elegir archivo. Elige el tipo de importación (y, para entidades, la entidad), arrastra o busca un archivo .csv o .json y pulsa Siguiente. Joryio lee los nombres de las columnas en tu navegador: la fila de encabezados de un CSV, o las claves de los primeros 50 objetos de una matriz JSON. Un archivo sin fila de encabezados, o un JSON que no es una matriz de objetos, muestra aquí un error en lugar de continuar.

Paso 2 - Asignar columnas. Una fila por cada columna del archivo, con hasta tres valores de ejemplo de las primeras filas y un desplegable Importar como. Cada columna empieza emparejada por su nombre (consulta la tabla de abajo). Una columna cuyo nombre no se reconoce empieza como Atributo personalizado con el nombre de la columna - un punto en el nombre se convierte en _, porque un punto guardaría una ruta anidada. Cambia cualquier asignación, renombra un atributo personalizado o elige No importar para omitir una columna. Atrás vuelve al paso 1 y conserva tu archivo y tus elecciones.

Iniciar importación sigue desactivado hasta que la asignación pueda importar algo:

• una importación de usuarios asigna una columna a Email o External ID - las filas sin ninguno de los dos se omiten, así que una asignación solo de teléfono no importaría nada;
• una importación de eventos asigna Nombre del evento y User ID o Email;
• una importación de entidades asigna todos los campos obligatorios;
• dos columnas no van al mismo destino, y un nombre personalizado no está vacío, no tiene . y no empieza por $.

Solo se envían las columnas que importas: una columna marcada como No importar no se escribe.

Nombres de columna reconocidos

La comparación ignora mayúsculas, espacios, _ y -, así que First Name, first_name, first-name y FirstName son el mismo nombre.

Nombre de columna	Se importa como
email, e-mail, email_address	Email
phone, phone_number, mobile, mobile_number, mobile_phone, cell, cell_phone, telephone, tel	Teléfono
external_id, externalId, user_id, userId	External ID
first_name, firstname, given_name, fname, forename	Nombre (attributes.firstName)
last_name, lastname, surname, family_name, lname	Apellido (attributes.lastName)
email_subscribe, email_subscription_status, sms_opt_in, whatsapp_consent, viber_status, ...	El estado de suscripción del canal - un nombre de canal (email, sms, whatsapp, push, viber) seguido de una palabra de estado (status, subscribe, subscription, subscribed, consent, opt_in, opted_in)

Una columna cuyo nombre dice lo contrario - email_unsubscribe, sms_opt_out, email_opted_out - nunca se detecta como estado de suscripción. En una columna así, "yes" significa que la persona se dio de baja, por lo que leerla como consentimiento la suscribiría. Se importa como atributo personalizado; para aplicarla, cambie primero sus valores a estados (por ejemplo unsubscribed) y luego asígnela a la suscripción del canal.

name y full_name no se dividen en nombre y apellido - ninguna regla divide bien todos los nombres. Se importan como atributo personalizado ({{ user.full_name }} en un mensaje). Cuando un archivo tiene dos columnas para el mismo campo (por ejemplo phone y mobile), gana el nombre que aparece primero en la lista de arriba y la otra columna queda como atributo personalizado, así que no se pierde ningún valor.

Guarda los nombres en Nombre y Apellido: de ahí leen las etiquetas de combinación estándar {{ user.firstName }} y {{ user.lastName }}, la búsqueda de contactos y el perfil. Un nombre guardado como atributo personalizado, como first_name, solo se muestra con {{ user.first_name }}.

Los mismos nombres se reconocen cuando se llama a la Imports API sin fieldMapping.

Destinos 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. Para attributes.<anything>, elige Atributo personalizado y edita el nombre.
subscriptions.email / sms / whatsapp / push / viber	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.

Números de teléfono

Envía los números de teléfono con + y el código de país

Envía siempre los números de teléfono en formato internacional completo (E.164): +, el código de país y luego el número - por ejemplo +972501234567. Un número sin + se lee con el país predeterminado para números de teléfono del espacio de trabajo; si no hay ninguno, o los dígitos se pueden leer de dos formas, se guarda sin verificar y no se usa para mensajes. Cómo se tratan los números de teléfono

Un teléfono escrito con código de país (+972501234567) se importa tal cual. Uno sin código (0501234567) se interpreta con el país predeterminado para números de teléfono del workspace; si no hay ninguno, no se convierte. Un teléfono que no es un número válido se conserva, no se descarta: se guarda como número sin verificar del contacto (phoneUnverified), el teléfono actual del contacto no cambia y el informe de la importación incluye un notice para esa fila. Nunca se envían mensajes a números sin verificar. Las sincronizaciones desde el almacén de datos siguen las mismas reglas. La exportación de contactos muestra el número sin verificar en una última columna, phoneUnverified.

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. Un teléfono por sí solo no basta: una fila que solo tiene teléfono también se omite.

• Primero externalId. Si la fila tiene externalId, Joryio busca coincidencia solo con él, dentro del espacio de trabajo. El email de la fila se escribe en ese contacto, pero no se usa para encontrarlo. Si ningún contacto tiene ese externalId, se crea un contacto nuevo.
• Si no, email. La fila busca coincidencia con el email normalizado (en minúsculas y sin espacios en los extremos). Si ningún contacto tiene ese email, se crea uno nuevo. Si hay exactamente uno, se actualiza. Si hay varios, consulta más abajo.
• El teléfono nunca sirve para vincular. Una columna phone se escribe en el contacto que la fila vinculó o creó, pero nunca se usa para encontrar uno.
• 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.

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.

Cuando varios contactos comparten un email

Una dirección de email no es única en un espacio de trabajo: una pareja o una familia pueden compartirla, o una misma persona puede existir con dos IDs de usuario. Cuando una fila tiene email pero no externalId, y más de un contacto tiene ese email:

• Se actualiza exactamente un contacto: el de actividad más reciente, es decir, el contacto cuyo perfil cambió más recientemente (en caso de empate, el creado más recientemente). El mismo archivo elige siempre el mismo contacto.
• Los demás quedan como estaban. Una importación nunca fusiona contactos y nunca los actualiza todos; de lo contrario, un nombre de la fila sobrescribiría el de otra persona.
• Una baja en la fila se aplica a todos los contactos con ese email, como se describe en Contactos duplicados.
• Un alta en la fila se aplica solo al contacto actualizado. Volver a suscribir es por contacto; los demás contactos conservan su propio estado.
• El resumen de la importación muestra cuántas filas coincidieron con varios contactos, y el informe descargable incluye cada una como notice, no como error, porque la fila sí se importó.

Para actualizar un contacto concreto, incluye una columna externalId: una fila con externalId siempre coincide con ese único contacto. Las sincronizaciones de almacenes de datos (Data Import) vinculan las filas del mismo modo.

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.

Marcar "Override unsubscribes" (solo administradores y propietarios, tras un aviso) trata el archivo como la fuente de verdad: puede volver a suscribir bajas anteriores y rebajar opt-ins confirmados. Confirmas que tienes consentimiento para contactar a esos usuarios. En cualquier caso, cada cambio que hace una importación se escribe en el historial de suscripciones del contacto con el origen import.

Contactos duplicados y "Override unsubscribes"

Las importaciones siguen las reglas de Contactos que comparten un email o un teléfono:

• "Override unsubscribes" está desactivado por defecto. Sin él, un valor subscribed para un contacto que se dio de baja antes - o cuyo email o teléfono está bloqueado por la baja de otro contacto - se ignora y se cuenta como se mantiene de baja.
• Con la opción marcada, ese contacto se vuelve a suscribir, solo ese contacto. Los demás contactos con el mismo email o teléfono siguen de baja.
• Con la opción marcada, también se anula una baja por STOP - solo para ese contacto, registrada en su historial con el trabajo de importación. En SMS, la página de importación avisa junto a la casilla y el resumen cuenta esos contactos: This contact opted out by texting STOP. Your SMS provider may keep blocking messages until they text START.
• Una importación nunca levanta un rebote duro o una queja de spam, ni un bloqueo a nivel de organización (solo el soporte de Joryio los levanta). Esas filas se cuentan aparte.
• Las bajas del archivo llegan a todos los duplicados. Todos los contactos del espacio de trabajo con el mismo email o teléfono también se dan de baja, con una entrada de historial.

Al terminar la importación, el resumen muestra cuántos contactos se forzaron (y, de ellos, cuántos eran contactos de SMS que habían enviado STOP), y cuántos se mantuvieron dados de baja, se mantuvieron por un rebote duro o queja, o por un bloqueo a nivel de organización. Las sincronizaciones de almacén de datos siguen las mismas reglas. Las sincronizaciones de tiendas (Shopify, WooCommerce, Magento) nunca vuelven a suscribir a nadie.

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, el número de filas que coincidieron con varios contactos y, cuando haya problemas o avisos, un enlace Descargar informe de errores (Descargar informe cuando también incluye avisos). El informe tiene una línea por fila: su número, su tipo (error: la fila no se escribió, o notice: se escribió, pero conviene revisarla) y el motivo; los valores identificativos aparecen ocultos. El enlace al informe 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.

Segmentar los contactos de una importación

Cada contacto que una importación de contactos crea o actualiza queda marcado con esa importación. Abre una importación de contactos finalizada con View y pulsa Crear segmento: Joryio crea un segmento llamado Imported: <file name> (<date>) con una sola condición - Vino de una importación es esa importación - y lo abre, listo para previsualizar, ajustar o usar como audiencia. El botón solo se muestra a quien puede crear segmentos.

La misma condición está disponible en cualquier segmento, audiencia de campaña y audiencia de recorrido, donde puedes elegir varias importaciones a la vez o excluirlas - consulta Vino de una importación.

Los contactos importados antes de que se publicara esta función no están marcados - el sistema no registraba qué importación los tocó -, así que un segmento de una importación antigua no coincide con nadie; vuelve a importar el archivo para marcar sus contactos. Las importaciones de eventos y de entidades no marcan contactos.

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.