Carbon Footprint + Offset Checkout: guia completo

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.

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.

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.

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.

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

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.