# Carbon Footprint + Offset Checkout: guia completo

> Instalação O Carbon Footprint + Offset Checkout é um plugin WooCommerce padrão, instalável como qualquer extensão. Descarregue o ZIP df-carbon-offset.zip a partir da ficha de produto DataFirefly. No seu back-office…

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

## Instalação

O Carbon Footprint + Offset Checkout é um plugin WooCommerce padrão, instalável como qualquer extensão.

1. Descarregue o ZIP `df-carbon-offset.zip` a partir da ficha de produto DataFirefly.
2. No seu back-office WordPress, vá a **Plugins → Adicionar → Carregar plugin**.
3. Selecione o ficheiro ZIP, clique em **Instalar agora** e depois em **Ativar**.
4. Aparece uma nova entrada **Carbon Footprint** no menu lateral do WooCommerce.

**Requisitos:** WordPress 6.0 ou superior, WooCommerce 7.0 ou superior, PHP 7.4 no mínimo (recomendado PHP 8.1+). O plugin declara explicitamente a compatibilidade com HPOS e com os Cart/Checkout Blocks, pelo que não aparece qualquer aviso no Estado do WooCommerce.

Na ativação, são criadas automaticamente duas tabelas SQL: `{prefix}dfcarbon_factors` (fatores de emissão) e `{prefix}dfcarbon_log` (registo das compensações). A base da ADEME é logo inicializada com cerca de 25 fatores pré-carregados.

## Configuração inicial

O plugin funciona **sem configuração** logo na ativação: os fatores da ADEME são carregados, o distintivo aparece em todas as fichas de produto, e a compensação surge no checkout. Mas alguns ajustes iniciais dão-lhe números bem mais pertinentes.

### Definições gerais

Vá a **Carbon Footprint → Definições**. Quatro blocos de parâmetros:

- **API Climatiq**: opcional. Deixe vazio para um funcionamento 100% local sobre os fatores da ADEME.
- **Compensação**: ativação do bloco no checkout, preço por tonelada (25 €/t por predefinição, mercado típico entre 15 e 30 €/t), parceiro apresentado (Gold Standard por predefinição) e descrição para o cliente.
- **Transporte**: ativação da componente de transporte, distância média em km (500 km por predefinição) e fator de emissão do transporte (por predefinição, transporte rodoviário).
- **Apresentação**: posição do distintivo na ficha de produto (5 hooks disponíveis), estilo (cartão, pastilha, mínimo), cor e prioridade do hook.

### Mapeamento de categorias para fatores

É a etapa com mais impacto. Vá a **Carbon Footprint → Mapeamento**. Para cada categoria de produtos do WooCommerce, selecione o fator de emissão mais pertinente entre os da base da ADEME.

Sem mapeamento, todos os seus produtos usam o fator `general` (4,50 kgCO₂e/kg), o que é muito aproximativo. Um mapeamento cuidado faz passar de _«ordem de grandeza»_ a _«estimativa credível para relato»_.

### Ativação da API Climatiq (opcional)

A Climatiq é uma base de mais de 80 000 fatores de emissão, mais fina do que a Base Empreinte da ADEME em certos setores (eletrónica detalhada, cosmética por componente, agroalimentar por fileira). Se tiver uma chave:

1. Crie uma conta em `climatiq.io` (existe uma oferta gratuita para utilização moderada).
2. Copie a chave de API para **Carbon Footprint → Definições → Climatiq API**.
3. Clique em **Testar a ligação** para validar.

Depois de ativada, a API Climatiq é usada com prioridade 2 (depois de um eventual valor manual do produto) e à frente do mapeamento da ADEME. Cada resultado fica em cache durante uma semana, sem qualquer custo adicional de chamadas na apresentação das páginas.

## Como funciona o cálculo da pegada

### Prioridades do cálculo

Para cada produto, o plugin determina a pegada a partir de quatro fontes, nesta ordem estrita de prioridade:

1. **Valor manual do produto**: se tiver introduzido um valor no separador «Carbon» da ficha de produto (meta `_dfcarbon_kgco2e`), é esse que é usado. Sobrepõe-se a todas as outras fontes.
2. **API Climatiq**: se estiver configurada uma chave de API e o produto tiver um peso ou uma categoria consultável.
3. **Fator da ADEME através do mapeamento**: o fator atribuído à categoria do produto, aplicado ao peso.
4. **Recurso geral**: o fator `general` (4,50 kgCO₂e/kg) aplicado ao peso, ou um valor fixo se o peso não estiver preenchido.

O cálculo é colocado em cache através da API de objetos do WordPress (grupo `dfcarbon_product`) e invalidado automaticamente a cada alteração de ficha de produto ou de mapeamento.

### Componente de transporte

Se estiver ativa, a componente de transporte é acrescentada à pegada material:

```
pegada_total = pegada_material + (peso_kg × distancia_km × fator_transporte_tkm)
```

O fator de transporte rodoviário predefinido é de 0,105 kgCO₂e por tonelada-quilómetro (fonte ADEME, veículo pesado médio). Pode alterar o fator de transporte nas definições, ou passar para outro fator (transporte marítimo, aéreo, etc.) se o acrescentar à base.

A componente de transporte diz respeito apenas ao **transporte a jusante** (do armazém para o cliente). A pegada material do fator da ADEME já inclui a produção e o transporte a montante.

## Fatores de emissão da ADEME incluídos

O plugin é entregue com cerca de 25 fatores pré-carregados, provenientes da **Base Empreinte da ADEME** (França). Os principais setores cobertos:

- **Têxtil**: peça de vestuário padrão, algodão, lã, sintético, calçado
- **Eletrónica**: smartphone, computador portátil, pequenos e grandes eletrodomésticos
- **Alimentar**: bovino, suíno, aves, peixe, laticínios, mercearia seca
- **Cosmética**: cuidado corporal, maquilhagem, perfumaria
- **Casa**: mobiliário em madeira, mobiliário em metal, têxteis-lar
- **Papel**: livro, revista, cartão de embalagem
- **Desporto**: equipamento desportivo, vestuário de desporto
- **Joalharia**: bijuteria, prata, ouro
- **Transporte**: transporte rodoviário, transporte marítimo
- **Recurso**: `general` (4,50 kgCO₂e/kg)

Pode consultar, editar, eliminar ou acrescentar os seus próprios fatores em **Carbon Footprint → Fatores**. Cada fator tem: um slug único, uma designação, um valor em kgCO₂e por unidade, uma unidade (kg por predefinição), uma fonte (ADEME, Climatiq, personalizado...) e um ano.

Um botão **Recarregar os valores predefinidos da ADEME** permite restaurar a base de origem _sem substituir os seus acrescentos pessoais_: só os slugs da ADEME em falta são reinseridos.

## O distintivo de produto

### Estilos disponíveis

Três apresentações à escolha (ajustável em **Definições → Apresentação → Estilo do distintivo**):

- **Cartão (detalhado)**: bloco completo com a pegada, a fonte, duas equivalências pedagógicas (km de automóvel, anos de árvore) e o preço da compensação.
- **Pastilha em linha**: distintivo compacto «🌱 5,2 kg CO₂e» ao lado do preço.
- **Texto mínimo**: apenas o valor, sem caixa.

### Posições

O distintivo liga-se a um dos hooks padrão do WooCommerce:

- `after_price`: logo a seguir ao preço (predefinido)
- `before_add_to_cart`: antes do botão de adição ao carrinho
- `after_add_to_cart`: depois do botão de adição ao carrinho
- `before_meta`: antes dos metadados do produto
- `after_summary`: depois do resumo completo do produto

Se nenhuma posição servir ao seu tema, pode usar o shortcode `[dfcarbon_badge]` diretamente num template ou num construtor visual (Elementor, Divi, Gutenberg...).

