Importación y Exportación CSV y XML para PrestaShop — Guía completa

DF CSV & XML Pro es un motor de importación/exportación universal para PrestaShop 8 y 9. Conecta cualquier archivo CSV o XML con tu tienda mediante un mapeo visual de columnas, guarda cada configuración en un perfil reutilizable y puede recuperar automáticamente los flujos de tus proveedores desde FTP, SFTP o una URL. Esta guía cubre la instalación, la creación de perfiles, los formatos de columna esperados, la programación por cron, los registros y la resolución de problemas.

Instalación

Ve a Módulos > Gestor de módulos > Subir un módulo, envía el archivo dfcsvpro.zip y haz clic en Instalar. Una vez instalado, aparece una pestaña DF CSV Pro en Parámetros avanzados.

Crear un perfil

Un perfil describe una operación completa: sentido (importación o exportación), entidad, formato, origen, mapeo de columnas, opciones y programación. Se relanza en un clic o se dispara automáticamente por cron. Haz clic en Nuevo perfil: un asistente te guía en cuatro pasos.

1. General

Elige el sentido (importación / exportación), la entidad, el formato (CSV o XML) y el idioma de destino. Para CSV, ajusta el delimitador (o deja la detección automática), la codificación (UTF-8, ISO-8859-1 o Windows-1252), el número de líneas a omitir antes de la cabecera y el separador multivalor (coma por defecto). Para XML, puedes indicar el nodo de elemento o dejar que el módulo lo detecte.

Entidades disponibles en importación: productos, combinaciones, categorías, clientes, stock y precios. En exportación: productos, categorías, clientes, pedidos.

2. Origen

Selecciona de dónde procede el archivo (importación) o dónde depositar el resultado (exportación): subida manual, URL (HTTP/HTTPS), FTP, SFTP o ruta local. Para FTP/SFTP, indica host, puerto, usuario y contraseña, y usa el botón Probar conexión para validar antes de guardar.

3. Mapeo visual

Sube un archivo de ejemplo (o recupéralo desde el origen remoto): el módulo detecta las columnas, muestra una vista previa de las primeras filas y asocia automáticamente cada columna al campo correcto de PrestaShop gracias a un reconocimiento FR/EN (referencia/SKU, precio, cantidad/stock, EAN/código de barras, IVA, etc.). Ajusta las asociaciones en la tabla; cualquier columna dejada en «no mapeada» simplemente se ignora.

4. Opciones y programación

Define el comportamiento de importación: crear los elementos que faltan, actualizar los existentes, crear categorías al vuelo, descargar imágenes desde URLs, reemplazar o conservar las imágenes existentes en la actualización, y el tamaño de lote (filas procesadas por llamada AJAX). Activa opcionalmente la programación y elige la frecuencia (horaria, diaria o semanal). Guarda: el perfil aparece en la lista, listo para ejecutar o programar.

Formatos de columna

El módulo entiende los formatos de negocio de PrestaShop. Estas son las convenciones esperadas en tus archivos:

Combinaciones

La columna de atributos sigue el formato Grupo:Valor|Grupo:Valor. Los grupos y valores de atributo que falten se crean automáticamente, y la combinación se identifica por su conjunto exacto de atributos, de modo que reejecutar la importación no crea duplicados. El producto padre se encuentra por su referencia o ID según la clave de correspondencia.

Características

Usa el formato Nombre:Valor|Nombre:Valor. Cada característica y su valor se crean si aún no existen.

Categorías, imágenes y etiquetas

Estos campos aceptan varios valores, separados por el separador multivalor definido en el perfil. Para las categorías, puedes mezclar nombres e IDs; la primera imagen listada sirve de portada.

Orígenes remotos y seguridad

En importación, el módulo recupera el archivo desde una URL (HTTP/HTTPS, con autenticación básica si es necesario), un servidor FTP (modo pasivo o activo), un servidor SFTP o una ruta local restringida al directorio de la tienda. En exportación, puede depositar el archivo generado en FTP/SFTP o en una carpeta local, o proponerlo para descarga.

