# Carbon Footprint + Offset Checkout — Guida completa
> Installazione Carbon Footprint + Offset Checkout è un plugin WooCommerce standard, installabile come qualsiasi altra estensione. Scarica il file df-carbon-offset.zip dalla scheda prodotto DataFirefly. Nel back-office WordPress, vai su Plugin…
- Pagina:
- Lingua: it
- Aggiornato il: 2026-07-01
- Altre lingue: [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), [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), [pt](https://www.datafirefly.com/pt/documentation/carbon-footprint-offset-checkout/index.md)
- Indice:
## Installazione
Carbon Footprint + Offset Checkout è un plugin WooCommerce standard, installabile come qualsiasi altra estensione.
1. Scarica il file `df-carbon-offset.zip` dalla scheda prodotto DataFirefly.
2. Nel back-office WordPress, vai su **Plugin → Aggiungi nuovo → Carica plugin**.
3. Seleziona lo ZIP, clicca su **Installa ora**, poi su **Attiva**.
4. Una nuova voce **Carbon Footprint** appare nel menu laterale di WooCommerce.
**Requisiti:** WordPress 6.0+, WooCommerce 7.0+, PHP 7.4 minimo (PHP 8.1+ raccomandato). Il plugin dichiara esplicitamente la compatibilità con HPOS e Cart/Checkout Blocks — nessun avviso appare in WooCommerce Status.
All'attivazione, due tabelle SQL vengono create automaticamente: `{prefix}dfcarbon_factors` (fattori di emissione) e `{prefix}dfcarbon_log` (registro delle compensazioni). La base ADEME viene subito pre-caricata con circa 25 fattori.
## Configurazione iniziale
Il plugin funziona **zero-config** subito dopo l'attivazione: i fattori ADEME sono caricati, il badge appare su tutte le schede prodotto, la compensazione compare al checkout. Ma alcune regolazioni iniziali ti daranno cifre molto più precise.
### Impostazioni generali
Vai su **Carbon Footprint → Impostazioni**. Quattro blocchi di parametri:
- **API Climatiq** — opzionale. Lascia vuoto per un funzionamento 100% locale con i fattori ADEME.
- **Compensazione** — attivazione del blocco al checkout, prezzo per tonnellata (default 25 €/t, mercato tipico 15–30 €/t), partner mostrato (Gold Standard di default), descrizione per il cliente.
- **Trasporto** — attivazione della componente trasporto, distanza media in km (default 500 km), fattore di emissione del trasporto (default: trasporto su strada).
- **Visualizzazione** — posizione del badge sulla scheda (5 hook disponibili), stile (scheda, pillola, minimo), colore, priorità dell'hook.
### Mappatura categorie → fattori
È il passaggio più incisivo. Vai su **Carbon Footprint → Mappatura**. Per ogni categoria di prodotti WooCommerce, seleziona il fattore di emissione più rilevante tra quelli della base ADEME.
Senza mappatura, tutti i tuoi prodotti useranno il fattore `general` (4,50 kgCO₂e/kg), che è molto approssimativo. Una mappatura curata passa da _«ordine di grandezza»_ a _«stima credibile per reporting»_.
### Attivazione dell'API Climatiq (opzionale)
Climatiq è una base di oltre 80.000 fattori di emissione, più granulare della Base Empreinte ADEME su certi settori (elettronica dettagliata, cosmetica per componente, alimentare per filiera). Se hai una chiave:
1. Crea un account su `climatiq.io` (piano gratuito disponibile per uso moderato).
2. Incolla la chiave API in **Carbon Footprint → Impostazioni → API Climatiq**.
3. Clicca su **Testa connessione** per validare.
Una volta attivata, l'API Climatiq viene usata con priorità 2 (dopo un eventuale override manuale prodotto) e davanti alla mappatura ADEME. Ogni risultato viene messo in cache per una settimana — nessun costo aggiuntivo al rendering delle pagine.
## Come funziona il calcolo dell'impronta
### Priorità del calcolo
Per ogni prodotto, il plugin determina l'impronta secondo quattro fonti, in questo ordine rigido di priorità:
1. **Override manuale prodotto** — se hai inserito un valore nella tab «Carbon» della scheda (meta `_dfcarbon_kgco2e`), è quello che viene usato. Cortocircuita tutte le altre fonti.
2. **API Climatiq** — se una chiave API è configurata e il prodotto ha un peso o una categoria consultabile.
3. **Fattore ADEME tramite mappatura** — il fattore assegnato alla categoria del prodotto, applicato al peso.
4. **Fallback generale** — il fattore `general` (4,50 kgCO₂e/kg) applicato al peso, o un valore forfettario se non c'è peso.
Il calcolo viene messo in cache tramite l'API a oggetti di WordPress (gruppo `dfcarbon_product`) e invalidato automaticamente a ogni modifica di prodotto o mappatura.
### Componente trasporto
Se attivata, la componente trasporto si aggiunge all'impronta materiale:
```
impronta_totale = impronta_materiale + (peso_kg × distanza_km × fattore_trasporto_tkm)
```
Il fattore di trasporto su strada di default è 0,105 kgCO₂e per tonnellata-chilometro (fonte ADEME, camion pesante medio). Puoi cambiarlo nelle impostazioni, o passare a un altro fattore (marittimo, aereo, ecc.) se lo aggiungi alla base.
La componente trasporto copre solo il **trasporto a valle** (dal magazzino al cliente). L'impronta materiale del fattore ADEME include già la produzione e il trasporto a monte.
## Fattori di emissione ADEME inclusi
Il plugin viene fornito con circa 25 fattori pre-caricati dalla **Base Empreinte ADEME** (Francia). Principali settori coperti:
- **Tessile** — capo standard, cotone, lana, sintetico, calzature
- **Elettronica** — smartphone, portatile, piccoli elettrodomestici, grandi elettrodomestici
- **Alimentare** — bovino, suino, pollame, pesce, latticini, drogheria
- **Cosmetica** — cura del corpo, trucco, profumeria
- **Casa** — mobili legno, mobili metallo, tessili casa
- **Carta** — libro, rivista, imballaggio cartone
- **Sport** — attrezzatura sportiva, abbigliamento sportivo
- **Gioielleria** — bigiotteria, argento, oro
- **Trasporto** — trasporto su strada, trasporto marittimo
- **Fallback** — `general` (4,50 kgCO₂e/kg)
Puoi consultare, modificare, eliminare o aggiungere i tuoi fattori da **Carbon Footprint → Fattori**. Ogni fattore ha: uno slug univoco, un'etichetta, un valore in kgCO₂e/unità, un'unità (kg di default), una fonte (ADEME, Climatiq, personalizzato…) e un anno.
Un pulsante **Ricarica i valori ADEME predefiniti** permette di ripristinare la base originale _senza sovrascrivere le tue aggiunte personali_: solo gli slug ADEME mancanti vengono reinseriti.
## Il badge prodotto
### Stili disponibili
Tre rese tra cui scegliere (in **Impostazioni → Visualizzazione → Stile del badge**):
- **Scheda (dettagliata)** — blocco completo con impronta, fonte, due equivalenze pedagogiche (km in auto, anni d'albero) e prezzo di compensazione.
- **Pillola in linea** — badge compatto «🌱 5,2 kg CO₂e» accanto al prezzo.
- **Testo minimo** — solo il valore, senza riquadro.
### Posizioni
Il badge si aggancia a uno degli hook WooCommerce standard:
- `after_price` — subito dopo il prezzo (default)
- `before_add_to_cart` — prima del pulsante «aggiungi al carrello»
- `after_add_to_cart` — dopo il pulsante «aggiungi al carrello»
- `before_meta` — prima dei meta del prodotto
- `after_summary` — dopo il riepilogo completo del prodotto
Se nessuna posizione si adatta al tuo tema, usa lo shortcode `[dfcarbon_badge]` direttamente in un template o in un page builder (Elementor, Divi, Gutenberg…).
### Nascondere su alcuni prodotti
Nella tab **Carbon** di ogni scheda prodotto, spunta _«Nascondi il badge»_. Il calcolo dell'impronta resta attivo (utile per i report e il checkout), ma la visualizzazione pubblica scompare. Pratico per prodotti digitali, buoni regalo o servizi.
## Compensazione al checkout
Al checkout, il plugin inserisce un blocco tra il riepilogo ordine e il metodo di pagamento. Questo blocco contiene:
- L'impronta stimata del carrello (somma delle impronte di tutti gli articoli × le loro quantità)
- Il costo di compensazione corrispondente (impronta × prezzo per tonnellata)
- Una casella facoltativa «Sì, aggiungo X € per compensare l'impatto del mio ordine»
- Un testo descrittivo configurabile che menziona il partner (Gold Standard, Verra…)
Quando il cliente spunta la casella, un **fee dinamico WooCommerce** viene aggiunto al totale tramite l'hook `woocommerce_cart_calculate_fees`. Lo stato è salvato nella sessione WooCommerce (`dfcarbon_offset_active`), poi persistito sull'ordine tramite i meta `_dfcarbon_cart_kgco2e`, `_dfcarbon_offset_active`, `_dfcarbon_offset_amount` e `_dfcarbon_offset_provider`.
**Importante:** il plugin **raccoglie** la compensazione dai tuoi clienti — **non acquista** automaticamente i crediti di carbonio al tuo posto. È una scelta deliberata, per lasciarti il controllo su tempistica, canale e partner (Gold Standard, Verra, Ecologi, MyClimate…). La bacheca ti indica il totale da regolare a ogni ciclo di pagamento con il tuo partner.
## Bacheca e report
Il menu **Carbon Footprint → Bacheca** mostra gli indicatori globali:
- Numero totale di ordini compensati
- Impronta CO₂ cumulativa misurata sugli ordini
- Impronta CO₂ effettivamente compensata
- Importo totale investito in compensazione
Il menu **Carbon Footprint → Report** dettaglia ogni ordine compensato: data, numero ordine, impronta dell'ordine, kg compensati, importo, partner. Questa tabella alimenta direttamente il tuo reporting extra-finanziario CSRD o qualsiasi richiesta di audit ESG.
Uno snapshot di impronta viene anche conservato per riga d'ordine (meta `_dfcarbon_line_kgco2e`): i valori mostrati non cambiano retroattivamente quando modifichi un fattore ADEME in seguito.
## Shortcode disponibili
Tre shortcode pubblici per integrare gli elementi ovunque sul tuo sito:
```
[dfcarbon_badge id="123" style="card"]
```
Mostra il badge carbonio di un prodotto specifico. `id` è obbligatorio, `style` facoltativo (`card` di default, `pill`, `minimal`).
```
[dfcarbon_cart_summary]
```
Mostra l'impronta del carrello corrente e il costo di compensazione. Utile in una pagina «Il mio carrello» personalizzata o in una side-cart.
```
[dfcarbon_stats]
```
Blocco pubblico con statistiche aggregate: tonnellate compensate, numero di ordini, importo investito. Perfetto per una pagina «Il nostro impegno climatico».
## Hook e filtri per sviluppatori
Il plugin espone un filtro principale per sovrascrivere completamente il calcolo dell'impronta:
```
add_filter( 'dfcarbon_product_footprint', function( $footprint, $product_id, $context ) {
// $footprint è un array: ['kg' => 5.2, 'source' => 'ademe', 'breakdown' => [...]]
// Ritorna un array modificato per sovrascrivere
return $footprint;
}, 10, 3 );
```
Altri hook utili:
- `dfcarbon_daily_sync` — azione WP-Cron giornaliera (purga dei transient Climatiq)
- `dfcarbon_before_offset_fee` — azione prima dell'aggiunta del fee di compensazione
- `dfcarbon_offset_purchased` — azione scatenata alla persistenza sull'ordine
Il plugin usa il namespace PHP `DataFirefly\CarbonOffset`. Per aggiungere un fattore programmaticamente da un mu-plugin o da un tema figlio, importa la classe `Database`:
```
use DataFirefly\CarbonOffset\Database;
Database::upsert_factor( [
'slug' => 'mio-fattore',
'label' => 'Il mio settore specifico',
'value' => 2.35,
'unit' => 'kg',
'source' => 'Personalizzato',
'year' => 2026,
] );
```
## Multilingue (Polylang / WPML)
Il plugin è compatibile con Polylang Pro e WPML. Le 5 lingue fornite (FR, EN, ES, DE, IT) sono nella cartella `languages/` con i file `.po` e `.mo` già compilati.
Per modificare una traduzione:
1. Installa Loco Translate (plugin gratuito) o usa Poedit in locale.
2. Apri il catalogo `df-carbon-offset-it_IT.po`.
3. Modifica le voci.
4. Ricompila in `.mo` — automatico in Loco Translate.
Per aggiungere una lingua non fornita di default (portoghese, olandese…), duplica un `.po` esistente, rinominalo con il locale corretto (`df-carbon-offset-pt_PT.po`, `df-carbon-offset-nl_NL.po`…), traduci e compila.
## Disinstallazione
Il plugin pulisce accuratamente alla disinstallazione tramite `uninstall.php`:
- Elimina le tabelle `dfcarbon_factors` e `dfcarbon_log`
- Elimina le opzioni `dfcarbon_settings` e `dfcarbon_db_version`
- Elimina i postmeta `_dfcarbon_*` da tutti i prodotti e ordini
- Disiscrizione del cron `dfcarbon_daily_sync`
- Purga dei transient Climatiq
La disinstallazione è **distruttiva**: il registro delle compensazioni passate viene eliminato. Se devi conservarlo per un audit CSRD, esporta la tabella `Report` prima di disinstallare.
## FAQ
### Posso forzare un fattore specifico su un prodotto senza cambiare la sua categoria?
Sì. Nella tab Carbon della scheda, seleziona un fattore nel menu a tendina «Fattore di emissione». Prevale sulla mappatura di categoria solo per quel prodotto.
### Cosa succede se il mio prodotto non ha peso?
Il calcolo usa un valore forfettario per i prodotti senza peso (trattati come «unità»). Puoi anche usare l'override manuale per inserire direttamente il valore in kg CO₂e.
### Il plugin funziona con i prodotti variabili?
Sì. L'impronta viene calcolata a livello di prodotto padre (tramite il suo peso e categoria), il che resta coerente nella maggior parte dei casi. Per un controllo per variazione, usa il filtro `dfcarbon_product_footprint`.
### Come gestisco i prodotti scaricabili (digitali)?
Per un prodotto puramente digitale (ebook, corso online, licenza software), spunta «Nascondi il badge» e lascia il calcolo cadere sul fallback generale (l'impatto sarà minimo se il prodotto non ha peso). Alternativa: usa l'override manuale con un valore piccolo (tipicamente 0,01 a 0,1 kg CO₂e per un ebook).
### Posso escludere un prodotto dalla compensazione al checkout?
La compensazione si applica al carrello nel suo insieme, non prodotto per prodotto. Per escludere totalmente un prodotto dal calcolo, usa il filtro `dfcarbon_product_footprint` restituendo un array con `['kg' => 0]`.
### Il plugin fa chiamate API a ogni visualizzazione di pagina?
No. Ogni impronta prodotto è messa in cache tramite l'API a oggetti di WordPress. Le chiamate Climatiq (se attive) sono a loro volta memorizzate in transient per una settimana. Una pagina prodotto non fa alcuna chiamata esterna.
### Compatibile con le cache (WP Rocket, Litespeed, W3TC)?
Sì, totalmente. Il rendering del badge è lato server. La parte dinamica (casella di compensazione al checkout) è gestita in AJAX e non influisce sulla cache della scheda prodotto.