PrestaNexus — Sincronización Dolibarr ⇄ PrestaShop

El puente ERP / e-commerce completo y bidireccional entre Dolibarr ERP/CRM y una o varias tiendas PrestaShop.

1. Presentación

PrestaNexus convierte Dolibarr en el verdadero back office de su negocio PrestaShop. Clientes, direcciones, catálogo, combinaciones, existencias, precios, pedidos, facturas, pagos, abonos y envíos circulan automáticamente entre ambas aplicaciones, en el sentido que usted elija para cada tipo de dato.

Diseñado para producción, el módulo se basa en un motor de sincronización profesional: cola persistente, reintentos automáticos, protección contra duplicados y bucles, gestión de conflictos, simulación antes de importar y registro completo. Funciona sin ninguna modificación del núcleo de Dolibarr ni de PrestaShop.

2. Ventajas principales

• Sincronización bidireccional configurable objeto por objeto: Dolibarr → PrestaShop, PrestaShop → Dolibarr o en ambos sentidos.
• Fuente de verdad por tipo de dato: Dolibarr, PrestaShop, última modificación o validación manual.
• Multitienda: varias tiendas PrestaShop conectadas a la vez, cada una con su clave, idioma, moneda, almacén, reglas y correspondencias.
• Cero duplicados: cada pedido, factura, pago o abono se crea una sola vez, aunque el evento se reciba varias veces.
• Tiempo real y programado: triggers de Dolibarr, webhooks de PrestaShop firmados y tareas CRON de recuperación (sincronización delta).
• Grandes volúmenes: procesamiento por lotes, paginación y detección de cambios por huella, preparado para cientos de miles de productos, clientes y pedidos.
• Seguridad: claves API cifradas (AES-256-GCM), webhooks HMAC, protección CSRF, permisos de usuario detallados, secretos ocultos en los registros.
• Compatibilidad multiversión gracias a una arquitectura de adaptadores para Dolibarr y PrestaShop.

3. Funcionalidades detalladas

3.1 Conexión y multitienda

• Asistente de conexión: URL, clave del Webservice, tienda y grupo de tiendas, idioma, moneda, almacén, nivel de precio, modo de sincronización.
• Botón «Probar la conexión»: versión de PrestaShop, adaptador utilizado, nombre de la tienda, idiomas, monedas, multitienda, volúmenes y permisos del Webservice que faltan.
• Detección automática que rellena las correspondencias: idiomas, monedas, impuestos, transportistas, estados de pedido y grupos de clientes.
• Asistente de primera sincronización en 10 pasos, desde la conexión hasta la importación inicial.

3.2 Catálogo

• Productos y servicios: referencia, EAN, UPC, ISBN, MPN, nombre, descripciones, peso y dimensiones, coste, estado, categorías, marca, campos SEO y traducciones.
• Combinaciones de PrestaShop sincronizadas con las variantes de Dolibarr: atributos, valores, referencia, EAN, impacto en precio y peso.
• Categorías con árbol completo y categoría principal.
• Marcas y fabricantes, representados en Dolibarr como categorías dedicadas.
• Imágenes principales y secundarias, con detección de huella para no volver a enviar nunca una imagen idéntica.
• Filtros: solo determinadas categorías, solo productos activos, por tipo de producto.

3.3 Existencias

• Modos Dolibarr maestro, PrestaShop maestro o bidireccional.
• Existencias reales o virtuales, calculadas sobre uno o varios almacenes de Dolibarr (varios almacenes pueden abastecer una misma tienda).
• Protección antibucle: una cantidad enviada a PrestaShop nunca se vuelve a importar como un cambio nuevo.

3.4 Precios e impuestos

• Precio sin impuestos como referencia, niveles de precio de Dolibarr, precios específicos por cliente.
• Correspondencia de las reglas de impuestos de PrestaShop con los tipos de IVA de Dolibarr por país, sin crear nunca tipos duplicados.
• Cálculos decimales exactos sin errores de redondeo, soporte multimoneda.

3.5 Clientes, contactos y direcciones

• Creación automática de terceros en Dolibarr a partir de los clientes de PrestaShop, particulares y empresas (razón social, número de registro, NIF-IVA).
• Estrategias antiduplicados: ID externo, correo electrónico, NIF-IVA, número de registro, referencia; los casos ambiguos se señalan en lugar de crear un duplicado.
• Direcciones de facturación y de entrega sincronizadas con los contactos de Dolibarr.
• Opción para crear automáticamente una cuenta PrestaShop para cada nuevo cliente de Dolibarr.

3.6 Pedidos y estados

• Importación automática de los pedidos de PrestaShop: cliente, direcciones, líneas y combinaciones, descuentos, gastos de envío, envoltorio de regalo, mensaje, forma de pago, transportista y moneda.
• Control de totales: cualquier diferencia entre PrestaShop y Dolibarr se indica en la nota del pedido.
• Productos desconocidos: línea libre, importación del producto o bloqueo con error, a elegir.
• Pantalla de correspondencia de estados: cada estado de PrestaShop desencadena una acción en Dolibarr (validar, anular, cerrar…) y cada evento de Dolibarr puede actualizar el estado en PrestaShop.

3.7 Facturas, pagos y abonos

• Factura de Dolibarr creada automáticamente según la regla elegida: pedido validado, pago aceptado, pedido enviado o entregado.
• Importación de pagos con correspondencia de formas de pago (Stripe, PayPal, transferencia, contra reembolso…) y cuenta bancaria; ningún pago se registra dos veces ni por encima del importe pendiente.
• Abonos de PrestaShop importados como abonos de Dolibarr, con reposición opcional de existencias.