Las contraseñas FTP/SFTP se cifran en reposo en la base de datos (AES-256-CBC, clave derivada de la clave de cifrado de tu tienda) y nunca se devuelven al navegador en texto claro.

Importación por lotes y reanudación

Las importaciones manuales se ejecutan por lotes sucesivos en AJAX, con una barra de progreso y contadores en tiempo real (OK / errores / total). Tras cada lote se memoriza la posición exacta: un archivo de decenas de miles de filas se importa sin provocar un timeout de PHP, incluso en alojamiento compartido. En modo cron, el procesamiento encadena de forma síncrona hasta la última fila.

Exportación

Crea un perfil de exportación eligiendo la entidad (productos, categorías, clientes, pedidos), el formato (CSV o XML) y los campos a incluir. El archivo generado se propone para descarga inmediata o se deposita automáticamente en el destino remoto configurado. Las exportaciones se generan por lotes para mantener el rendimiento en grandes volúmenes.

Programación (cron)

Para automatizar un perfil, activa su programación (paso 4) y luego llama a la URL de cron del módulo a intervalos regulares. En cada llamada solo se ejecutan los perfiles cuya frecuencia ha vencido.

*/15 * * * * curl -s "https://tu-tienda.tld/index.php?fc=module&module=dfcsvpro&controller=cron&token=TU_TOKEN" > /dev/null

La URL exacta y el token están en la pestaña Scheduling / Cron del módulo, con un botón para regenerar el token. Dos parámetros opcionales:

• &id_profile=N: ejecuta solo el perfil indicado.
• &force=1: ignora la comprobación de frecuencia y ejecuta el perfil de inmediato.

Registros y alertas por e-mail

Cada ejecución se registra con su estado, sus contadores y el detalle de errores línea por línea (los primeros 200). La pestaña Logs lista el historial y permite consultar los errores de una importación. En cuanto una importación falla o contiene filas con error, se envía automáticamente una alerta por e-mail (plantilla FR o EN) a la dirección configurada en los ajustes.

Ajustes

En la pestaña Ajustes, activa o desactiva las alertas por e-mail, define la dirección destinataria, el tamaño de lote por defecto y el periodo de retención de los registros (los más antiguos se purgan automáticamente). Los archivos temporales de importación/exportación se limpian tras 48 horas.

Formato XML

En la importación XML, el nodo de elemento repetido se detecta automáticamente (o se indica en el perfil). Los elementos se aplanan: los elementos anidados se convierten en columnas padre/hijo, los atributos en @atributo, y los elementos repetidos se sufijan nombre#1, nombre#2. Luego mapeas estas columnas aplanadas como en un CSV.

Compatibilidad y notas técnicas

• Compatible con PrestaShop 8.0 a 9.x, PHP 7.4 a 8.3, multitienda.
• CSV: detección automática del delimitador, gestión del BOM, conversión de codificaciones ISO-8859-1 y Windows-1252.
• Clientes importados con contraseña cifrada en bcrypt y asignados a un grupo por nombre.
• Sin override del núcleo; el AJAX legacy usa las convenciones de PS9.

Resolución de problemas

La interfaz del módulo queda vacía o las listas desplegables no se rellenan. Vacía la caché de PrestaShop y luego fuerza la recarga del navegador (Ctrl+Mayús+R). Si hay un gestor de caché/CCC activo, regenera los assets.

El SFTP falla. Comprueba que la extensión PHP ssh2 está instalada en el servidor; si no, usa FTP o una URL.

El cron no se dispara. Comprueba el token, que la tienda no esté en mantenimiento, y que el perfil tenga la programación activada y un origen automático (los perfiles de subida manual no se pueden programar).

Hay filas con error. Abre el detalle del registro: cada error indica el número de fila y la causa (columna clave ausente, valor no válido, etc.).