### Ocultar em determinados produtos

No separador **Carbon** de cada ficha de produto, assinale _«Ocultar o distintivo»_. O cálculo da pegada mantém-se ativo (útil para os relatórios e para o checkout), mas a apresentação pública desaparece. Prático para os produtos desmaterializados, os vales de oferta ou os serviços.

## Compensação no checkout

No checkout, o plugin insere um bloco entre o resumo da encomenda e o modo de pagamento. Esse bloco contém:

- A pegada estimada do carrinho (soma das pegadas de todos os artigos multiplicadas pelas respetivas quantidades)
- O custo de compensação correspondente (pegada multiplicada pelo preço por tonelada)
- Uma caixa de seleção opcional «Sim, acrescento X € para compensar o impacto da minha encomenda»
- Um texto descritivo configurável que menciona o parceiro (Gold Standard, Verra...)

Quando o cliente assinala a caixa, é acrescentada ao total uma **taxa dinâmica do WooCommerce** através do hook `woocommerce_cart_calculate_fees`. O estado é guardado na sessão do WooCommerce (`dfcarbon_offset_active`) e depois persistido na encomenda através das metas `_dfcarbon_cart_kgco2e`, `_dfcarbon_offset_active`, `_dfcarbon_offset_amount` e `_dfcarbon_offset_provider`.

**Importante:** o plugin **recolhe** a compensação junto dos seus clientes, mas **não compra** os créditos de carbono por si. É uma opção deliberada, para o deixar senhor do momento, do canal e do parceiro (Gold Standard, Verra, Ecologi, MyClimate...). O painel indica-lhe o total a liquidar em cada ciclo de pagamento junto do seu parceiro.

## Painel e relatórios

O menu **Carbon Footprint → Painel** mostra os indicadores globais:

- Número total de encomendas compensadas
- Pegada de CO₂ acumulada medida nas encomendas
- Pegada de CO₂ efetivamente compensada
- Montante total investido em compensação

O menu **Carbon Footprint → Relatórios** detalha cada encomenda compensada: data, número de encomenda, pegada da encomenda, kg compensados, montante e parceiro. Esta tabela alimenta diretamente o seu relato não financeiro CSRD ou qualquer pedido de auditoria de sustentabilidade.

É também conservado um instantâneo da pegada por linha de encomenda (meta `_dfcarbon_line_kgco2e`): os valores apresentados não mudam retroativamente quando altera um fator da ADEME mais tarde.

## Shortcodes disponíveis

Três shortcodes públicos para integrar os elementos em qualquer ponto do seu site:

```
[dfcarbon_badge id="123" style="card"]
```

Apresenta o distintivo de carbono de um produto específico. O `id` é obrigatório e o `style` é opcional (`card` por predefinição, `pill`, `minimal`).

```
[dfcarbon_cart_summary]
```

Apresenta a pegada do carrinho atual e o custo de compensação. Útil numa página «O meu carrinho» personalizada ou num carrinho lateral.

```
[dfcarbon_stats]
```

Bloco público com as estatísticas agregadas: toneladas compensadas, número de encomendas e montante investido. Ideal para uma página «O nosso compromisso climático».

## Hooks e filtros para programadores

O plugin expõe um filtro principal para substituir por completo o cálculo da pegada:

```
add_filter( 'dfcarbon_product_footprint', function( $footprint, $product_id, $context ) {
    // $footprint é um array: ['kg' => 5.2, 'source' => 'ademe', 'breakdown' => [...]]
    // Devolva um array alterado para sobrepor
    return $footprint;
}, 10, 3 );
```

Outros hooks úteis:

- `dfcarbon_daily_sync`: ação diária do WP-Cron (limpeza dos transientes da Climatiq)
- `dfcarbon_before_offset_fee`: ação antes de acrescentar a taxa de compensação
- `dfcarbon_offset_purchased`: ação acionada na persistência sobre a encomenda