3.8 Envíos y seguimiento

Al validar un envío en Dolibarr se actualiza el pedido de PrestaShop: número de seguimiento, transportista y estado «Enviado», con envío opcional del correo al cliente.

3.9 Correspondencias y reglas de negocio

• Correspondencia de valores: estados, formas de pago, impuestos, transportistas, almacenes, idiomas, monedas, grupos de clientes.
• Constructor de correspondencias de campos: extrafields de Dolibarr ⇄ campos de PrestaShop, con conversión a texto, número, fecha, booleano, lista o JSON.
• Motor de reglas sin código, por ejemplo: «si la tienda es Francia y el pedido supera 500 €, asignar el comercial X».

3.10 Fiabilidad y rendimiento

• Cola persistente: ninguna sincronización pesada se ejecuta durante una petición web.
• Reintentos automáticos con espera exponencial; una operación fallida nunca se pierde y puede relanzarse.
• Tareas aisladas: un error en un producto nunca detiene la sincronización de los demás.
• Idempotencia, detección de cambios por huella, sincronización delta.
• Centro de conflictos: valor de Dolibarr, valor de PrestaShop y valor anterior lado a lado, resolución con un clic.
• Limitación de frecuencia y cortacircuitos para no saturar nunca la tienda; recuperación progresiva tras una caída.
• Modo simulación: número de elementos a crear, actualizar, sin cambios, en conflicto o con error, sin modificar ningún dato.

3.11 Supervisión

Commerce Sync Control Center — captura real del módulo en Dolibarr 23.0.4.

• Commerce Sync Control Center: indicadores clave, gráficos de 30 días, actividad reciente, últimos errores y tareas programadas.
• Sincronización manual por tipo de objeto, historial de lotes, cola, registros filtrables y exportables a CSV.
• Pestañas PrestaShop en las fichas de producto, tercero, pedido y factura.
• Informes: facturación, cesta media, nuevos clientes, productos más vendidos, roturas de stock, tasas de anulación y de reembolso.
• Diagnóstico, monitor de estado y consola de administración.

3.12 Seguridad y RGPD

• 12 permisos de Dolibarr distintos: lectura, administración, sincronización por ámbito, registros, conflictos, reintentos, correspondencias, purga.
• Las eliminaciones nunca se propagan por defecto: se prioriza el archivado o la desactivación.
• Exportación y anonimización de los datos de sincronización de un cliente; notificaciones al administrador (correo, agenda, webhook).

4. Matriz de sincronización

El sentido de cada objeto se configura tienda por tienda. «—» indica una operación que las API no permiten (por ejemplo, el Webservice de PrestaShop no permite crear una factura).

5. Requisitos

• Dolibarr 17 o superior, PHP 7.1 o superior con las extensiones curl, openssl, json, dom, simplexml y mbstring.
• Módulos de Dolibarr: Terceros, Productos, Pedidos, Facturas y Tareas programadas; opcionales: Stock, Variantes, Multimoneda, Bancos.
• PrestaShop 1.6.1 a 9.x con el Webservice activado y una clave API con los permisos necesarios; se recomienda HTTPS.
• Para tiempo real: el módulo complementario de PrestaShop «nxwebhook» incluido.

6. Instalación

• En Dolibarr: Inicio → Configuración → Módulos → Desplegar/instalar un módulo externo y subir el archivo prestanexus-1.0.zip.
• Activar el módulo PrestaNexus en la lista de módulos.
• En PrestaShop: activar el Webservice y crear una clave API con los permisos indicados en el manual.
• En Dolibarr: PrestaShop → Configuración → Conexiones → Nueva conexión y, a continuación, «Probar la conexión».
• Ejecutar el asistente de primera sincronización (correspondencias, simulación, importación inicial).
• Comprobar que las tareas programadas de Dolibarr se ejecutan (crontab del sistema) y, para tiempo real, instalar el módulo complementario nxwebhook.

7. Compatibilidad

El código incluye 469 pruebas automatizadas (motor, API, servicios de negocio). La matriz detallada está en docs/TEST_MATRIX.md.

8. Limitaciones conocidas

• Las contraseñas de los clientes no se pueden transferir: el cliente utiliza «¿Olvidó su contraseña?».
• Las devoluciones de mercancía de PrestaShop no están expuestas por el Webservice: se gestionan mediante los abonos.
• Las existencias de los productos gestionados por lote o número de serie no se pueden corregir desde PrestaShop.
• Las reglas de precios del catálogo y los cupones no tienen equivalente en Dolibarr: se importan como descuentos en los pedidos.

9. Preguntas frecuentes

¿El módulo modifica Dolibarr o PrestaShop?

No. Solo utiliza mecanismos oficiales: módulo, triggers, hooks, Webservice y un módulo complementario estándar de PrestaShop.

¿Se puede importar un pedido dos veces?

No. Cada pedido se identifica de forma única; el mismo evento recibido varias veces nunca crea un duplicado.

¿Qué ocurre si la tienda no está disponible?

Las tareas permanecen en la cola, el cortacircuitos suspende las llamadas y luego las reanuda progresivamente, sin pérdidas ni duplicados.

¿Puedo probar antes de importar mis datos?

Sí, el modo simulación muestra lo que se crearía, actualizaría o estaría en conflicto sin modificar nada.

¿Puedo conectar varias tiendas?

Sí, sin límite, cada una con su propia configuración.

10. Editor y soporte

NEXT GESTION — www.nextgestion.com — contact@nextgestion.com

Distribuido bajo licencia GPL v3 o posterior. Documentación completa en francés e inglés incluida (manual en PDF).

Demo del módulo PrestaNexus
Usuario : demo
Contraseña : demo