# DataFirefly Server-Side: guia completo

> Guia completo do módulo gratuito DataFirefly Server-Side para PrestaShop 8 e 9: instalação, credenciais, evento de teste, gate de consentimento com o Cookie Manager e resolução de problemas.

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

## Apresentação

O DataFirefly Server-Side é o conector PrestaShop gratuito do serviço [DataFirefly Server-Side Tracking](https://server-side.datafirefly.com/). A cada encomenda validada, o módulo constrói um evento de compra completo e envia-o de servidor para servidor, assinado HMAC-SHA256, para o dispatcher DataFirefly alojado na UE (Alemanha). O serviço difunde depois o evento para os seus destinos configurados: Meta Conversions API, GA4 Measurement Protocol, TikTok Events API, Pinterest Conversions API e Google Ads.

A repartição de papéis é simples: o módulo **capta e assina**, o serviço **ingere, desduplica e difunde**. O módulo é gratuito; a difusão exige uma subscrição do serviço (Starter a partir de 39 €/mês).

Um incidente de tracking nunca quebrará o seu checkout: o módulo é fail-safe por conceção (timeouts de 2 s / 4 s, erros registados nos logs do PrestaShop, nenhuma exceção sobe até ao funil de encomenda).

## Pré-requisitos

- PrestaShop 1.7.6 ou superior, 8.x ou 9.x
- PHP 7.4 ou superior, com a extensão cURL (presente na quase totalidade dos alojamentos)
- Uma conta DataFirefly Server-Side Tracking ativa: subscreva em [server-side.datafirefly.com](https://server-side.datafirefly.com/)
- Recomendado: o nosso módulo [DataFirefly Cookie Manager](https://www.datafirefly.com/pt/produto/gestor-cookies-tarteaucitron-rgpd-prestashop/) (banner tarteaucitron conforme ao RGPD com Google Consent Mode v2) para a gate de consentimento nativa

## Instalação

1. Transfira o ZIP do módulo a partir da sua conta DataFirefly.
2. No back-office do PrestaShop, abra **Módulos > Gestor de módulos > Instalar um módulo** e envie o ficheiro `datafirefly_serverside.zip`.
3. Clique em **Instalar**. O módulo regista-se no hook de validação de encomenda; não é necessário nenhum override nem alteração de tema.

Na instalação, o tracking está **desativado** e a exigência de consentimento está **ativa**: nada parte enquanto não tiver configurado e ativado o módulo.

## Obter as suas credenciais

1. Inicie sessão na sua [área de cliente DataFirefly](https://admin.datafirefly.com/app/login) (ou [subscreva](https://admin.datafirefly.com/pricing) se ainda não o fez).
2. Abra a secção **Ligar a sua loja** do seu site.
3. Copie os três valores apresentados: o **Tenant ID** (no formato `shop_asualoja_xxxx`), o **segredo HMAC** (chave de assinatura de 64 caracteres) e o **endpoint de eventos**.

O segredo HMAC é uma chave privada: não a partilhe nem a cole em nenhum outro sítio além da configuração do módulo. Em caso de fuga, regenere-a a partir da sua área de cliente.

## Configuração

Abra **Módulos > Gestor de módulos > DataFirefly Server-Side > Configurar**. O formulário tem cinco definições:

- **Ativar o tracking**: o interruptor principal. Enquanto estiver em Não, nenhum evento é enviado.
- **Tenant ID**: o identificador da sua loja no serviço, copiado a partir da sua área de cliente.
- **Segredo HMAC**: a chave de assinatura de 64 caracteres. Cada evento é assinado com esta chave antes do envio.
- **Events endpoint**: o URL de ingestão do dispatcher. O valor por defeito serve na quase totalidade dos casos; só o altere se a sua área de cliente indicar outro.
- **Exigir o consentimento**: ativo por defeito. Quando está ativo, a compra só é transmitida se o visitante tiver dado um consentimento de marketing (ver abaixo). Desative-o apenas se gerir o consentimento a montante com outro dispositivo.

Guarde e passe ao teste.

## Testar a ligação

Clique em **Enviar um evento de teste** no formulário de configuração. O módulo envia um `page_view` sintético, assinado, para o dispatcher, sem tocar nas encomendas reais.

- **«Evento de teste entregue» (HTTP 200)**: o seu Tenant ID, o seu segredo e o seu endpoint estão corretos. A sua loja está ligada, mesmo que ainda não haja nenhum destino configurado do lado do serviço.
- **«Evento de teste falhou»**: o código HTTP e a mensagem do dispatcher são apresentados para diagnóstico (ver Resolução de problemas).

## O consentimento (RGPD)

Quando **Exigir o consentimento** está ativo, o módulo lê, diretamente do lado do servidor e no momento da validação da encomenda, o cookie de consentimento no formato tarteaucitron colocado pelo nosso módulo [DataFirefly Cookie Manager](https://www.datafirefly.com/pt/produto/gestor-cookies-tarteaucitron-rgpd-prestashop/) (Google Consent Mode v2). O nome do cookie é retomado automaticamente da configuração do Cookie Manager (por defeito `tarteaucitron`).

A compra é transmitida se o visitante tiver consentido em **pelo menos um serviço publicitário**: Meta Pixel, Google Ads, TikTok Pixel ou LinkedIn Insight. A abordagem é privacy-first: cookie ausente ou ilegível = nenhum envio.

É a combinação recomendada no PrestaShop: o Cookie Manager gere o banner, o Consent Mode v2 e a prova do consentimento; este módulo aplica a mesma decisão ao tracking server-side. Uma única fonte de verdade para toda a cadeia, alinhada com as exigências da CNPD sobre o consentimento prévio.

Se gerir o consentimento com outro dispositivo, desative **Exigir o consentimento** e aplique a sua própria lógica a montante: cabe então ao seu dispositivo garantir que nenhuma encomenda provém de um visitante que não consentiu.

## O que é enviado

A cada encomenda validada, o módulo constrói um evento `purchase` com:

- **Transação**: montante pago, moeda ISO, referência da encomenda, produtos (id, nome, quantidade, preço unitário com IVA) e número total de artigos.
- **Dados de correspondência**: e-mail e identificador do cliente, telefone, nome próprio, apelido, cidade, código postal e país ISO da morada de faturação (recurso à morada de entrega).
- **Identificadores do navegador** capturados no momento da encomenda: `_fbp` e `_fbc` (Meta), `_ttp` (TikTok) e o client id GA4 extraído do cookie `_ga`.

Cada campo opcional só é acrescentado se estiver presente e for válido: o dispatcher valida de forma estrita, e um evento bem formado é um evento entregue. O identificador do evento está alinhado com a encomenda (`order_ID`), de forma idempotente: é ele que permite a desduplicação cliente + servidor do lado das plataformas se usar também tags no navegador.

Do lado do transporte, cada pedido leva três cabeçalhos: o tenant, o carimbo temporal (verificado numa janela anti-replay de 300 segundos) e a assinatura HMAC-SHA256 do corpo exato do pedido. As suas credenciais Meta, GA4, TikTok, Pinterest e Google Ads ficam na sua área DataFirefly: nem a loja nem o navegador as veem.

## Acompanhar os seus eventos do lado do serviço

Na sua área de cliente, o **Event Inspector** mostra-lhe os eventos um a um, com os dados pessoais mascarados (conforme ao RGPD). Verifica aí o que é realmente entregue a cada destino. A disponibilidade das plataformas pode ser consultada a qualquer momento na [página de estado pública](https://serverside.datafirefly.com/status).

## Resolução de problemas

### O evento de teste falha com «not_configured»

Um dos três campos (Tenant ID, segredo, endpoint) está vazio. Copie de novo os três valores a partir da sua área de cliente e guarde antes de testar de novo.

### O evento de teste falha em HTTP 401 ou 403

A assinatura é rejeitada: o segredo HMAC não corresponde ao tenant, ou o Tenant ID está errado. Copie de novo os dois valores sem espaços nem quebras de linha. Verifique também que o relógio do seu servidor está correto (NTP): um desvio superior a 300 segundos faz falhar a janela anti-replay.

### O evento de teste falha com «curl: …» ou HTTP 0

O seu servidor não consegue contactar o dispatcher: firewall de saída, DNS ou proxy. Autorize as ligações HTTPS de saída para o endpoint indicado na sua área de cliente.

### O teste passa, mas não chega nenhuma encomenda

- Verifique que **Ativar o tracking** está em Sim.
- Se **Exigir o consentimento** estiver ativo, só as encomendas de visitantes que consentiram num serviço publicitário são transmitidas. Faça uma encomenda de teste depois de aceitar os cookies publicitários no banner.
- Consulte **Parâmetros avançados > Registos** no back-office: cada falha de entrega é aí registada com o código HTTP e o identificador da encomenda (prefixo `[DataFirefly SS]`).

### As conversões são contadas duas vezes

Impossível do lado do módulo: o identificador do evento é idempotente por encomenda. Se usar também tags no navegador fora do serviço, certifique-se de que enviam o mesmo identificador de evento (`order_ID`) para que as plataformas desdupliquem.

## Desinstalação

A desinstalação elimina toda a configuração do módulo (tenant, segredo, endpoint, definições). Não é criada nenhuma tabela na base de dados: o módulo não guarda nada além da sua configuração.