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.

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.

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.

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.

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.

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

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.