Carga masiva de usuarios por CSV — Anexo A-07 Nuevo
Tema: Alta de muchos usuarios a la vez a partir de un archivo CSV DRF base: 07-usuarios.md Idioma: ES Estado: Propuesta a debatir con el cliente
Resumen en pocas palabras
Hoy, para dar de alta a las personas de una organización, hay que cargarlas de a una desde el panel de administración. Para una empresa de doscientas personas eso son doscientas cargas manuales. Este anexo propone que un administrador pueda subir un archivo CSV con la lista completa y que el sistema cree todas las cuentas de una sola vez, avisándole antes qué filas están bien y cuáles tienen problemas.
La solicitud original dice que "no hay mucho que definir: es poder cargar por CSV como Memberstack". La mecánica de subir un archivo efectivamente es simple. Lo que no lo es —y es lo que este documento resuelve antes de construir— son las preguntas que aparecen apenas el archivo tiene un error:
- Doscientas personas nuevas necesitan una contraseña. ¿Quién la define? Hoy el alta exige que el administrador escriba una contraseña para esa persona. Eso no escala a doscientas y no es aceptable como práctica.
- Si el archivo trae ciento noventa filas correctas y diez con errores, ¿se carga todo, nada, o las que están bien?
- Si un email del archivo ya existe en la plataforma, ¿se ignora, se actualiza o se marca como error?
Ninguna de esas decisiones la puede tomar el equipo técnico por su cuenta: cambian lo que la persona recibe en su casilla y lo que el administrador ve en pantalla.
Cómo funciona hoy
- El administrador entra al panel de usuarios y abre "Crear usuario".
- Completa nombre, apellido, email, rol y una contraseña para esa persona.
- El sistema valida que el email no esté en uso y crea la cuenta.
- La persona ingresa con la contraseña que le definió el administrador y completa su onboarding.
Se repite el proceso una vez por persona.
Nota sobre las invitaciones por email. El documento 09-invitaciones.md describe un flujo en el que la persona recibe un email con un enlace y define ella misma su contraseña. Ese flujo está documentado pero no está construido: hoy el alta es la descripta arriba. Es relevante porque la carga masiva necesita resolver exactamente el mismo problema — cómo entra la persona por primera vez.
Qué se propone
- El administrador descarga una plantilla CSV con las columnas correctas y el formato esperado.
- Completa la plantilla con su lista de personas y la sube.
- El sistema revisa el archivo antes de crear nada y muestra una vista previa: cuántas filas están listas, cuántas tienen problemas y cuál es el problema de cada una.
- El administrador confirma.
- El sistema crea las cuentas válidas y envía a cada persona un email para que defina su propia contraseña e ingrese.
- Al terminar, el administrador ve un resumen: cuántas se crearon, cuántas se omitieron y por qué, con la posibilidad de descargar el detalle de errores para corregir y reintentar solo esas.
Cómo se vería
En el panel de usuarios, junto a "Crear usuario", aparece "Importar desde CSV".
Paso 1 — Subir el archivo
┌─────────────────────────────────────────────────────────┐
│ Importar usuarios │
│ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Arrastrá tu archivo CSV o buscalo │ │
│ └───────────────────────────────────────────────────┘ │
│ │
│ ¿No sabés qué formato usar? │
│ ↓ Descargar plantilla CSV │
└─────────────────────────────────────────────────────────┘
Paso 2 — Vista previa (antes de crear nada)
┌─────────────────────────────────────────────────────────┐
│ Revisá antes de confirmar equipo-2026.csv │
│ │
│ ✅ 187 personas listas para crear │
│ ⚠️ 13 filas con problemas — se van a omitir │
│ │
│ ───────────────────────────────────────────────────── │
│ Fila 14 ana.gomez@ Email inválido │
│ Fila 27 jperez@empresa.com Ya existe │
│ Fila 31 (vacío) Falta el nombre │
│ Fila 42 luis@empresa.com Rol inexistente │
│ ver las 13 → │
│ ───────────────────────────────────────────────────── │
│ │
│ [ Cancelar ] [ Crear las 187 personas ] │
└─────────────────────────────────────────────────────────┘
Paso 3 — Resultado
┌─────────────────────────────────────────────────────────┐
│ ✅ 187 personas creadas │
│ │
│ Cada una recibió un email para definir su contraseña │
│ e ingresar a la plataforma. │
│ │
│ 13 filas se omitieron. │
│ ↓ Descargar el detalle para corregir y reintentar │
└─────────────────────────────────────────────────────────┘
El archivo CSV
Columnas propuestas para la plantilla:
| Columna | Obligatoria | Contenido |
|---|---|---|
nombre |
Sí | Nombre de pila |
apellido |
Sí | Apellido |
email |
Sí | Debe ser único en toda la plataforma |
rol |
No | Nombre del rol tal como figura en la organización. Si se deja vacío, se asigna el rol por defecto |
No se incluye columna de contraseña: la define cada persona (ver D-07b.1). Tampoco de nivel, que arranca siempre en 1 como cualquier alta.
Actores
| Actor | Qué hace |
|---|---|
| Administrador de organización | Importa personas a su propia organización. |
| Administrador de plataforma (Existential) | Importa personas a cualquier organización, igual que hoy puede crearlas de a una. |
| Persona importada | Recibe un email, define su contraseña, ingresa y completa el onboarding — el mismo que cualquier usuario. |
| Sistema | Valida el archivo, muestra la vista previa, crea las cuentas válidas, envía los emails y devuelve el reporte. |
Casos de uso
| # | Caso | Qué pasa |
|---|---|---|
| CU-1 | Descargar la plantilla | El administrador descarga un CSV de ejemplo con las columnas correctas y una fila de muestra. |
| CU-2 | Subir y previsualizar | Sube su archivo. El sistema lo revisa sin crear nada y muestra cuántas filas están listas y el detalle de las problemáticas. |
| CU-3 | Confirmar la importación | Confirma. El sistema crea las cuentas válidas, omite las problemáticas y envía los emails de acceso. |
| CU-4 | Descargar el reporte de errores | Descarga un archivo con las filas omitidas y su motivo, para corregirlas y volver a subir solo esas. |
| CU-5 | Primer ingreso de la persona importada | Recibe el email, define su contraseña, ingresa y completa el onboarding habitual (incluido el E-Test). |
Reglas de negocio
| # | Regla |
|---|---|
| R-1 | El archivo se valida completo antes de crear ninguna cuenta. |
| R-2 | Las filas válidas se crean y las inválidas se omiten: un error en una fila no cancela la importación. (Ver D-07b.2.) |
| R-3 | El email debe ser único en toda la plataforma. Una fila con un email ya existente se omite e informa. (Ver D-07b.3.) |
| R-4 | Un administrador de organización solo puede importar personas a su propia organización. |
| R-5 | Las personas importadas se crean con nivel 1 y sin E-Mode, igual que cualquier alta. |
| R-6 | Ninguna persona importada queda con una contraseña definida por un tercero: la define ella en su primer ingreso. |
| R-7 | Toda importación deja registro de quién la hizo, cuándo, cuántas personas se crearon y cuántas se omitieron. |
| R-8 | Si el mismo email aparece dos veces dentro del archivo, se procesa la primera aparición y se omiten las siguientes. |
Lo que ya existe hoy
| Componente | Estado |
|---|---|
| Alta de usuario de a uno desde el panel | Existe |
| Validación de email duplicado | Existe |
| Roles por organización | Existe |
| Infraestructura para subir archivos (la misma de las fotos de perfil) | Existe — reutilizable |
| Envío de emails (bienvenida, recuperación de contraseña) | Existe — reutilizable |
| Flujo de "definí tu contraseña" para un usuario nuevo | Parcial — Existe el de recuperación; hay que adaptarlo al primer ingreso |
| Invitación por email descripta en el DRF 09 | Nuevo — Documentada, no construida |
| Carga masiva por archivo | Nuevo |
Decisiones a debatir con el cliente
| # | Pregunta | Impacto |
|---|---|---|
| D-07b.1 | ¿Cómo ingresa por primera vez la persona importada? Tres caminos: (a) el sistema le envía un email para que defina su contraseña —recomendado, es lo que hace Memberstack, y es lo cotizado—; (b) el CSV trae una columna de contraseña que define el administrador —desaconsejado, implica que alguien conoce la contraseña de otro—; (c) no se envía nada y cada persona usa "olvidé mi contraseña". | Bloqueante. Define el flujo completo y si hay envío masivo de emails. |
| D-07b.2 | ¿La importación es parcial (se crean las filas válidas y se omiten las erróneas, propuesta actual) o todo o nada (un solo error cancela la importación entera)? | Experiencia del administrador. |
| D-07b.3 | ¿Qué hacer con un email que ya existe en la plataforma? ¿Omitir e informar (propuesta actual), o actualizar los datos de esa persona? | Riesgo de sobrescribir datos. Actualizar no está incluido. |
| D-07b.4 | ¿Qué columnas debe tener la plantilla además de nombre, apellido, email y rol? ¿Hace falta poder asignar el líder de cada persona desde el CSV? | Agrega una columna, pero también resolver referencias entre filas del mismo archivo. No incluido. |
| D-07b.5 | ¿Cuál es el máximo de filas por archivo? La propuesta asume hasta 500 por importación. Más que eso cambia la forma de construirlo — ver el cuadro de volumen. | Alcance y esfuerzo. |
| D-07b.6 | Si se aprueba el envío de emails (D-07b.1a), ¿está bien enviar varios cientos de golpe? Conviene verificar el límite y el costo del proveedor de email actual. | Costo y entregabilidad. Pendiente de verificar. |
| D-07b.7 | ¿Conviene aprovechar este desarrollo para construir el flujo de invitaciones del DRF 09, hoy documentado pero inexistente? Comparte casi toda la mecánica con D-07b.1a, así que es el momento más barato para hacerlo. | Alcance adicional. No incluido. |
Composición del trabajo
| Pieza | Qué implica |
|---|---|
| Recibir el archivo | Subida del CSV. Se reutiliza el servicio de archivos que hoy usan las fotos de perfil. |
| Leer y validar | Interpretar el CSV, validar cada fila (formato del email, campos obligatorios, rol existente, duplicados dentro del archivo y contra la plataforma) y separar válidas de erróneas. |
| La plantilla descargable | Un CSV de ejemplo con las columnas correctas, para que nadie adivine el formato. |
| La vista previa | Mostrar el resultado de la validación antes de crear nada: cuántas filas van, cuáles no y por qué. |
| Crear las cuentas | Alta de las filas válidas respetando las mismas reglas que el alta individual. |
| El primer ingreso de cada persona | Email para que defina su propia contraseña. Es la pieza más importante y hoy no existe (ver D-07b.1): el alta actual exige que un administrador escriba la contraseña. |
| El reporte de errores | Archivo descargable con las filas omitidas y su motivo, para corregir y reintentar solo esas. |
| Registro de la importación | Quién la hizo, cuándo, cuántas se crearon y cuántas se omitieron. |
| Textos en tres idiomas y pruebas | Pantallas y mensajes en español, inglés y portugués; pruebas automatizadas, revisión y despliegue. |
El factor que más mueve el trabajo: el volumen
| Hasta ~500 por archivo (lo cotizado) | Miles por archivo | |
|---|---|---|
| Cómo funciona | El administrador sube y espera en pantalla mientras se procesa. | El procesamiento va en segundo plano: se puede cerrar la pantalla y llega un aviso al terminar, con barra de progreso. |
| Trabajo | El descripto arriba. | Se suma toda la maquinaria de procesamiento en segundo plano, seguimiento de progreso, reanudación ante fallos y aviso al terminar. Es notablemente más. |
| Cuándo se justifica | Volumen real de una organización. La carga concreta que motivó el pedido son ~300 personas. | Solo si se espera cargar organizaciones de miles de una vez. |
Se puede recortar en una primera versión: el reporte de errores descargable, reemplazándolo por el listado en pantalla si se acepta corregir a mano; y el registro histórico de importaciones, si alcanza con ver el resultado en el momento.
Inversión
USD 450 — precio cerrado por este entregable. Se contrata por separado: no depende de ningún otro documento de esta serie ni condiciona lo que se decida sobre los demás.
Incluye
- Análisis funcional y desarrollo de todo lo descripto en Composición del trabajo, incluido el email de primer ingreso.
- Plantilla CSV descargable, vista previa de validación y reporte de errores.
- Interfaz en español, inglés y portugués.
- Pruebas automatizadas, revisión y puesta en producción.
- Reuniones de definición y seguimiento durante la construcción.
- Dos rondas de ajuste sobre lo entregado.
No incluye
- Archivos de miles de filas (D-07b.5). El procesamiento en segundo plano, la barra de progreso, la reanudación ante fallos y el aviso al terminar son otro alcance y se cotizan aparte.
- Actualizar los datos de usuarios ya existentes (D-07b.3): las filas que corresponden a alguien ya registrado se omiten.
- Asignar el líder de cada persona desde el CSV (D-07b.4).
- El flujo completo de invitaciones del DRF 09 (D-07b.7).
Supuestos. Hasta 500 filas por importación —la carga concreta que motivó el pedido son unas 300 personas— y que el proveedor de email actual admite el envío de varios cientos de mensajes de una vez, sin costo adicional ni problemas de entregabilidad (D-07b.6). Eso último está pendiente de verificar; si no lo admite, se recotiza. Si alguno cambia, o se pide algo del bloque No incluye, se cotiza antes de ejecutarse.
Vale la pena saberlo: el email de primer ingreso comparte casi toda su mecánica con el flujo de invitaciones del DRF 09, hoy documentado pero no construido. Si ese flujo se va a hacer alguna vez, éste es el momento más barato para sumarlo.
Forma de pago: 50% al inicio, 50% contra entrega.
Relación con otros documentos
- 07-usuarios.md — alta de usuarios, reglas de validación y datos obligatorios.
- 09-invitaciones.md — flujo de invitación por email; hoy documentado pero no construido (ver D-07b.7).
- 03-roles.md — roles por organización, referenciados por nombre en el CSV.
- 06-niveles.md — las personas importadas arrancan en nivel 1.
- 11-entrevista.md — el E-Test que cada persona importada completa en su onboarding.
- 17-almacenamiento.md — servicio de archivos que se reutiliza para subir el CSV.
Correcciones / historial de validación
| Fecha | Versión | Cambio |
|---|---|---|
| 2026-08-02 | v1.0 | Documento inicial. Propuesta de carga masiva por CSV, con estado actual relevado sobre el código, reglas de negocio, decisiones abiertas y estimación de esfuerzo en dos opciones según volumen. Pendiente de debate con el cliente. |
| 2026-08-10 | v1.1 | Recorte de lectura: se fusiona el resumen con el planteo del problema, Qué agranda el trabajo se absorbe en No incluye y en la tabla D-07b.x, y los casos de uso pasan a tabla. Sin cambios de alcance ni de precio. |