# Carbon Footprint + Offset Checkout — Guide complet
> Installation Carbon Footprint + Offset Checkout est un plugin WooCommerce standard, installable comme n'importe quelle extension. Téléchargez le ZIP df-carbon-offset.zip depuis la fiche produit DataFirefly. Dans votre back-office WordPress, allez…
- Page:
- Langue: fr
- Mis à jour le: 2026-07-01
- Autres langues: [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), [pt](https://www.datafirefly.com/pt/documentation/carbon-footprint-offset-checkout/index.md)
- Index:
## Installation
Carbon Footprint + Offset Checkout est un plugin WooCommerce standard, installable comme n'importe quelle extension.
1. Téléchargez le ZIP `df-carbon-offset.zip` depuis la fiche produit DataFirefly.
2. Dans votre back-office WordPress, allez sur **Extensions → Ajouter → Téléverser une extension**.
3. Sélectionnez le fichier ZIP, cliquez sur **Installer maintenant**, puis sur **Activer**.
4. Une nouvelle entrée **Carbon Footprint** apparaît dans le menu latéral WooCommerce.
**Prérequis :** WordPress 6.0 ou plus, WooCommerce 7.0 ou plus, PHP 7.4 minimum (PHP 8.1+ recommandé). Le plugin déclare explicitement sa compatibilité HPOS et Cart/Checkout Blocks — aucun avertissement n'apparaît dans WooCommerce Status.
À l'activation, deux tables SQL sont créées automatiquement : `{prefix}dfcarbon_factors` (facteurs d'émission) et `{prefix}dfcarbon_log` (journal des compensations). La base ADEME est immédiatement seedée avec environ 25 facteurs pré-chargés.
## Configuration initiale
Le plugin fonctionne **zero-config** dès l'activation : les facteurs ADEME sont chargés, le badge s'affiche sur toutes les fiches produit, la compensation apparaît au checkout. Mais quelques ajustements initiaux vous donneront des chiffres bien plus pertinents.
### Réglages généraux
Allez sur **Carbon Footprint → Réglages**. Quatre blocs de paramètres :
- **API Climatiq** — optionnelle. Laissez vide pour un fonctionnement 100% local sur les facteurs ADEME.
- **Compensation** — activation du bloc au checkout, prix par tonne (défaut 25 €/t, marché typique 15–30 €/t), partenaire affiché (Gold Standard par défaut), description client.
- **Transport** — activation de la composante transport, distance moyenne en km (défaut 500 km), facteur d'émission transport (défaut : transport routier).
- **Affichage** — position du badge sur la fiche produit (5 hooks disponibles), style (carte, pastille, minimal), couleur, priorité du hook.
### Mapping catégories → facteurs
C'est l'étape la plus impactante. Allez sur **Carbon Footprint → Mapping**. Pour chaque catégorie de produits WooCommerce, sélectionnez le facteur d'émission le plus pertinent parmi ceux de la base ADEME.
Sans mapping, tous vos produits utiliseront le facteur `general` (4,50 kgCO₂e/kg), ce qui est très approximatif. Un mapping soigné passe de _« ordre de grandeur »_ à _« estimation crédible pour reporting »_.
### Activation de l'API Climatiq (optionnelle)
Climatiq est une base de plus de 80 000 facteurs d'émission, plus fine que la Base Empreinte ADEME sur certains secteurs (électronique détaillée, cosmétique par composant, agroalimentaire par filière). Si vous avez une clé :
1. Créez un compte sur `climatiq.io` (offre gratuite disponible pour un usage modéré).
2. Copiez la clé API dans **Carbon Footprint → Réglages → Climatiq API**.
3. Cliquez sur **Tester la connexion** pour valider.
Une fois activée, l'API Climatiq est utilisée en priorité 2 (après un éventuel override manuel produit) et devant le mapping ADEME. Chaque résultat est mis en cache une semaine — aucun surcoût d'appel au rendu des pages.
## Comment fonctionne le calcul d'empreinte
### Priorités du calcul
Pour chaque produit, le plugin détermine l'empreinte via quatre sources, dans cet ordre strict de priorité :
1. **Override manuel produit** — si vous avez saisi une valeur dans l'onglet « Carbon » de la fiche produit (meta `_dfcarbon_kgco2e`), c'est celle-ci qui est utilisée. Elle court-circuite toutes les autres sources.
2. **API Climatiq** — si une clé API est configurée et que le produit a un poids ou une catégorie interrogeable.
3. **Facteur ADEME via mapping** — le facteur assigné à la catégorie du produit, appliqué au poids.
4. **Fallback général** — le facteur `general` (4,50 kgCO₂e/kg) appliqué au poids, ou une valeur forfaitaire si le poids n'est pas renseigné.
Le calcul est mis en cache via l'API objet WordPress (groupe `dfcarbon_product`) et invalidé automatiquement à chaque modification de fiche produit ou de mapping.
### Composante transport
Si activée, la composante transport est ajoutée à l'empreinte matière :
```
empreinte_totale = empreinte_matière + (poids_kg × distance_km × facteur_transport_tkm)
```
Le facteur transport routier par défaut est de 0,105 kgCO₂e par tonne-kilomètre (source ADEME, poids lourd moyen). Vous pouvez changer le facteur transport dans les réglages, ou basculer sur un autre facteur (transport maritime, aérien, etc.) si vous en ajoutez à la base.
La composante transport ne concerne que le **transport aval** (de l'entrepôt vers le client). L'empreinte matière du facteur ADEME inclut déjà la production et le transport amont.
## Facteurs d'émission ADEME inclus
Le plugin est livré avec environ 25 facteurs pré-chargés, issus de la **Base Empreinte ADEME** (France). Les principaux secteurs couverts :
- **Textile** — vêtement standard, coton, laine, synthétique, chaussures
- **Électronique** — smartphone, ordinateur portable, petit électroménager, gros électroménager
- **Alimentaire** — bovin, porc, volaille, poisson, produits laitiers, épicerie sèche
- **Cosmétique** — soin corps, maquillage, parfumerie
- **Maison** — mobilier bois, mobilier métal, textile de maison
- **Papier** — livre, magazine, carton d'emballage
- **Sport** — équipement sportif, vêtement sport
- **Bijoux** — bijouterie fantaisie, argent, or
- **Transport** — transport routier, transport maritime
- **Fallback** — `general` (4,50 kgCO₂e/kg)
Vous pouvez consulter, éditer, supprimer ou ajouter vos propres facteurs depuis **Carbon Footprint → Facteurs**. Chaque facteur possède : un slug unique, un libellé, une valeur en kgCO₂e/unité, une unité (kg par défaut), une source (ADEME, Climatiq, personnalisé…) et une année.
Un bouton **Recharger les valeurs ADEME par défaut** permet de restaurer la base d'origine _sans écraser vos ajouts personnels_ : seuls les slugs ADEME manquants seront réinsérés.
## Le badge produit
### Styles disponibles
Trois rendus au choix (réglable dans **Réglages → Affichage → Style du badge**) :
- **Carte (détaillée)** — bloc complet avec l'empreinte, la source, deux équivalences pédagogiques (km voiture, années d'arbre) et le prix de compensation.
- **Pastille en ligne** — badge compact « 🌱 5,2 kg CO₂e » à côté du prix.
- **Texte minimal** — juste la valeur, sans encadré.
### Positions
Le badge s'accroche à l'un des hooks WooCommerce standards :
- `after_price` — juste après le prix (défaut)
- `before_add_to_cart` — avant le bouton d'ajout au panier
- `after_add_to_cart` — après le bouton d'ajout au panier
- `before_meta` — avant les métadonnées produit
- `after_summary` — après le résumé complet du produit
Si aucune position ne convient à votre thème, vous pouvez utiliser le shortcode `[dfcarbon_badge]` directement dans un template ou un builder visuel (Elementor, Divi, Gutenberg…).
### Masquer sur certains produits
Dans l'onglet **Carbon** de chaque fiche produit, cochez _« Masquer le badge »_. Le calcul d'empreinte reste actif (utile pour les rapports et le checkout), mais l'affichage public disparaît. Pratique pour les produits dématérialisés, les cartes cadeaux ou les services.
## Compensation au checkout
Au checkout, le plugin insère un bloc entre le récapitulatif de commande et le mode de paiement. Ce bloc contient :
- L'empreinte estimée du panier (somme des empreintes de tous les articles × leurs quantités)
- Le coût de compensation correspondant (empreinte × prix par tonne)
- Une case à cocher optionnelle « Oui, j'ajoute X € pour compenser l'impact de ma commande »
- Un texte descriptif configurable mentionnant le partenaire (Gold Standard, Verra…)
Quand le client coche la case, un **fee WooCommerce dynamique** est ajouté au total via le hook `woocommerce_cart_calculate_fees`. L'état est stocké dans la session WooCommerce (`dfcarbon_offset_active`), puis persisté sur la commande via les metas `_dfcarbon_cart_kgco2e`, `_dfcarbon_offset_active`, `_dfcarbon_offset_amount` et `_dfcarbon_offset_provider`.
**Important :** le plugin **collecte** la compensation auprès de vos clients — il **n'achète pas** les crédits carbone à votre place. C'est un choix délibéré, pour vous laisser maître du timing, du canal et du partenaire (Gold Standard, Verra, Ecologi, MyClimate…). Le tableau de bord vous indique le total à honorer à chaque cycle de paiement chez votre partenaire.
## Tableau de bord et rapports
Le menu **Carbon Footprint → Tableau de bord** affiche les indicateurs globaux :
- Nombre total de commandes compensées
- Empreinte CO₂ cumulée mesurée sur les commandes
- Empreinte CO₂ effectivement compensée
- Montant total investi en compensation
Le menu **Carbon Footprint → Rapports** détaille chaque commande compensée : date, numéro de commande, empreinte de la commande, kg compensés, montant, partenaire. Ce tableau alimente directement votre reporting extra-financier CSRD ou toute demande d'audit RSE.
Un snapshot d'empreinte est aussi conservé par ligne de commande (meta `_dfcarbon_line_kgco2e`) : les valeurs affichées ne changent pas rétrospectivement quand vous modifiez un facteur ADEME plus tard.
## Shortcodes disponibles
Trois shortcodes publics pour intégrer les éléments partout dans votre site :
```
[dfcarbon_badge id="123" style="card"]
```
Affiche le badge carbone d'un produit spécifique. `id` est obligatoire, `style` optionnel (`card` par défaut, `pill`, `minimal`).
```
[dfcarbon_cart_summary]
```
Affiche l'empreinte du panier en cours et le coût de compensation. Utile dans une page « Mon panier » personnalisée ou dans une side-cart.
```
[dfcarbon_stats]
```
Bloc public avec les statistiques agrégées : tonnes compensées, nombre de commandes, montant investi. Parfait pour une page « Notre engagement climat ».
## Hooks & filtres pour développeurs
Le plugin expose un filtre principal pour override complet du calcul d'empreinte :
```
add_filter( 'dfcarbon_product_footprint', function( $footprint, $product_id, $context ) {
// $footprint est un array : ['kg' => 5.2, 'source' => 'ademe', 'breakdown' => [...]]
// Retournez un array modifié pour surcharger
return $footprint;
}, 10, 3 );
```
Autres hooks utiles :
- `dfcarbon_daily_sync` — action WP-Cron quotidienne (purge des transients Climatiq)
- `dfcarbon_before_offset_fee` — action avant l'ajout du fee de compensation
- `dfcarbon_offset_purchased` — action déclenchée à la persistance sur commande
Le plugin utilise le namespace PHP `DataFirefly\CarbonOffset`. Pour ajouter un facteur programmatique depuis un mu-plugin ou un thème enfant, importez la classe `Database` :
```
use DataFirefly\CarbonOffset\Database;
Database::upsert_factor( [
'slug' => 'mon-facteur',
'label' => 'Mon secteur particulier',
'value' => 2.35,
'unit' => 'kg',
'source' => 'Personnalisé',
'year' => 2026,
] );
```
## Multilingue (Polylang / WPML)
Le plugin est compatible avec Polylang Pro et WPML. Les 5 langues fournies (FR, EN, ES, DE, IT) sont dans le dossier `languages/` avec les fichiers `.po` et `.mo` déjà compilés.
Pour ajuster une traduction :
1. Installez Loco Translate (plugin gratuit) ou utilisez Poedit en local.
2. Ouvrez le catalogue `df-carbon-offset-fr_FR.po`.
3. Éditez les entrées à traduire.
4. Recompilez en `.mo` — automatique dans Loco Translate.
Pour ajouter une nouvelle langue non fournie (portugais, néerlandais…), dupliquez un `.po` existant, renommez-le au bon locale (`df-carbon-offset-pt_PT.po`, `df-carbon-offset-nl_NL.po`…), traduisez et compilez.
## Désinstallation
Le plugin nettoie proprement à la désinstallation via `uninstall.php` :
- Suppression des tables `dfcarbon_factors` et `dfcarbon_log`
- Suppression des options `dfcarbon_settings` et `dfcarbon_db_version`
- Suppression des postmeta `_dfcarbon_*` sur tous les produits et commandes
- Désinscription du cron `dfcarbon_daily_sync`
- Purge des transients Climatiq
La désinstallation est **destructive** : le journal des compensations passées est supprimé. Si vous avez besoin de le conserver pour un audit CSRD, exportez le tableau `Rapports` avant la suppression.
## FAQ
### Puis-je forcer un facteur spécifique sur un produit sans changer sa catégorie ?
Oui. Dans l'onglet Carbon de la fiche produit, sélectionnez un facteur dans le menu déroulant « Facteur d'émission ». Il l'emporte sur le mapping de catégorie pour ce produit uniquement.
### Que se passe-t-il si mon produit n'a pas de poids ?
Le calcul utilise une valeur forfaitaire pour les produits sans poids (traités comme « unité »). Vous pouvez aussi utiliser l'override manuel pour saisir directement la valeur en kg CO₂e.
### Le plugin fonctionne-t-il avec les produits variables ?
Oui. L'empreinte est calculée au niveau du produit parent (via son poids et sa catégorie), ce qui reste cohérent pour la plupart des cas. Pour un contrôle par variation, utilisez le filtre `dfcarbon_product_footprint`.
### Comment gérer les produits téléchargeables (dématérialisés) ?
Pour un produit purement dématérialisé (ebook, formation en ligne, licence logicielle), cochez « Masquer le badge » et laissez le calcul retomber sur le fallback général (l'impact sera minimal si le produit n'a pas de poids). Alternative : utilisez l'override manuel avec une petite valeur (typiquement 0,01 à 0,1 kg CO₂e pour un ebook).
### Puis-je exclure un produit de la compensation au checkout ?
La compensation s'applique au panier dans son ensemble, pas produit par produit. Si un produit doit être totalement exclu du calcul, utilisez le filtre `dfcarbon_product_footprint` pour retourner un array avec `['kg' => 0]`.
### Le plugin fait-il des appels API à chaque page vue ?
Non. Chaque empreinte produit est mise en cache via l'API objet WordPress. Les appels Climatiq (si activés) sont eux-mêmes cachés en transient pendant une semaine. Une page produit ne déclenche aucun appel externe.
### Compatible avec les caches (WP Rocket, Litespeed, W3TC) ?
Oui, entièrement. Le rendu du badge est statique côté serveur. La partie dynamique (checkbox de compensation au checkout) est gérée en AJAX et n'affecte pas la mise en cache de la fiche produit.