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

> 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…

- Página: <https://www.datafirefly.com/pt/documentation/synchronisation-google-sheets-prestashop/>
- Idioma: pt
- Atualizado em: 2026-09-09
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/synchronisation-google-sheets-prestashop/index.md), [en](https://www.datafirefly.com/en/documentation/synchronisation-google-sheets-prestashop/index.md), [es](https://www.datafirefly.com/es/documentation/synchronisation-google-sheets-prestashop/index.md), [de](https://www.datafirefly.com/de/documentation/synchronisation-google-sheets-prestashop/index.md), [it](https://www.datafirefly.com/it/documentation/synchronisation-google-sheets-prestashop/index.md), [pl](https://www.datafirefly.com/pl/documentation/synchronisation-google-sheets-prestashop/index.md), [nl](https://www.datafirefly.com/nl/documentation/synchronisation-google-sheets-prestashop/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

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](https://console.cloud.google.com) 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.