Documentación completa

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

Índice

0. Obtener una licencia

Paso 1: Instalar la aplicación Doli2Shop

Acceda a doli2shop.ptitetete.org/shopify-app/ e instale la aplicación en su tienda Shopify.

Paso 2: Elegir su suscripción

  • Anual (recomendado): 250€ sin IVA/año - Ahorre 50€
  • Mensual: 25€ sin IVA/mes - Sin compromiso
¿Ya es cliente de DoliStore?
Elija "Ya tengo una licencia" e introduzca su número de serie (SI-XXXX-XXXX-XXXX) para seguir utilizando su licencia existente hasta su vencimiento.

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 18.0 a 22.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. Instalación de la aplicación Doli2Shop en Shopify

¡Nuevo! Aplicación oficial de Shopify - Doli2Shop ahora utiliza una aplicación de socio oficial, más simple y segura que las antiguas aplicaciones privadas.

¿Por qué una aplicación Shopify?

El uso de una aplicación de socio oficial de Shopify ofrece varias ventajas importantes:

  • 🔐 Seguridad OAuth 2.0: Autenticación segura conforme a los estándares de Shopify, sin compartir claves API sensibles
  • ✅ Conformidad Shopify: Aplicación verificada y aprobada por Shopify, cumpliendo todos sus requisitos de seguridad
  • 🚀 Instalación simplificada: Con unos pocos clics desde la App Store de Shopify, sin configuración técnica compleja
  • 🔄 Actualizaciones automáticas: Los permisos y funcionalidades se mantienen automáticamente actualizados
  • 📊 Acceso API completo: Todos los permisos necesarios están preconfigurados (productos, pedidos, clientes, inventario)

Tutorial de instalación en video

Mire este video para ver el proceso de instalación completo paso a paso:

Ver tutorial de instalación

Pasos de instalación

Paso 1: Acceder a la App Store de Shopify

  1. Inicie sesión en su administración Shopify
  2. En el menú de la izquierda, haga clic en "Apps"
  3. Haga clic en "Shopify App Store" o busque directamente en la tienda
  4. O acceda directamente a través del enlace: Doli2Shop en el Shopify App Store

Paso 2: Encontrar e instalar Doli2Shop

  1. Busque "Doli2Shop - ERP Integration" en la App Store
  2. O use el enlace directo proporcionado por el soporte
  3. Haga clic en "Agregar aplicación"
  4. Acepte los permisos solicitados (productos, pedidos, clientes, inventario)

