Documentación completa

Guía detallada de instalación y configuración del módulo Shopify Integration

Índice

1. Introducción

Esta guía explica paso a paso cómo configurar la integración Shopify para Dolibarr. Detallamos exactamente dónde encontrar cada valor necesario para la configuración.

Lo que aprenderá: De dónde provienen todos los valores de configuración y cómo obtenerlos precisamente.

Novedades en v2.0.24

Esta versión aporta mejoras importantes para una integración más fluida y automatizada.

Nuevas funcionalidades

Importación automática de pedidos históricos

El sistema CRON ahora puede importar automáticamente sus pedidos históricos durante la primera sincronización, creando automáticamente los clientes asociados.

Auto-activación inteligente de CRONs

Las tareas CRON se activan automáticamente tan pronto como las configuraciones de productos y pedidos están completas, y se desactivan si la configuración se vuelve incompleta para evitar errores de API.

Correcciones críticas

Problemas resueltos:
  • Sincronización manual: Corregido el caso donde la interfaz mostraba productos pero no podía sincronizarlos
  • Gestión de servicios: Los servicios ahora se identifican correctamente y se sincronizan como tales (requiresShipping: false)
  • Parámetros unificados: Manejo consistente de parámetros entre interfaces de búsqueda y sincronización
  • SKUs con ceros iniciales: Preservación adecuada de ceros iniciales en referencias de productos

Mejoras de seguridad

Instalación segura: Las tareas CRON ahora están desactivadas por defecto durante la instalación para evitar llamadas API prematuras. Se activan automáticamente una vez que la configuración está completa.

2. Prerrequisitos del sistema

Dolibarr y Servidor

Componente Versión requerida Verificación
PHP 7.2.5 a 8.3.16 Menú Dolibarr → Inicio → Información del sistema
Dolibarr 19.0 a 21.x Menú Dolibarr → Inicio → Versión
Extensión cURL Activada Menú Dolibarr → Inicio → Información del sistema → Extensiones PHP
Extensión JSON Activada Menú Dolibarr → Inicio → Información del sistema → Extensiones PHP

Shopify

3. Instalación del módulo

Paso 1: Compra y descarga

  1. Compre el módulo en Dolistore
  2. Descargue el archivo ZIP desde su cuenta Dolistore
  3. No descomprima el archivo

Paso 2: Instalación en Dolibarr

  1. Inicie sesión en Dolibarr como administrador
  2. Vaya a Inicio → Configuración → Módulos/Aplicaciones
  3. Haga clic en "Desplegar/Instalar módulo/aplicación externa"
  4. Seleccione su archivo ZIP descargado
  5. Haga clic en "Enviar archivo"
  6. Active el módulo en la lista de módulos disponibles
Importante: Active estos módulos Dolibarr requeridos antes de continuar:
  • Productos/Servicios
  • Terceros (Clientes/Proveedores)
  • Pedidos de clientes
  • Facturas de clientes
  • Stocks
  • Envíos

4. Creación de la aplicación Shopify

Paso crucial: Debe crear una aplicación privada en Shopify para obtener las claves de acceso.

Paso 1: Acceder a las aplicaciones

  1. Inicie sesión en su administración Shopify
  2. En el menú de la izquierda, haga clic en "Apps"
  3. Haga clic en "Desarrollar apps" (o "App and sales channel settings")
  4. Si es su primera app, haga clic en "Permitir desarrollo de aplicaciones personalizadas"

Paso 2: Crear la aplicación

  1. Haga clic en "Crear una app"
  2. Nombre de la app: Dolibarr Integration
  3. Email del desarrollador: su email
  4. Haga clic en "Crear la app"

Paso 3: Configurar los permisos

Haga clic en "Configurar scopes Admin API" y active estos permisos:

Scope Permiso Justificación
read_products Lectura Leer los productos Shopify
write_products Escritura Crear/modificar productos
read_orders Lectura Leer los pedidos
write_orders Escritura Modificar los pedidos
read_customers Lectura Leer los datos de clientes
write_customers Escritura Crear clientes
read_inventory Lectura Leer los stocks
write_inventory Escritura Actualizar los stocks
read_locations Lectura Leer las ubicaciones

Haga clic en "Guardar" después de seleccionar todos los scopes.

Paso 4: Instalar la aplicación

  1. Haga clic en "Instalar la app"
  2. Confirme la instalación
  3. La app ahora está instalada y puede recuperar los tokens

5. Configuración Shopify - Dónde encontrar cada valor

Ahora que su aplicación está creada, aquí está exactamente dónde recuperar cada valor:

