# DataFirefly Server-Side para Shopware: guia completo
> Apresentação O DataFirefly Server-Side é o conector Shopware gratuito do serviço DataFirefly Server-Side Tracking. A cada encomenda validada, a extensão constrói um evento de compra completo e envia-o de servidor…
- Página:
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/datafirefly-server-side-shopware/index.md), [en](https://www.datafirefly.com/en/documentation/datafirefly-server-side-shopware/index.md), [es](https://www.datafirefly.com/es/documentation/datafirefly-server-side-shopware/index.md), [de](https://www.datafirefly.com/de/documentation/datafirefly-server-side-shopware/index.md), [it](https://www.datafirefly.com/it/documentation/datafirefly-server-side-shopware/index.md), [pl](https://www.datafirefly.com/pl/documentation/datafirefly-server-side-shopware/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafirefly-server-side-shopware/index.md)
- Índice:
## Apresentação
O DataFirefly Server-Side é o conector Shopware gratuito do serviço [DataFirefly Server-Side Tracking](https://server-side.datafirefly.com/). A cada encomenda validada, a extensão constrói um evento de compra completo e envia-o de servidor para servidor, assinado com HMAC-SHA256, para o dispatcher DataFirefly alojado na UE. O serviço ingere o evento, desduplica-o e difunde-o para os seus destinos: Meta CAPI, GA4, TikTok Events API, Pinterest Conversions API e Google Ads.
A extensão é propositadamente minimalista do lado da loja: nenhuma credencial de destino fica aí guardada, nenhum script é acrescentado ao storefront, nenhuma tabela é criada. Capta, constrói, assina, envia; o resto acontece do lado do serviço.
**Modelo económico:** a extensão é gratuita; a difusão dos eventos exige uma subscrição do serviço (Starter 39 €/mês, Growth 119 €/mês, Scale 349 €/mês). Detalhes e subscrição em [server-side.datafirefly.com](https://server-side.datafirefly.com/).
## Pré-requisitos
- Shopware 6.5.x, 6.6.x ou 6.7.x (instalação auto-alojada; o Shopware Cloud não aceita extensões de servidor)
- PHP 8.1 ou superior, consoante a sua versão do Shopware, com a extensão curl
- Uma subscrição ativa do serviço DataFirefly Server-Side Tracking para obter a sua chave de ligação
## Instalação
### Por carregamento de ZIP
1. Na administração do Shopware, abra **Extensões → As minhas extensões → Carregar extensão** e selecione o ficheiro ZIP da extensão.
2. Clique em **Instalar** e depois em **Ativar**.
### Por linha de comandos
```
bin/console plugin:refresh
bin/console plugin:install --activate DatafireflyServerSide
bin/console cache:clear
```
A extensão não acrescenta nada ao storefront: nenhum `build-storefront` é necessário depois da instalação.
## Ligação ao serviço
### Obter a sua chave de ligação
1. Inicie sessão na sua área de cliente em [server-side.datafirefly.com](https://server-side.datafirefly.com/).
2. Abra a secção **Ligar a sua loja**.
3. Copie a chave de ligação numa linha, no formato `dfss_…`. Codifica o seu identificador de tenant, o seu segredo de assinatura HMAC e o endpoint de ingestão.
A chave de ligação contém o seu segredo de assinatura: mantenha-a confidencial, como uma palavra-passe. Em caso de fuga, gere uma nova a partir da área de cliente e substitua-a na configuração da extensão.
### Colar a chave no Shopware
1. Abra **Extensões → As minhas extensões → DataFirefly Server-Side → Configuração**.
2. Cole a chave no campo **Chave de ligação**.
3. Ative o interruptor **Ativar o tracking** e guarde.
É tudo: a partir da próxima encomenda validada, o evento de compra segue para o dispatcher. Uma chave em falta ou mal formada nunca é um erro bloqueante: a extensão considera simplesmente que não está configurada e não envia nada.
## Configuração
- **Ativar o tracking**: interruptor principal. Desativado por predefinição.
- **Chave de ligação**: a chave `dfss_…` copiada da sua área de cliente.
- **Exigir o consentimento de marketing**: ativa a barreira de consentimento (desativada por predefinição, ver abaixo).
- **Nome do cookie de consentimento**: o cookie colocado pela sua ferramenta de consentimento (CMP).
- **Valor do cookie de consentimento (contém)**: opcional; fragmento de valor esperado no cookie.
A configuração é gerida por sales channel: pode ativar o tracking numa loja e não noutra, ou usar chaves diferentes por canal.
## Barreira de consentimento
O Shopware não coloca nativamente um cookie único de consentimento de marketing legível do lado do servidor. A extensão oferece portanto uma barreira genérica, desativada por predefinição: quando está ativa, o evento de compra só é enviado se o cookie configurado estiver presente no pedido do cliente e, se estiver definido um valor esperado, se o valor do cookie o contiver.
### Com o DataFirefly Cookie Consent
A combinação recomendada no Shopware é a nossa extensão [DataFirefly Cookie Consent](https://www.datafirefly.com/pt/produto/df-cookie-consent/) (banner RGPD com Google Consent Mode v2 nativo): ative a barreira e indique o nome do cookie de consentimento colocado pelo banner (indicado na respetiva documentação). A recusa ou a ausência de consentimento de marketing bloqueia o envio, do lado do servidor, antes de qualquer transmissão.
### Com outro CMP
Indique o nome do cookie que o seu CMP coloca quando o visitante aceita os cookies de marketing (por exemplo `CookieConsent` para o Cookiebot), e eventualmente um fragmento de valor (por exemplo `marketing:true`). Se o seu CMP não colocar um cookie legível do lado do servidor, ou se gerir o consentimento inteiramente a montante, deixe a barreira desativada.
### Comportamento privacy-first
- Barreira ativa e nome de cookie não configurado → nada é enviado.
- Barreira ativa e cookie ausente ou vazio → nada é enviado.
- Barreira ativa e valor esperado configurado mas ausente do valor do cookie → nada é enviado.
- Pedido ausente (fluxo CLI ou headless sem pedido HTTP) → nada é enviado.
Em caso de dúvida, a extensão não envia: é uma opção de conceção. Nenhum evento pode partir «por acidente» sem consentimento quando a barreira está ativa.
## Testar a ligação
A extensão fornece um comando de consola que envia um `page_view` sintético para o dispatcher, sem tocar em encomendas reais:
```
bin/console datafirefly:serverside:test
```
Opções disponíveis:
- `--sales-channel-id=`: lê a configuração de um sales channel específico (por predefinição: configuração global).
- `--source-url=`: inclui um sourceUrl no evento de teste.
Um código HTTP 2xx confirma que a chave de ligação, a assinatura e o endpoint estão corretos, mesmo que ainda não haja qualquer destino configurado do lado do serviço.
## Funcionamento técnico
### O evento purchase
A extensão subscreve o evento de encomenda validada do Shopware. A cada acionamento, constrói um evento `purchase` com um identificador idempotente ligado à encomenda (`order_`): se usar também tags de navegador, o serviço aplica a desduplicação cliente mais servidor e cada conversão é contada uma só vez.
### Dados enviados
- **Transação:** valor pago, moeda, número de encomenda, produtos, quantidades, número de artigos.
- **Correspondência:** email, identificador de cliente, telefone, nome próprio, apelido, localidade, código postal e país da morada de facturação.
- **Identificadores de navegador** captados no momento da encomenda: `_fbp`, `_fbc`, `_ttp` e o client id do GA4 (cookie `_ga`).
A construção é defensiva: cada campo opcional só é acrescentado se estiver presente e válido (o dispatcher valida de forma estrita: país em 2 caracteres, moeda em 3, e assim por diante). Nos fluxos headless em que algumas associações da encomenda possam faltar, os campos correspondentes são simplesmente omitidos, nunca fabricados.
### Assinatura HMAC
Cada evento é assinado com HMAC-SHA256 usando o segredo do seu tenant: os bytes assinados são exatamente os bytes enviados, com uma marca temporal verificada numa janela de 300 segundos contra reprodução. Os cabeçalhos transmitidos são o identificador de tenant, o timestamp e a assinatura. As suas credenciais Meta, GA4, TikTok, Pinterest e Google Ads ficam do lado do serviço, nunca na loja e nunca no navegador.
### Fail-safe
Todo o subsistema está concebido para nunca afetar o checkout: timeouts de 2 segundos (ligação) e 4 segundos (total), todos os erros capturados e registados como warning nos logs do Shopware com o código HTTP e o número de encomenda, e nenhuma exceção chega ao funil de encomenda.
## Resolução de problemas
- **Nenhum evento é enviado**: verifique que o interruptor está ativo para o sales channel certo, que a chave começa por `dfss_` sem espaços nem quebras de linha, e que a barreira de consentimento não está ativa sem cookie configurado.
- **O comando de teste falha**: um código 0 com uma mensagem do curl indica um problema de rede de saída (firewall); um código 401/403 indica uma chave inválida ou regenerada: volte a copiá-la da área de cliente.
- **Eventos marcados como não entregues nos logs**: o código HTTP e o número de encomenda ficam registados nos logs do Shopware (canal warning). Um código 4xx assinala um payload rejeitado pela validação estrita do dispatcher; verifique o Event Inspector da sua área de cliente para os detalhes.
- **Conversões duplicadas no Meta ou no GA4**: confirme que as suas tags de navegador enviam o mesmo identificador de evento (`order_`) para beneficiar da desduplicação.
## Changelog
- **1.0.0** (01/07/2026): versão inicial: evento purchase server-side idempotente, assinatura HMAC-SHA256 com janela antirreprodução, chave de ligação numa linha, barreira de consentimento opt-in por cookie de CMP, configuração por sales channel, comando de consola de teste, conceção fail-safe.