Paso 3: Configuración en la aplicación

  1. Una vez instalada la app, siga el asistente de configuración
  2. Introduzca la URL de su Dolibarr (ej: https://sudominio.com/dolibarr)
  3. La aplicación genera automáticamente sus credenciales de API
  4. Anote cuidadosamente la información mostrada:
    • Access Token (comienza con shpat_...)
    • API Key
    • API Secret

Paso 4: Introducir información en Dolibarr

  1. Vuelva a Dolibarr → ShopifyIntegration → Configuración
  2. Pegue la información obtenida en los campos correspondientes
  3. Haga clic en "Guardar"
Importante: El Access Token solo se muestra una vez durante la instalación. Si lo pierde, deberá desinstalar y reinstalar la aplicación para obtener uno nuevo.

Permisos configurados automáticamente

La aplicación Doli2Shop configura automáticamente todos los permisos necesarios:

Scope Permiso Uso
read_products / write_products Lectura/Escritura Sincronización de productos Dolibarr ↔ Shopify
read_orders / write_orders Lectura/Escritura Importar pedidos de Shopify a Dolibarr
read_customers / write_customers Lectura/Escritura Creación automática de clientes
read_inventory / write_inventory Lectura/Escritura Sincronización de inventario en tiempo real
read_locations Lectura Gestión de ubicaciones de inventario
read_fulfillments / write_fulfillments Lectura/Escritura Sincronización de envíos

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"

🚨 Permisos Shopify faltantes - CRÍTICO

Síntoma: Los pedidos no se sincronizan desde hace varios días, CRON devuelve un error (-1)
Causa: Permisos WRITE faltantes en su aplicación Shopify
Diagnóstico rápido:
  1. Vaya a Menú ShopifyIntegration → Configuración → Diagnóstico del sistema
  2. Observe la sección "Shopify API Permissions"
  3. Si ve líneas con status: "error" → ¡Permisos faltantes!

📝 Permisos requeridos (9 mínimos)

PermisoTipoRequeridoFunción
read_productsREAD✅ SÍLeer productos
write_productsWRITE✅ SÍCrear/modificar productos
read_inventoryREAD✅ SÍLeer stocks
write_inventoryWRITE✅ SÍActualizar stocks
read_ordersREAD✅ SÍLeer pedidos
write_ordersWRITE✅ SÍModificar pedidos
read_customersREAD✅ SÍLeer clientes
write_customersWRITE✅ SÍCrear clientes
read_locationsREAD✅ SÍLeer ubicaciones
write_publicationsWRITE⚠️ RecomendadoPublicar en canales venta
write_filesWRITE⚠️ RecomendadoSincronizar imágenes

🔧 Procedimiento de corrección paso a paso

  1. Acceder a su aplicación Shopify:
    • Shopify Admin → Settings → Apps and sales channels
    • Haga clic en "Develop apps"
    • Seleccione su aplicación Dolibarr
  2. Modificar permisos:
    • Pestaña "Configuration"
    • Sección "Admin API access scopes" → Haga clic en "Edit"
  3. Activar TODOS los permisos faltantes (ver tabla arriba)
  4. Guardar y reinstalar:
    • Haga clic en "Save"
    • ⚠️ IMPORTANTE: Haga clic en "Reinstall app" para activar los nuevos scopes
  5. Recuperar el nuevo token:
    • Pestaña "API credentials"
    • Sección "Admin API access token"
    • Haga clic en "Reveal token once" y cópielo
    • ⚠️ ¡No podrá verlo nuevamente después!
  6. Actualizar Dolibarr:
    • Menú ShopifyIntegration → Configuración → Setup
    • Campo "Token de acceso Shopify" → Pegue el nuevo token
    • Haga clic en "Guardar"
  7. Verificar la corrección:
    • Menú ShopifyIntegration → Configuración → Diagnóstico del sistema
    • Todos los permisos deben mostrar status: "ok"
    • Pruebe una sincronización manual de pedidos
⚠️ Error frecuente: ¡Tener solo permisos READ NO es suficiente! El módulo necesita absolutamente permisos WRITE para funcionar correctamente (crear productos, actualizar stocks, agregar notas a pedidos, etc.).
Documentación completa: Para más detalles, consulte la guía técnica completa en /docs/troubleshooting/SHOPIFY_PERMISSIONS_EN.md de su instalación.

Problemas de endpoints API Dolibarr

Error: "Endpoint no encontrado (404)" o "Bad Request (400)"
Causas posibles:
  • Módulo API/Servicios Web deshabilitado: Menú → Configuración → Módulos → Buscar "API" → Habilitar
  • Versión Dolibarr demasiado antigua: Algunos endpoints requieren Dolibarr 14+
  • Permisos de usuario insuficientes: El usuario API debe tener derechos completos
  • Archivo de prueba faltante: Para documents/download, esto es normal si no existe logo de empresa

Configurar permisos de usuario API

  1. Menú → Configuración → Usuarios y Grupos
  2. Haga clic en su usuario API
  3. Pestaña "Permisos"
  4. Otorgue estos permisos mínimos:
    • ✅ API: Acceso completo a APIs
    • ✅ Documentos: Leer documentos
    • ✅ Productos/Servicios: Leer productos
    • ✅ Terceros: Leer/crear clientes
    • ✅ Pedidos: Leer/crear pedidos
  5. Haga clic en "Guardar"
Nota importante: El error 404 en "documents/download" es normal si no existe logo de empresa. Esto no afecta la sincronización con Shopify.

Explorar y probar la API de Dolibarr

Dolibarr proporciona un explorador API integrado para probar y documentar todos los endpoints disponibles:

  1. URL del explorador: https://sudominio.com/dolibarr/api/index.php/explorer
  2. Documentación Swagger: https://sudominio.com/dolibarr/api/index.php/explorer/swagger.json?DOLAPIKEY=su_clave_api
  3. Reemplace sudominio.com/dolibarr con su URL real de Dolibarr
  4. Reemplace su_clave_api con su clave API de usuario

Esta herramienta le permite:

  • ✅ Probar todos los endpoints API en vivo
  • ✅ Ver documentación completa para cada endpoint
  • ✅ Verificar parámetros requeridos y opcionales
  • ✅ Diagnosticar problemas de API directamente
Parámetros API críticos según documentación Swagger:
  • GET /documents: Parámetro modulepart obligatorio (ej.: product, company, user)
  • GET /documents/download: Parámetro modulepart obligatorio + original_file opcional
  • GET /status: Endpoint básico (no documentado en Swagger pero funcional)

Nota: Los errores 400 (Bad Request) generalmente indican parámetros faltantes o inválidos.

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