Campo Dolibarr Dónde encontrar el valor en Shopify Formato exacto Ejemplo
Nombre de host tienda Shopify * URL de su tienda (barra de direcciones) mitienda.myshopify.com
(SIN https://)		 tienda-test.myshopify.com
Token de acceso Shopify * Apps → Desarrollar apps → [Su app] → Tokens de acceso API → "Admin API access token" shpat_xxxxxxxxxxxxxxxxxxxxxxxx shpat_1a2b3c4d5e6f7g8h9i0j
Clave API Shopify * Apps → Desarrollar apps → [Su app] → Credenciales de la API → "API key" Cadena alfanumérica abc123def456ghi789
Clave secreta API Shopify * Apps → Desarrollar apps → [Su app] → Credenciales de la API → "API secret key" Cadena alfanumérica secreta shpss_xyz789abc123def456
ID de ubicación Shopify * Configuración → Ubicaciones → Copie el ID de su ubicación principal Número entero 123456789
Vendedor Shopify Nombre de su marca/empresa (opcional) Texto libre Mi Tienda
Atención a los formatos:
  • Nombre de host: SIN "https://" al principio
  • Token de acceso: Generalmente comienza con "shpat_"
  • Clave secreta: Generalmente comienza con "shpss_"
  • ID ubicación: Solo números, sin texto

Cómo recuperar el ID de ubicación

  1. En Shopify Admin, vaya a Configuración → Ubicaciones
  2. Haga clic en su ubicación principal (generalmente la que tiene su dirección)
  3. El ID se encuentra en la URL: .../locations/123456789
  4. Copie solo los números: 123456789

6. Configuración Dolibarr - Parámetros automáticos y manuales

Campo Cómo obtener el valor Notas
Clave API Dolibarr * Generada automáticamente por el módulo Si no tiene una: Menú → Usuarios y Grupos → [Su usuario] → Pestaña API → Generar
URL host Dolibarr * Detectada automáticamente Ej: https://sudominio.com/dolibarr
Categoría productos Dolibarr * Menú → Productos/Servicios → Categorías → Seleccione su categoría Solo los productos de esta categoría serán sincronizados

Parámetros de sincronización

Parámetro Valor recomendado Explicación
Máximo pedidos por sync 10 Limita el número de pedidos procesados cada vez
Productos por ciclo cron 10 Número de productos actualizados por ciclo automático

7. Configuración sincronización de productos

Opciones de sincronización disponibles

Opción Descripción Recomendación
Sincronizar precios Envía los precios Dolibarr a Shopify Activado - Esencial para e-commerce
Nivel de precio (si multiprecio) Qué nivel de precio Dolibarr usar Nivel 1 generalmente
Sincronizar descripciones Envía las descripciones de productos Activado - Importante para SEO
Sincronizar imágenes Envía las imágenes de productos Activado - Indispensable
Sincronizar stocks Actualiza las cantidades en stock Activado - Evita la sobreventa
Usar stock virtual Stock real - pedidos + pedidos proveedores Activado - Más preciso
Consejo: Active todas las opciones para una sincronización completa. Podrá desactivarlas individualmente más tarde si es necesario.

8. Configuración sincronización de pedidos

Parámetros requeridos

Campo Dónde configurarlo en Dolibarr Ejemplo
Prefijo pedidos Texto libre (ej: SHOP-) SHOP-
Origen pedido Menú → Configuración → Diccionarios → Origen de las propuestas comerciales/pedidos Internet
Condiciones de pago Menú → Configuración → Diccionarios → Condiciones de pago Pago a la recepción
Método envío por defecto Menú → Configuración → Diccionarios → Medios de transporte Correos
Producto para gastos de envío Menú → Productos/Servicios → Crear un servicio "Gastos de envío" Servicio con ref SHIP001
Almacén por defecto Menú → Stocks → Almacenes Su almacén principal
Cuenta bancaria Menú → Banco → Cuentas financieras Su cuenta principal

Crear el producto "Gastos de envío"

  1. Menú → Productos/Servicios → Nuevo producto/servicio
  2. Tipo: Servicio
  3. Referencia: ENVIO
  4. Etiqueta: Gastos de envío
  5. Precio: 0 (se calculará automáticamente)
  6. Haga clic en Crear

8.1. Importación de pedidos históricos v2.0.24

Importe automáticamente todos sus pedidos Shopify anteriores durante la primera configuración del módulo.

Nueva función: La importación histórica ahora utiliza paginación inteligente para procesar miles de pedidos sin limitación y se reanuda automáticamente si se interrumpe.

Campos de configuración

Campo Descripción
Habilitar importación histórica Permite la importación automática de pedidos Shopify anteriores durante la próxima ejecución del CRON. Se desmarca automáticamente después de una importación exitosa para evitar duplicados.
Fecha de inicio de importación Fecha desde la cual importar pedidos históricos (dejar vacío para importar desde el principio)
Fecha de fin de importación Fecha hasta la cual importar pedidos históricos (dejar vacío para importar hasta hoy)
Importación histórica completada Indica si la importación histórica ha sido realizada. Una vez completada, solo se importarán nuevos pedidos

Cómo funciona

  1. Active la importación histórica y opcionalmente defina un rango de fechas
  2. El sistema procesa automáticamente pedidos en lotes de 10-50 según su configuración
  3. Si se interrumpe por límite de tiempo, la importación se reanuda automáticamente en el próximo CRON
  4. Una vez completado, la importación se desactiva automáticamente para evitar duplicados
Paginación automática: El sistema atraviesa automáticamente todas las páginas de pedidos disponibles, incluso en catálogos grandes.
Para importaciones iniciales grandes: Monitoree los logs de Dolibarr para seguir el progreso.

9. Configuración de tareas automáticas (Cron)

Importante: Las tareas cron están desactivadas por defecto por seguridad. Debe activarlas manualmente.

Tareas a configurar

Tarea Frecuencia recomendada Descripción
Sincronización productos Cada hora Actualiza productos y stocks
Importación pedidos Cada 15 minutos Recupera los nuevos pedidos Shopify

Activación de las tareas cron

  1. Menú → Herramientas → Tareas programadas
  2. Busque las tareas "ShopifyIntegration"
  3. Para cada tarea:
    • Haga clic en Modificar
    • Active "Estado: Activado"
    • Configure la frecuencia
    • Haga clic en Modificar
Prueba: Puede probar una tarea haciendo clic en el botón "Ejecutar ahora" junto a cada tarea.

10. Actualización del módulo

Cómo actualizar el módulo Shopify Integration a una nueva versión desde el DoliStore.

Importante: El procedimiento de desactivación/reactivación es obligatorio para que los scripts de actualización SQL se ejecuten correctamente.

Procedimiento de actualización

1. Descargar la nueva versión

  1. Vaya al DoliStore
  2. Inicie sesión con su cuenta
  3. Descargue la última versión del módulo (archivo ZIP)
  4. Guarde el archivo ZIP en su computadora

2. Desactivar el módulo actual

  1. En Dolibarr: Menú → Configuración → Módulos/Aplicaciones
  2. Busque "Shopify Integration"
  3. Haga clic en "Desactivar" (botón rojo)
  4. Confirme la desactivación

3. Instalar la nueva versión

  1. Permanezca en Menú → Configuración → Módulos/Aplicaciones
  2. Haga clic en "Desplegar/Instalar módulo externo"
  3. Haga clic en "Examinar" y seleccione el archivo ZIP descargado
  4. Haga clic en "Enviar archivo"
  5. Siga las instrucciones de instalación

4. Reactivar el módulo

  1. Una vez completada la instalación, busque "Shopify Integration"
  2. Haga clic en "Activar" (botón verde)
  3. Verifique que el número de versión mostrado coincida con la nueva versión
  4. Los scripts SQL de actualización se ejecutan automáticamente durante la reactivación
Verificación:
  • El número de versión mostrado en la lista de módulos debe coincidir con la nueva versión
  • Revise los logs de Dolibarr para asegurar que los scripts SQL se ejecutaron sin errores
  • Pruebe las funcionalidades principales (sincronización manual, configuración)

Método alternativo: Vía pestaña DoliStore

Alternativa rápida: También puede intentar la pestaña "Módulos disponibles desde DoliStore" que a veces permite actualizaciones automáticas directas, pero el método anterior es más confiable.
En caso de problemas: Restaure la copia de seguridad de la carpeta anterior y contacte al soporte. Nunca deje el módulo en un estado parcialmente actualizado.

11. Resolución de problemas comunes

Errores de conexión Shopify

Error: "Connection failed" o "Access denied"
Causa: Información API incorrecta
Solución:
  • Verifique el nombre de host (sin https://)
  • Regenere el token de acceso Shopify
  • Verifique que la app esté bien instalada
  • Controle todos los scopes necesarios

Productos no sincronizados

Error: "Ningún producto sincronizado"
Causa: Problema de categoría o estado
Solución:
  • Verifique que sus productos estén en la categoría correcta
  • Estado producto = "En venta"
  • Producto no archivado

Pedidos no importados

Error: "No orders found"
Causa: Configuración incompleta
Solución:
  • Complete todos los campos obligatorios de la pestaña "Pedidos"
  • Verifique que la cuenta bancaria exista
  • Cree el producto "Gastos de envío"

Dónde encontrar los logs

Menú → Herramientas → Log Dolibarr Busque: "ShopifyIntegration"

Soporte técnico

Si no puede resolver su problema:

🎉 ¡Felicitaciones!

Su integración Shopify-Dolibarr ahora está configurada. Puede probar la sincronización a través de la interfaz de sincronización manual.

Volver al inicio Evaluar el módulo