O plugin usa o namespace PHP `DataFirefly\CarbonOffset`. Para acrescentar um fator por programação a partir de um mu-plugin ou de um tema-filho, importe a classe `Database`:

```
use DataFirefly\CarbonOffset\Database;

Database::upsert_factor( [
    'slug'   => 'o-meu-fator',
    'label'  => 'O meu setor específico',
    'value'  => 2.35,
    'unit'   => 'kg',
    'source' => 'Personalizado',
    'year'   => 2026,
] );
```

## Multilingue (Polylang / WPML)

O plugin é compatível com o Polylang Pro e o WPML. Os 5 idiomas fornecidos (FR, EN, ES, DE, IT) estão na pasta `languages/` com os ficheiros `.po` e `.mo` já compilados.

Para ajustar uma tradução:

1. Instale o Loco Translate (plugin gratuito) ou use o Poedit localmente.
2. Abra o catálogo `df-carbon-offset-fr_FR.po`.
3. Edite as entradas a traduzir.
4. Recompile em `.mo`, o que é automático no Loco Translate.

Para acrescentar um idioma não fornecido (português, neerlandês...), duplique um `.po` existente, mude-lhe o nome para a locale certa (`df-carbon-offset-pt_PT.po`, `df-carbon-offset-nl_NL.po`...), traduza e compile.

## Desinstalação

O plugin faz uma limpeza correta na desinstalação, através do `uninstall.php`:

- Eliminação das tabelas `dfcarbon_factors` e `dfcarbon_log`
- Eliminação das opções `dfcarbon_settings` e `dfcarbon_db_version`
- Eliminação das postmeta `_dfcarbon_*` em todos os produtos e encomendas
- Desagendamento do cron `dfcarbon_daily_sync`
- Limpeza dos transientes da Climatiq

A desinstalação é **destrutiva**: o registo das compensações passadas é eliminado. Se precisar de o conservar para uma auditoria CSRD, exporte a tabela `Relatórios` antes da remoção.

## FAQ

### Posso forçar um fator específico num produto sem mudar a sua categoria?

Sim. No separador Carbon da ficha de produto, selecione um fator no menu pendente «Fator de emissão». Prevalece sobre o mapeamento de categoria apenas nesse produto.

### O que acontece se o meu produto não tiver peso?

O cálculo usa um valor fixo para os produtos sem peso (tratados como «unidade»). Também pode usar o valor manual para introduzir diretamente o valor em kg CO₂e.

### O plugin funciona com produtos variáveis?

Sim. A pegada é calculada ao nível do produto principal (pelo seu peso e pela sua categoria), o que se mantém coerente na maioria dos casos. Para um controlo por variação, use o filtro `dfcarbon_product_footprint`.

### Como gerir os produtos descarregáveis (desmaterializados)?

Num produto puramente desmaterializado (ebook, formação online, licença de software), assinale «Ocultar o distintivo» e deixe o cálculo recair no recurso geral (o impacto será mínimo se o produto não tiver peso). Alternativa: use o valor manual com um valor pequeno (tipicamente 0,01 a 0,1 kg CO₂e para um ebook).

### Posso excluir um produto da compensação no checkout?

A compensação aplica-se ao carrinho no seu conjunto, e não produto a produto. Se um produto tiver de ser totalmente excluído do cálculo, use o filtro `dfcarbon_product_footprint` para devolver um array com `['kg' => 0]`.

### O plugin faz chamadas à API em cada página vista?

Não. Cada pegada de produto é colocada em cache através da API de objetos do WordPress. As chamadas à Climatiq (se estiverem ativas) ficam elas próprias em cache num transiente durante uma semana. Uma página de produto não desencadeia qualquer chamada externa.

### É compatível com as caches (WP Rocket, LiteSpeed, W3TC)?

Sim, por completo. A apresentação do distintivo é estática do lado do servidor. A parte dinâmica (caixa de compensação no checkout) é gerida em AJAX e não afeta a colocação em cache da ficha de produto.