PS PrestaShop PrestaShop Intermédio

Sincronização bidirecional com o Google Sheets: guia completo

Instalar, configurar e explorar a sincronização bidirecional Google Sheets ⇄ PrestaShop: conta de serviço Google, partilha da folha, colunas, conflitos, cron e resolução de problemas.

Atualizado Versão do módulo 1.0.0

O módulo DataFirefly Sheet Sync sincroniza o seu catálogo PrestaShop com uma folha do Google Sheets nos dois sentidos: edita o preço, a quantidade em stock, o título e o estado ativo dos seus produtos na folha, e o módulo reflete-os no PrestaShop; ao contrário, qualquer alteração feita no back-office sobe automaticamente para a folha. Este guia cobre a instalação, a criação da conta de serviço Google, a partilha da folha, a configuração, o funcionamento da sincronização, o cron e a resolução de problemas.

Pré-requisitos

  • PrestaShop 8.0 a 9.x.
  • PHP 7.4 a 8.3 com as extensões cURL e OpenSSL ativas.
  • Uma conta Google e acesso à consola do Google Cloud para criar uma conta de serviço (gratuita).
  • Um acesso a cron (tarefa agendada no servidor ou serviço de cron externo) para a sincronização automática.

Não é necessária qualquer biblioteca Composer: as chamadas à API do Google Sheets são assinadas em PHP nativo (JWT RS256), com cURL e OpenSSL, ambos já exigidos pelo PrestaShop.

Instalação

  1. No back-office, abra Módulos > Gestor de módulos, clique em Carregar um módulo e coloque o ficheiro dfsheetsync.zip.
  2. Depois de instalado, abra a página de configuração através do botão Configurar.

Na instalação, o módulo cria a sua tabela de estado de sincronização, regista os valores predefinidos e gera automaticamente um token de cron.

Criar a conta de serviço Google

Uma conta de serviço é uma identidade Google que o módulo usa para ler e escrever na sua folha, sem OAuth nem ecrã de consentimento.

  1. Na consola do Google Cloud, crie (ou selecione) um projeto.
  2. Ative a API Google Sheets nesse projeto (menu APIs e serviços > Biblioteca, procure «Google Sheets API» e clique em Ativar).
  3. Abra APIs e serviços > Credenciais, clique em Criar credenciais > Conta de serviço, dê-lhe um nome e confirme.
  4. Abra a conta de serviço criada, separador Chaves, e depois Adicionar chave > Criar chave > JSON. É descarregado um ficheiro .json: é a chave que vai colar no módulo.

Este ficheiro JSON contém uma chave privada. Guarde-o em local seguro e não o partilhe. Pode sempre gerar um novo e revogar o antigo a partir da consola.

Partilhar a folha com a conta de serviço

O ficheiro JSON contém um campo client_email com a forma nome@projeto.iam.gserviceaccount.com. É esse o endereço a autorizar.

  1. Abra (ou crie) a sua folha do Google Sheets.
  2. Clique em Partilhar e acrescente o endereço client_email da conta de serviço com o papel de Editor.

Sem essa partilha como Editor, a API devolve um erro de «permissão recusada»: a conta de serviço só tem acesso às folhas que lhe tenham sido explicitamente partilhadas.

Configuração

A página de configuração reúne as seguintes definições:

  • JSON da conta de serviço: cole aqui o conteúdo completo do ficheiro .json. Deixe o campo vazio para conservar a chave já gravada.
  • ID ou URL da folha de cálculo: cole o identificador da folha ou o seu URL completo, uma vez que o ID é extraído automaticamente.
  • Nome do separador: o nome do separador a usar na folha de cálculo (por predefinição, Products). É preenchido com uma linha de cabeçalho na primeira passagem.
  • Idioma dos títulos: o idioma em que os títulos dos produtos são lidos e escritos.
  • Prioridade em caso de conflito: determina quem prevalece quando um produto foi alterado dos dois lados (a folha do Google ou o PrestaShop).
  • Exportar apenas os produtos ativos: limita a sincronização aos produtos ativos.

Grave e verifique depois o painel de estado: mostra o e-mail da conta de serviço ligada, o URL de cron, a data da última sincronização e uma ligação direta para a folha.

O idioma dos títulos é único: escolha o português se a sua equipa edita o catálogo nesse idioma. Os títulos dos outros idiomas continuam a ser geridos apenas no PrestaShop, e uma alteração na folha nunca lhes toca.

Estrutura da folha

A folha tem seis colunas, cujo cabeçalho é criado automaticamente na primeira passagem:

  1. ID: identificador do produto no PrestaShop. Não alterar.
  2. Referência: referência do produto (só de leitura do lado da sincronização).
  3. Nome: título do produto no idioma configurado.
  4. Preço sem IVA: preço de base sem impostos.
  5. Quantidade: quantidade em stock global.
  6. Ativo: 1 para ativo, 0 para inativo.

