# Carbon Footprint + Offset Checkout — Guía completa > Instalación Carbon Footprint + Offset Checkout es un plugin WooCommerce estándar, instalable como cualquier otra extensión. Descarga el archivo df-carbon-offset.zip desde la ficha de producto DataFirefly. En tu back-office WordPress,… - Página: - Idioma: es - Actualizado el: 2026-07-01 - Otros 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), [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) - Índice: ## Instalación Carbon Footprint + Offset Checkout es un plugin WooCommerce estándar, instalable como cualquier otra extensión. 1. Descarga el archivo `df-carbon-offset.zip` desde la ficha de producto DataFirefly. 2. En tu back-office WordPress, ve a **Plugins → Añadir nuevo → Subir plugin**. 3. Selecciona el ZIP, haz clic en **Instalar ahora**, luego en **Activar**. 4. Una nueva entrada **Carbon Footprint** aparece en el menú lateral de WooCommerce. **Requisitos:** WordPress 6.0+, WooCommerce 7.0+, PHP 7.4 mínimo (PHP 8.1+ recomendado). El plugin declara explícitamente la compatibilidad con HPOS y Cart/Checkout Blocks — no aparece ninguna advertencia en WooCommerce Status. Al activarse, se crean automáticamente dos tablas SQL: `{prefix}dfcarbon_factors` (factores de emisión) y `{prefix}dfcarbon_log` (registro de compensaciones). La base ADEME se pre-carga inmediatamente con unos 25 factores. ## Configuración inicial El plugin funciona **zero-config** desde su activación: los factores ADEME están cargados, la insignia se muestra en todas las fichas de producto, la compensación aparece en el checkout. Pero unos ajustes iniciales te darán cifras mucho más precisas. ### Ajustes generales Ve a **Carbon Footprint → Ajustes**. Cuatro bloques de parámetros: - **API Climatiq** — opcional. Deja vacío para funcionar 100% en local con los factores ADEME. - **Compensación** — activación del bloque en checkout, precio por tonelada (por defecto 25 €/t, mercado típico 15–30 €/t), partner mostrado (Gold Standard por defecto), descripción para el cliente. - **Transporte** — activación del componente de transporte, distancia media en km (por defecto 500 km), factor de emisión del transporte (por defecto: transporte por carretera). - **Visualización** — posición de la insignia en la ficha (5 hooks disponibles), estilo (tarjeta, píldora, mínimo), color, prioridad del hook. ### Mapeo categorías → factores Es el paso más impactante. Ve a **Carbon Footprint → Mapeo**. Para cada categoría de productos WooCommerce, selecciona el factor de emisión más relevante entre los de la base ADEME. Sin mapeo, todos tus productos usan el factor `general` (4,50 kgCO₂e/kg), lo cual es muy aproximado. Un mapeo cuidado te lleva de _«orden de magnitud»_ a _«estimación creíble para reporting»_. ### Activación de la API Climatiq (opcional) Climatiq es una base de más de 80 000 factores de emisión, más fina que la Base Empreinte ADEME en ciertos sectores (electrónica detallada, cosmética por componente, alimentación por cadena de suministro). Si tienes una clave: 1. Crea una cuenta en `climatiq.io` (nivel gratuito disponible para uso moderado). 2. Pega la clave API en **Carbon Footprint → Ajustes → API Climatiq**. 3. Haz clic en **Probar conexión** para validar. Una vez activada, la API Climatiq se usa con prioridad 2 (tras un posible valor manual de producto) y por delante del mapeo ADEME. Cada resultado se cachea una semana — sin sobrecoste al renderizar páginas. ## Cómo funciona el cálculo de huella ### Prioridades del cálculo Para cada producto, el plugin determina la huella según cuatro fuentes, en este orden estricto de prioridad: 1. **Valor manual del producto** — si has introducido un valor en la pestaña «Carbon» de la ficha (meta `_dfcarbon_kgco2e`), es ese el que se usa. Cortocircuita todas las demás fuentes. 2. **API Climatiq** — si hay una clave configurada y el producto tiene peso o categoría consultable. 3. **Factor ADEME vía mapeo** — el factor asignado a la categoría del producto, aplicado al peso. 4. **Fallback general** — el factor `general` (4,50 kgCO₂e/kg) aplicado al peso, o un valor fijo si no hay peso. El cálculo se cachea vía la API de objeto de WordPress (grupo `dfcarbon_product`) y se invalida automáticamente en cada modificación de producto o mapeo. ### Componente de transporte Si está activado, el componente de transporte se añade a la huella material: ``` huella_total = huella_material + (peso_kg × distancia_km × factor_transporte_tkm) ``` El factor de transporte por carretera por defecto es 0,105 kgCO₂e por tonelada-kilómetro (fuente ADEME, camión pesado medio). Puedes cambiarlo en los ajustes, o cambiar a otro factor (marítimo, aéreo, etc.) si lo añades a la base. El componente de transporte solo cubre el **transporte descendente** (del almacén al cliente). La huella material del factor ADEME ya incluye la producción y el transporte ascendente. ## Factores de emisión ADEME incluidos El plugin viene con unos 25 factores pre-cargados de la **Base Empreinte ADEME** (Francia). Principales sectores cubiertos: - **Textil** — prenda estándar, algodón, lana, sintético, calzado - **Electrónica** — smartphone, portátil, pequeño electrodoméstico, gran electrodoméstico - **Alimentación** — vacuno, cerdo, ave, pescado, lácteos, ultramarinos - **Cosmética** — cuidado corporal, maquillaje, perfumería - **Hogar** — mobiliario madera, mobiliario metal, textil del hogar - **Papel** — libro, revista, embalaje de cartón - **Deporte** — equipamiento deportivo, ropa deportiva - **Joyería** — bisutería, plata, oro - **Transporte** — transporte por carretera, transporte marítimo - **Fallback** — `general` (4,50 kgCO₂e/kg) Puedes consultar, editar, eliminar o añadir tus propios factores desde **Carbon Footprint → Factores**. Cada factor tiene: un slug único, una etiqueta, un valor en kgCO₂e/unidad, una unidad (kg por defecto), una fuente (ADEME, Climatiq, personalizado…) y un año. Un botón **Recargar los valores ADEME por defecto** permite restaurar la base original _sin sobrescribir tus añadidos personales_: solo los slugs ADEME faltantes se reinsertan. ## La insignia de producto ### Estilos disponibles Tres representaciones para elegir (en **Ajustes → Visualización → Estilo de la insignia**): - **Tarjeta (detallada)** — bloque completo con la huella, la fuente, dos equivalencias pedagógicas (km en coche, años de árbol) y el precio de compensación. - **Píldora en línea** — insignia compacta «🌱 5,2 kg CO₂e» junto al precio. - **Texto mínimo** — solo el valor, sin recuadro. ### Posiciones La insignia se engancha a uno de los hooks WooCommerce estándar: - `after_price` — justo después del precio (por defecto) - `before_add_to_cart` — antes del botón «añadir al carrito» - `after_add_to_cart` — después del botón «añadir al carrito» - `before_meta` — antes de los metadatos del producto - `after_summary` — después del resumen completo del producto Si ninguna posición encaja con tu tema, puedes usar el shortcode `[dfcarbon_badge]` directamente en una plantilla o en un maquetador (Elementor, Divi, Gutenberg…). ### Ocultar en ciertos productos En la pestaña **Carbon** de cada ficha de producto, marca _«Ocultar la insignia»_. El cálculo de huella permanece activo (útil para los informes y el checkout), pero la visualización pública desaparece. Práctico para productos digitales, tarjetas regalo o servicios. ## Compensación en el checkout En el checkout, el plugin inserta un bloque entre el resumen del pedido y el método de pago. Este bloque contiene: - La huella estimada del carrito (suma de las huellas de todos los artículos × sus cantidades) - El coste de compensación correspondiente (huella × precio por tonelada) - Una casilla opcional «Sí, añado X € para compensar el impacto de mi pedido» - Un texto descriptivo configurable mencionando al partner (Gold Standard, Verra…) Cuando el cliente marca la casilla, se añade una **fee dinámica de WooCommerce** al total vía el hook `woocommerce_cart_calculate_fees`. El estado se guarda en la sesión de WooCommerce (`dfcarbon_offset_active`), luego se persiste en el pedido vía los metas `_dfcarbon_cart_kgco2e`, `_dfcarbon_offset_active`, `_dfcarbon_offset_amount` y `_dfcarbon_offset_provider`. **Importante:** el plugin **recauda** la compensación de tus clientes — **no compra** automáticamente los créditos de carbono por ti. Es un diseño deliberado, para dejarte el control sobre el momento, el canal y el partner (Gold Standard, Verra, Ecologi, MyClimate…). El panel te indica el total a liquidar en cada ciclo de pago con tu partner. ## Panel e informes El menú **Carbon Footprint → Panel** muestra los indicadores globales: - Número total de pedidos compensados - Huella CO₂ acumulada medida en pedidos - Huella CO₂ efectivamente compensada - Importe total invertido en compensación El menú **Carbon Footprint → Informes** detalla cada pedido compensado: fecha, número de pedido, huella del pedido, kg compensados, importe, partner. Esta tabla alimenta directamente tu reporting extra-financiero CSRD o cualquier solicitud de auditoría ESG. También se conserva un snapshot de huella por línea de pedido (meta `_dfcarbon_line_kgco2e`): los valores mostrados no cambian retrospectivamente cuando modificas un factor ADEME más tarde. ## Shortcodes disponibles Tres shortcodes públicos para integrar los elementos donde quieras en tu sitio: ``` [dfcarbon_badge id="123" style="card"] ``` Muestra la insignia de carbono de un producto específico. `id` es obligatorio, `style` opcional (`card` por defecto, `pill`, `minimal`). ``` [dfcarbon_cart_summary] ``` Muestra la huella del carrito actual y el coste de compensación. Útil en una página «Mi carrito» personalizada o en una side-cart. ``` [dfcarbon_stats] ``` Bloque público con las estadísticas agregadas: toneladas compensadas, número de pedidos, importe invertido. Perfecto para una página «Nuestro compromiso climático». ## Hooks y filtros para desarrolladores El plugin expone un filtro principal para sobrescribir por completo el cálculo de huella: ``` add_filter( 'dfcarbon_product_footprint', function( $footprint, $product_id, $context ) { // $footprint es un array: ['kg' => 5.2, 'source' => 'ademe', 'breakdown' => [...]] // Devuelve un array modificado para sobrescribir return $footprint; }, 10, 3 ); ``` Otros hooks útiles: - `dfcarbon_daily_sync` — acción WP-Cron diaria (purga de los transients Climatiq) - `dfcarbon_before_offset_fee` — acción antes de añadir la fee de compensación - `dfcarbon_offset_purchased` — acción disparada al persistir en el pedido El plugin usa el namespace PHP `DataFirefly\CarbonOffset`. Para añadir un factor programáticamente desde un mu-plugin o un tema hijo, importa la clase `Database`: ``` use DataFirefly\CarbonOffset\Database; Database::upsert_factor( [ 'slug' => 'mi-factor', 'label' => 'Mi sector específico', 'value' => 2.35, 'unit' => 'kg', 'source' => 'Personalizado', 'year' => 2026, ] ); ``` ## Multilingüe (Polylang / WPML) El plugin es compatible con Polylang Pro y WPML. Los 5 idiomas suministrados (FR, EN, ES, DE, IT) están en la carpeta `languages/` con los archivos `.po` y `.mo` ya compilados. Para ajustar una traducción: 1. Instala Loco Translate (plugin gratuito) o usa Poedit en local. 2. Abre el catálogo `df-carbon-offset-es_ES.po`. 3. Edita las entradas. 4. Recompila a `.mo` — automático en Loco Translate. Para añadir un idioma no suministrado (portugués, neerlandés…), duplica un `.po` existente, renómbralo al locale correcto (`df-carbon-offset-pt_PT.po`, `df-carbon-offset-nl_NL.po`…), traduce y compila. ## Desinstalación El plugin limpia bien al desinstalarse vía `uninstall.php`: - Elimina las tablas `dfcarbon_factors` y `dfcarbon_log` - Elimina las opciones `dfcarbon_settings` y `dfcarbon_db_version` - Elimina los postmeta `_dfcarbon_*` de todos los productos y pedidos - Desinscribe el cron `dfcarbon_daily_sync` - Purga los transients Climatiq La desinstalación es **destructiva**: el registro pasado de compensaciones se elimina. Si necesitas conservarlo para una auditoría CSRD, exporta la tabla `Informes` antes de desinstalar. ## FAQ ### ¿Puedo forzar un factor específico en un producto sin cambiar su categoría? Sí. En la pestaña Carbon de la ficha, selecciona un factor en el menú desplegable «Factor de emisión». Predomina sobre el mapeo de categoría solo para ese producto. ### ¿Qué pasa si mi producto no tiene peso? El cálculo usa un valor fijo para productos sin peso (tratados como «unidad»). También puedes usar el valor manual para introducir directamente el valor en kg CO₂e. ### ¿El plugin funciona con productos variables? Sí. La huella se calcula a nivel del producto padre (vía su peso y categoría), lo cual es coherente para la mayoría de los casos. Para un control por variación, usa el filtro `dfcarbon_product_footprint`. ### ¿Cómo gestiono productos descargables (digitales)? Para un producto puramente digital (ebook, curso online, licencia de software), marca «Ocultar la insignia» y deja el cálculo caer sobre el fallback general (el impacto será mínimo si el producto no tiene peso). Alternativa: usa el valor manual con un valor pequeño (típicamente 0,01 a 0,1 kg CO₂e para un ebook). ### ¿Puedo excluir un producto de la compensación en checkout? La compensación se aplica al carrito globalmente, no producto por producto. Para excluir totalmente un producto del cálculo, usa el filtro `dfcarbon_product_footprint` devolviendo un array con `['kg' => 0]`. ### ¿El plugin hace llamadas API en cada vista de página? No. Cada huella de producto se cachea vía la API de objeto de WordPress. Las llamadas Climatiq (si están activas) están a su vez cacheadas en transient durante una semana. Una página de producto no dispara ninguna llamada externa. ### ¿Es compatible con cachés (WP Rocket, Litespeed, W3TC)? Sí, totalmente. El renderizado de la insignia es del lado servidor. La parte dinámica (casilla de compensación en checkout) se gestiona por AJAX y no afecta a la caché de la ficha de producto.