Sincronización Bidireccional con Google Sheets — Guía completa

El módulo DataFirefly Sheet Sync mantiene tu catálogo PrestaShop sincronizado con una hoja de Google en ambos sentidos: editas el precio, la cantidad en stock, el título y el estado activo de tus productos en la hoja, y el módulo los aplica en PrestaShop; a la inversa, cualquier cambio hecho en el back office vuelve automáticamente a la hoja. Esta guía cubre la instalación, la creación de la cuenta de servicio de Google, el uso compartido de la hoja, la configuración, el funcionamiento de la sincronización, el cron y la resolución de problemas.

Requisitos

• PrestaShop 8.0 hasta 9.x.
• PHP 7.4 hasta 8.3 con las extensiones cURL y OpenSSL activadas.
• Una cuenta de Google con acceso a la consola de Google Cloud para crear una cuenta de servicio (gratis).
• Acceso a cron (tarea programada del servidor o servicio de cron externo) para la sincronización automática.

Instalación

1. En el back office, abre Módulos > Gestor de módulos, luego Subir un módulo y suelta el archivo dfsheetsync.zip.
2. Una vez instalado, abre la página de configuración con el botón Configurar.

Al instalarse, el módulo crea su tabla de estado de sincronización, registra sus valores por defecto y genera automáticamente un token de cron.

Crear la cuenta de servicio de Google

Una cuenta de servicio es una identidad de Google que el módulo utiliza para leer y escribir en tu hoja, sin flujo OAuth ni pantalla de consentimiento.

1. En la consola de Google Cloud, crea (o selecciona) un proyecto.
2. Activa la API de Google Sheets para este proyecto (menú APIs y servicios > Biblioteca, busca «Google Sheets API» y pulsa Habilitar).
3. Abre APIs y servicios > Credenciales, haz clic en Crear credenciales > Cuenta de servicio, ponle un nombre y confirma.
4. Abre la cuenta de servicio creada, pestaña Claves, luego Agregar clave > Crear clave nueva > JSON. Se descarga un archivo .json: es la clave que pegarás en el módulo.

Compartir la hoja con la cuenta de servicio

El archivo JSON contiene un campo client_email con el formato nombre@proyecto.iam.gserviceaccount.com. Esa es la dirección que hay que autorizar.

1. Abre (o crea) tu hoja de Google.
2. Haz clic en Compartir y añade la dirección client_email de la cuenta de servicio con el rol Editor.

Configuración

La página de configuración reúne los siguientes ajustes:

• JSON de la cuenta de servicio: pega aquí el contenido completo del archivo .json. Deja el campo vacío para conservar la clave ya guardada.
• ID o URL de la hoja de cálculo: pega el ID de la hoja o su URL completa — el ID se extrae automáticamente.
• Nombre de la pestaña: la pestaña a usar dentro de la hoja (por defecto Products). Se rellena con una fila de encabezado en la primera ejecución.
• Idioma de los títulos: el idioma en el que se leen y escriben los títulos de los productos.
• Prioridad en caso de conflicto: decide qué lado gana cuando un producto se ha editado en ambos lados (la hoja de Google, o PrestaShop).
• Exportar solo los productos activos: limita la sincronización a los productos activos.

Guarda y comprueba el panel de estado: muestra el correo de la cuenta de servicio conectada, la URL de cron, la fecha de la última sincronización y un enlace directo a la hoja.

Estructura de la hoja

La hoja tiene seis columnas, cuyo encabezado se crea automáticamente en la primera ejecución:

1. ID — el identificador del producto en PrestaShop. No modificar.
2. Referencia — referencia del producto (solo lectura para la sincronización).
3. Nombre — el título del producto en el idioma configurado.
4. Precio sin IVA — el precio base sin impuestos.
5. Cantidad — la cantidad de stock global.
6. Activo — 1 para activo, 0 para inactivo.

Cómo funciona la sincronización

El módulo guarda la huella (checksum) del último estado sincronizado de cada producto. En cada pasada, compara el estado actual de la tienda y el de la hoja con esa huella para determinar qué ha cambiado, y en qué lado:

• Hoja modificada, tienda sin cambios → los valores de la hoja se aplican al producto.
• Tienda modificada, hoja sin cambios → los valores de la tienda se escriben en la hoja.
• Ambos modificados → la regla de prioridad configurada decide (gana la hoja, o gana la tienda), y se registra la decisión.
• Producto ausente de la hoja → se añade automáticamente, con la tienda como referencia.

Solo se escriben las filas realmente modificadas, en el sentido correcto; las escrituras hacia Google se agrupan en lotes para respetar las cuotas de la API y mantenerse rápidas incluso en un catálogo grande.

Sincronización manual y reinicio

Hay dos botones disponibles en la configuración:

• Sincronizar ahora: ejecuta de inmediato una sincronización completa y muestra un informe (filas enviadas a la hoja, productos actualizados, filas añadidas, conflictos resueltos, filas ignoradas).
• Reiniciar estado: vacía la tabla de estado de sincronización. En la siguiente pasada, la tienda se considera la fuente de verdad para cada producto. Útil tras una reorganización manual de la hoja.

Configuración del cron

Para una sincronización automática, programa la URL de cron mostrada en la configuración, cada 5 a 15 minutos:

curl "https://tu-tienda.com/module/dfsheetsync/cron?token=TU_TOKEN"

El token se genera durante la instalación y protege el endpoint. La llamada devuelve un informe JSON de la sincronización.

Validación de los datos

Antes de escribir en la tienda, el módulo valida cada fila de la hoja. Una fila se ignora y se registra (sin interrumpir el resto de la sincronización) en los siguientes casos:

• nombre de producto vacío o con caracteres no permitidos;
• precio negativo;
• ID que no corresponde a ningún producto de la tienda.

El informe de sincronización muestra el número de filas ignoradas, y el detalle está disponible en los registros de PrestaShop.

Campos sincronizados y limitaciones

La versión 1.0.0 sincroniza, para cada producto: el título (en el idioma configurado), el precio base sin impuestos, la cantidad de stock global y el estado activo/inactivo.

Resolución de problemas

• Error «permiso denegado»: comprueba que la hoja está compartida como Editor con la dirección client_email de la cuenta de servicio.
• Error «JSON inválido»: el contenido pegado debe ser el archivo de clave completo, que contenga al menos client_email y private_key.
• Ninguna sincronización: comprueba que el ID de la hoja está indicado y que el cron se ejecuta, o lanza una sincronización manual.
• Error de autenticación de Google: asegúrate de que la API de Google Sheets está habilitada para el proyecto y de que el reloj del servidor está en hora (el JWT lleva marca de tiempo).
• Una fila no se aplica: nombre vacío/inválido o precio negativo; corrige la fila en la hoja.
• Un producto vuelve al valor anterior: revisa la regla de prioridad en caso de conflicto; el lado prioritario sobrescribe al otro cuando ambos han cambiado.

Desinstalación

La desinstalación elimina la tabla de estado de sincronización y la configuración del módulo (incluida la clave de la cuenta de servicio y el token de cron). Tus productos y tu hoja de Google no se modifican. Para una simple actualización, basta con reemplazar los archivos del módulo: el estado de sincronización se conserva.