A coluna ID serve para identificar cada produto: nunca a altere nem reordene manualmente as colunas. Uma linha cujo ID não corresponda a nenhum produto é simplesmente ignorada.

Atenção ao separador decimal. Numa folha configurada em português, o Google Sheets apresenta os números com vírgula («19,90»), mas a coluna do preço tem de conter um valor numérico que a API devolva de forma interpretável. Formate a coluna do preço como número (e não como texto) e evite colar valores com separador de milhares. Em caso de dúvida, faça um teste num único produto e verifique o preço obtido no PrestaShop antes de editar todo o catálogo.

O preço sincronizado é o preço sem IVA. Se a sua equipa raciocina em preços com IVA (o valor que o cliente vê), acrescente uma coluna de cálculo à parte na folha, fora das seis colunas geridas pelo módulo: as colunas adicionais são ignoradas pela sincronização.

Como funciona a sincronização

O módulo memoriza a impressão (checksum) do último estado sincronizado de cada produto. Em cada passagem, compara o estado atual da loja e o da folha com essa impressão, para determinar o que mudou e de que lado:

  • Folha alterada, loja inalterada → os valores da folha são aplicados ao produto.
  • Loja alterada, folha inalterada → os valores da loja são escritos na folha.
  • Os dois alterados → decide a regra de prioridade configurada (ganha a folha ou ganha a loja), e o arbítrio fica registado.
  • Produto ausente da folha → é acrescentado automaticamente, com a loja como referência.

Só são escritas as linhas efetivamente alteradas, no sentido correto; as escritas para o Google são agrupadas em lotes, para respeitar as quotas da API e se manterem rápidas mesmo num catálogo grande.

Sincronização manual e reinicialização

Estão disponíveis dois botões na configuração:

  • Sincronizar agora: lança de imediato uma sincronização completa e mostra um relatório (linhas enviadas para a folha, produtos atualizados, linhas acrescentadas, conflitos resolvidos, linhas ignoradas).
  • Reinicializar o estado: limpa a tabela de estado de sincronização. Na passagem seguinte, a loja passa a ser considerada a fonte de verdade para cada produto. É útil depois de uma reorganização manual da folha.

Configuração do cron

Para uma sincronização automática, agende o URL de cron apresentado na configuração, a cada 5 a 15 minutos:

curl "https://a-sua-loja.pt/module/dfsheetsync/cron?token=O_SEU_TOKEN"

O token é gerado na instalação e protege o endpoint. A chamada devolve um relatório JSON da sincronização.

Escolha uma frequência adequada ao seu ritmo de edição. A cada 5 minutos serve a uma equipa que edita em contínuo; a cada 15 a 30 minutos chega para atualizações pontuais.

Validação dos dados

Antes de escrever na loja, o módulo valida cada linha da folha. Uma linha é ignorada e registada (sem interromper o resto da sincronização) nos seguintes casos:

  • nome de produto vazio ou com caracteres não autorizados;
  • preço negativo;
  • ID que não corresponde a nenhum produto da loja.

O relatório de sincronização indica o número de linhas ignoradas, e o detalhe pode ser consultado nos registos do PrestaShop.

Os acentos e a cedilha são caracteres perfeitamente válidos num nome de produto do PrestaShop: um título como «Camisola de algodão» passa sem problema. As linhas recusadas por caracteres não autorizados são, em regra, colagens que trouxeram símbolos invisíveis de outro documento.

Campos sincronizados e limitações

A versão 1.0.0 sincroniza, em cada produto: o título (no idioma configurado), o preço de base sem impostos, a quantidade de stock global e o estado ativo ou inativo.

Não são geridas na versão 1.0.0: as combinações (stock e preço por combinação) e os preços específicos. Continuam a ser comandados a partir do PrestaShop. A sincronização decorre no contexto da loja atual.

Resolução de problemas

  • Erro de «permissão recusada»: confirme que a folha está partilhada como Editor com o endereço client_email da conta de serviço.
  • Erro de «JSON inválido»: o conteúdo colado tem de ser o ficheiro de chave completo, com pelo menos client_email e private_key.
  • Nenhuma sincronização: confirme que o ID da folha de cálculo está preenchido e que o cron está mesmo a ser executado, ou lance uma sincronização manual.
  • Erro de autenticação Google: certifique-se de que a API do Google Sheets está ativa no projeto e de que o relógio do servidor está certo (o JWT é datado).
  • Uma linha não é aplicada: nome vazio ou inválido, ou preço negativo; corrija a linha na folha.
  • Um produto volta ao valor antigo: verifique a regra de prioridade em caso de conflito; o lado prioritário sobrepõe-se ao outro quando ambos mudaram.

Desinstalação

A desinstalação elimina a tabela de estado de sincronização e a configuração do módulo (incluindo a chave da conta de serviço e o token de cron). Os seus produtos e a sua folha do Google não são alterados. Para uma simples atualização, basta substituir os ficheiros do módulo: o estado de sincronização é conservado.

Esta página foi útil?

Ainda com dúvidas? Contacte o suporte