Importar Clientes Masivamente

Carga multiples clientes desde un archivo Excel con validaciones automaticas.

Pasos

1. Clic en “Importar” (boton superior derecha) — se abre el modal.
2. Clic en “Descargar Plantilla” — descarga plantilla_clientes.xlsx.
3. Completa la plantilla con datos de tus clientes (ver columnas abajo).
4. Clic en “Seleccionar archivo” o arrastra el Excel al area de carga.
5. Revisa la vista previa — el sistema valida automaticamente cada fila.
6. (Opcional) Marca “Actualizar duplicados” si quieres sobrescribir clientes existentes con mismo CIF/NIF.
7. Selecciona las filas validas que quieres importar.
8. Clic en “Importar” — proceso de importacion inicia.

Columnas de la plantilla

Columna	Obligatorio	Descripcion	Ejemplo
Nombre	Si	Nombre o razon social	Acme Software, S.L.
CIF/NIF	Si	Identificador fiscal	A12345678
Email	Condicional	Email (Email O Telefono)	contacto@acme.com
Telefono	Condicional	Telefono (Telefono O Email)	+34 912345678
Direccion	Si	Domicilio fiscal	Calle Mayor 1, 3B
Codigo Postal	Si	CP	28001
Ciudad	Si	Ciudad	Madrid
Provincia	Si	Provincia	Madrid
Pais	Si	Pais	Espana
Persona Contacto	No	Responsable	Juan Perez
Notas	No	Observaciones	Cliente preferente

Validaciones automaticas

El sistema valida cada fila y muestra:

Estados de fila:

• Verde — Fila valida, lista para importar
• Amarillo — Fila con advertencias (duplicado), importable si marcas “Actualizar duplicados”
• Rojo — Fila con errores criticos, no importable

Tipos de error:

• CIF/NIF invalido (formato o letra control)
• Email y telefono vacios (se requiere al menos uno)
• Campos obligatorios vacios
• Formato de email invalido
• Formato de telefono invalido

Opciones de importacion

Opcion	Descripcion	Valor por defecto
Actualizar duplicados	Si un cliente con el mismo CIF/NIF ya existe, actualiza sus datos	No
Saltar invalidos	Ignora filas con errores y continua con las validas	Si

Como se que lo hice bien

• Modal de progreso muestra: “X clientes importados correctamente”.
• Los clientes aparecen en la lista principal.
• Toast de confirmacion con resumen: “3 importados, 1 omitido, 0 errores”.

Errores comunes

Mensaje	Causa	Solucion
”Archivo no valido”	Formato incorrecto	Usa solo archivos .xlsx o .xls
”Archivo demasiado grande”	Mas de 5MB	Divide la importacion en lotes menores
”El archivo no contiene datos validos”	Hoja vacia o sin columnas	Verifica que copiaste los datos en la plantilla
”CIF/NIF duplicado” (advertencia)	Ya existe un cliente con ese CIF/NIF	Marca “Actualizar duplicados” o omite la fila

🔧 Detalles Tecnicos — Importar Clientes

Tipos:

• CustomerImportRow — Fila parseada del Excel
• ValidationResult — Resultado de validacion por fila (isValid, errors, warnings, isDuplicate)
• ImportProgress — Estado del progreso (current, total, percentage, status, message)
• ImportOptions — Opciones de importacion (updateDuplicates, skipInvalid)
• ImportResult — Resultado final (success, failed, skipped, errors)

Flujo de validacion:

1. Parseo: parseExcelFile(file) — Lee Excel, retorna array de CustomerImportRow
2. Validacion Zod: validateCustomerRows(rows) — Aplica customerSchema a cada fila
3. Verificacion duplicados: checkDuplicates(results, userId) — Query a BD por CIF/NIF
4. Importacion: importCustomers(rows, options) — INSERT o UPDATE en lotes

Validaciones:

• Mismas reglas que Crear Cliente (customerSchema)
• Duplicados: Query por cif_nif y business_id

Componentes:

• Modal: CustomerImportModal.tsx
• Vista previa: CustomerImportPreview.tsx — Tabla con filas coloreadas
• Progreso: CustomerImportProgress.tsx — Barra de progreso animada

Utilidades:

• Plantilla: generateCustomerTemplate() en /src/utils/excelTemplateGenerator.ts
• Parseo: parseExcelFile() en /src/features/customers/utils/customerImportUtils.ts
• Validacion: validateCustomerRows() en mismo archivo
• Duplicados: checkDuplicates() — Query Supabase
• Importacion: importCustomers() — Lotes de 10 filas

Queries de diagnostico:

-- Verificar duplicados por CIF/NIF
SELECT cif_nif, COUNT(*) as count
FROM customers
WHERE business_id = '<business_id>'
GROUP BY cif_nif
HAVING COUNT(*) > 1;

-- Clientes importados en ultimos 5 minutos
SELECT * FROM customers
WHERE business_id = '<business_id>'
  AND created_at > NOW() - INTERVAL '5 minutes'
ORDER BY created_at DESC;

Limites:

• Tamano maximo archivo: 5MB
• Filas por lote: 10 (para evitar timeouts)
• Limite recomendado: 500 filas por importacion

---