DataFirefly Digital Product Passport — Documentación

Introducción

El plugin DataFirefly Digital Product Passport añade a WooCommerce todo lo necesario para generar un Pasaporte Digital de Producto (DPP) conforme con el Reglamento europeo Ecodiseño para Productos Sostenibles (ESPR). Este pasaporte se vuelve progresivamente obligatorio en la Unión Europea a partir de 2027, empezando por el textil, las baterías y la electrónica de consumo, antes de extenderse a la práctica totalidad de los productos comercializados en el mercado europeo.

Concretamente, cada producto WooCommerce obtiene un identificador único estable (UUID v4), un código QR nativo, una URL pública limpia tipo /dpp/{uuid}, un registro completo de componentes y materiales, una línea de tiempo de trazabilidad y una API REST pública. Ninguna llamada externa: todo se genera en servidor.

Requisitos

• WordPress 6.0 o superior
• WooCommerce 7.0 o superior, activado
• PHP 7.4 mínimo (probado hasta PHP 8.3)
• Un permalink distinto de «Simple» (Ajustes → Enlaces permanentes)

Instalación

1. Descarga el ZIP dfdpp-1.0.0.zip desde tu cuenta DataFirefly.
2. Ve a Plugins → Añadir nuevo → Subir plugin, selecciona el ZIP y pulsa Instalar ahora.
3. Pulsa Activar. Las 5 tablas personalizadas se crean automáticamente (wp_dfdpp_passports, wp_dfdpp_components, wp_dfdpp_materials, wp_dfdpp_suppliers, wp_dfdpp_events) y las opciones por defecto quedan configuradas.
4. Si la URL pública /dpp/{uuid} no responde de inmediato, ve a Ajustes → Enlaces permanentes y pulsa Guardar cambios (sin cambiar nada) para forzar el flush.

Configuración global

Ve a WooCommerce → Pasaporte DPP. Esta pantalla agrupa todos los ajustes del plugin.

URL pública y código QR

• Prefijo de URL: por defecto dpp, lo que da tudominio.com/dpp/{uuid}. Cámbialo si prefieres pasaporte, product-passport u otro. Recuerda visitar Ajustes → Enlaces permanentes tras el cambio.
• Tamaño del QR: factor de zoom de 1 a 10. El valor 6 (por defecto) produce unos 240 px de lado.
• Margen: número de módulos blancos alrededor del QR (4 por defecto).
• Corrección de errores: L / M / Q / H. Deja H si el QR se imprimirá en etiqueta: hasta un 30% del código puede dañarse sin comprometer la lectura.
• Formato preferido: PNG (raster, universal) o SVG (vectorial, mejor para impresión en gran formato).

Identidad del fabricante por defecto

Rellena aquí la información que no quieres reescribir producto por producto:

• Razón social, dirección, país de fabricación
• País por defecto aplicado a componentes y materiales
• Categoría ESPR por defecto (textil, batería, electrónica, mobiliario, etc.)

Visualización pública

Cinco interruptores independientes controlan lo que ven tus clientes en la página pública del pasaporte:

• Huella de carbono (activada por defecto)
• Proveedores (desactivada por defecto — datos sensibles)
• Composición material (activada)
• Reparabilidad y piezas de recambio (activada)
• Línea de tiempo de trazabilidad (activada)

Publicación automática

Si marcas esta opción, cada pasaporte pasa automáticamente a publicado cuando el producto WooCommerce se publica. Útil para un catálogo de cientos de productos gestionado por un equipo no técnico. En caso contrario, cada pasaporte debe publicarse manualmente — lo que garantiza un control final.

Branding

• Color de acento: formato hexadecimal (ej. #0f172a). Se aplica al hero, títulos y botones de la página pública.
• URL del logo: mostrado en la parte superior de la página pública. Usa una imagen transparente (PNG o SVG) — se invertirá sobre el fondo oscuro.

Crear un pasaporte para un producto

Abre cualquier producto en WooCommerce. Una nueva pestaña Pasaporte DPP aparece en el panel de datos del producto (junto a General, Inventario, Envío, etc.). Agrupa 8 secciones.

Pestaña Identificación

El punto de entrada obligatorio para publicar:

• Estado: Borrador / Publicado / Archivado. Solo Publicado hace accesible la URL pública.
• Categoría ESPR: determina la estructura de datos que los auditores europeos esperan encontrar. Elige textile, battery, electronics, furniture, iron_steel, aluminium, tyres, detergents, paints, lubricants, chemicals, cosmetics, toys, construction o general.
• GTIN / EAN / UPC: código de barras comercial internacional.
• Referencia de modelo, Número de lote, Número de serie: rellena los campos aplicables a tu producto.
• Fabricante: nombre, dirección, país (pre-rellenados desde los ajustes globales si los configuraste).
• Fecha de fabricación y Sitio de fabricación (ciudad, fábrica o taller).

Pestaña Sostenibilidad y huella

• Huella de carbono: valor numérico, unidad (kgCO2e por defecto) y metodología de cálculo de referencia (PEF, ISO 14067, GHG Protocol). Solo rellenes la huella si puedes justificarla con una metodología documentada — es el punto más escrutinizado en auditorías.
• Índice de reparabilidad: nota sobre 10.
• Duración de vida prevista en años.
• Duración de garantía en meses (obligación de al menos 24 meses en UE para bienes de consumo).
• Disponibilidad de piezas de recambio en años.
• Contenido reciclado en porcentaje.
• Contenido reciclable en porcentaje.

Pestaña Instrucciones

Cuatro campos ricos que aceptan HTML básico (párrafos, listas, enlaces):

• Uso: consejos para aprovechar al máximo el producto y alargar su vida útil.
• Cuidado: lavado, secado, almacenamiento.
• Reciclado: cadena de reciclado, clasificación selectiva, puntos de recogida.
• Fin de vida: qué hacer cuando el producto ya no es utilizable.

Pestaña Conformidad

• Sustancias preocupantes (SCIP / REACH): lista de sustancias de la lista candidata REACH presentes en más de 0,1% en peso. Formato libre; recomendamos una lista con nombre y número CAS.
• Materiales peligrosos: mención de clases de peligro aplicables (CLP, GHS).
• Certificaciones y etiquetas: OEKO-TEX, GOTS, GRS, Ecolabel, EPEAT, etc.

Pestaña Componentes

Registro plano de los componentes que constituyen el producto. Para cada componente añades:

• Nombre (obligatorio)
• Tipo: de una lista predefinida (tejido principal, forro, suela, hebilla, cremallera, etc.)
• Peso en gramos
• Nombre del proveedor (nunca expuesto públicamente salvo que actives el interruptor dedicado)
• País de origen en 3 caracteres ISO 3166 alpha-3 (ej. FRA, ITA, CHN)
• Reciclable: sí / no
• Reemplazable: sí / no (pertinente para electrónica, mobiliario)

Pestaña Materiales

Registro material más granular con códigos normalizados:

• Código material: desplegable con los principales códigos ISO 11469 / ISO 1043 para plásticos (PET, PP, PE, PVC, PS, PA, etc.), ISO 1833 para textiles (WO lana, CO algodón, PL poliéster, VI viscosa, EL elastano, etc.), DIN 6120 para metales, y químicas de baterías (Li-ion, LFP, NMC, NCA, NiMH, Pb).
• Nombre personalizado: si el código predefinido no se ajusta.
• Porcentaje: parte de este material en el producto (hasta 4 decimales).
• Reciclado + % reciclado: si es contenido reciclado, y en qué proporción.
• Renovable: material de origen biológico renovable.
• N° CAS: identificador CAS de la sustancia (para sustancias químicas reguladas).

Pestaña Trazabilidad

Línea de tiempo de los eventos clave del ciclo de vida. Cada evento asocia una fecha, tipo, actor, lugar y descripción. Los tipos disponibles cubren todo el ciclo:

• Producción
• Control de calidad
• Transporte
• Importación / Exportación
• Distribución
• Venta
• Reparación
• Reacondicionamiento
• Reciclado
• Fin de vida

Pestaña Código QR

Esta pestaña se activa en cuanto el producto se guarda por primera vez. Muestra:

• El código QR generado (vista previa en data-URI)
• El UUID del pasaporte
• La URL pública clicable
• Tres botones de descarga: PNG, SVG y JSON crudo

Publicar un pasaporte

Un pasaporte en estado Borrador no es accesible públicamente — la URL devuelve un 404. Para publicarlo:

1. Abre el producto, ve a la pestaña Pasaporte DPP → Identificación.
2. Pasa Estado a Publicado.
3. Pulsa Actualizar arriba a la derecha del producto.

La fecha de primera publicación se memoriza automáticamente en published_at. Un pasaporte publicado puede volver a Borrador o pasar a Archivado en cualquier momento.

Página pública del pasaporte

La URL del tipo tudominio.com/dpp/8f3a2c1d-4b5e-6f7a-8b9c-0d1e2f3a4b5c abre una página responsive con:

• Un hero con el nombre del producto, la categoría ESPR, el logo de marca y la imagen del producto
• Un banner de identificadores (UUID, GTIN, modelo, lote, serie, SKU)
• Una tarjeta fabricante con dirección y fecha de producción
• Una tarjeta sostenibilidad y huella con las métricas en forma de tarjetas
• Las tablas componentes y materiales (según los interruptores de visualización)
• Las instrucciones (uso, cuidado, reciclado, fin de vida)
• La conformidad regulatoria (certificaciones, sustancias, materiales peligrosos)
• Una línea de tiempo de trazabilidad vertical con fechas y lugares
• Una sidebar del código QR con descarga PNG / SVG / JSON
• Un bloque JSON-LD schema.org Product automáticamente inyectado para SEO e interoperabilidad

En la página pública del producto WooCommerce, un bloque discreto invita a los visitantes a consultar el pasaporte, con un QR en miniatura. Este bloque se añade automáticamente debajo del resumen del producto (hook woocommerce_after_single_product_summary, prioridad 25).

Formatos alternativos

La misma URL acepta dos sufijos:

• /dpp/{uuid}?dfdpp_format=json o /dpp/{uuid}.json: devuelve el payload JSON completo, incluyendo el bloque JSON-LD.
• /dpp/{uuid}?dfdpp_format=qr o /dpp/{uuid}/qr: descarga directamente el código QR en PNG.

API REST

Todos los endpoints están expuestos bajo el namespace dfdpp/v1.

Endpoints públicos

• GET /wp-json/dfdpp/v1/passport/{uuid} — devuelve el payload JSON completo del pasaporte.
• GET /wp-json/dfdpp/v1/passport/by-product/{product_id} — lo mismo pero buscado por identificador de producto WooCommerce.
• GET /wp-json/dfdpp/v1/passport/{uuid}/qr — devuelve el código QR en SVG vectorial.

Estos endpoints solo devuelven pasaportes en estado Publicado.

Endpoints autenticados

Requieren autenticación Application Password u OAuth y una capability manage_woocommerce o edit_products:

• PATCH /wp-json/dfdpp/v1/passport/{product_id} — actualiza parcialmente los campos de un pasaporte.
• POST /wp-json/dfdpp/v1/passport/{product_id}/publish — publica el pasaporte (atajo sin pasar por la administración).

Personalización

Sobrescribir la página pública

Copia public/templates/dpp-public.php desde el plugin a una carpeta dfdpp/ en la raíz de tu tema activo. El plugin usará este archivo prioritariamente, lo que te permite rehacer completamente la representación sin tocar el plugin. La lógica de recuperación de datos permanece inalterada: dispones de las variables $passport y $data exactamente como en la plantilla original.

Filtro del payload JSON

El filtro dfdpp_passport_payload te permite añadir o modificar campos en el payload JSON expuesto. Ejemplo: añadir un campo propietario internal_reference visible solo para tu ERP.

add_filter( 'dfdpp_passport_payload', function ( $data, $passport ) {
    $data['custom'] = array(
        'internal_reference' => get_post_meta( $passport->product_id, '_erp_ref', true ),
    );
    return $data;
}, 10, 2 );

Bloque en la página del producto

El bloque que invita a consultar el pasaporte en la página pública del producto WooCommerce puede moverse, desactivarse o reemplazarse manipulando el hook:

// Eliminarlo completamente
remove_action( 'woocommerce_after_single_product_summary', array( dfdpp()->frontend, 'render_product_dpp_link' ), 25 );

// Colocarlo en otro sitio, ej. encima del botón Añadir al carrito
add_action( 'woocommerce_single_product_summary', array( dfdpp()->frontend, 'render_product_dpp_link' ), 25 );

Traducciones

El plugin se entrega con una traducción francesa completa (languages/dfdpp-fr_FR.po y .mo) y un archivo plantilla dfdpp.pot (291 cadenas únicas) para traducir a otros idiomas con Poedit o cualquier herramienta compatible con gettext.

Polylang Pro y WPML están soportados para la traducción de contenidos de producto (nombre, descripción, categoría ESPR). El pasaporte permanece vinculado al producto fuente, lo que garantiza una única fuente de verdad para los datos de conformidad permitiendo una visualización multilingue de la página pública.

Compatibilidad HPOS

El plugin declara explícitamente su compatibilidad con el almacenamiento de alto rendimiento de pedidos WooCommerce (High-Performance Order Storage). No almacena ningún dato en el custom post type shop_order — las 5 tablas dedicadas son independientes. Puedes activar HPOS sin temor a romper el plugin.

FAQ y solución de problemas

La URL pública devuelve un 404

Tres causas posibles:

• El pasaporte está en estado Borrador o Archivado — pásalo a Publicado.
• Las rewrite rules no se han flusheado — ve a Ajustes → Enlaces permanentes y guarda (sin cambiar nada).
• Un permalink «Simple» está activo — pasa a «Nombre de la entrada» o cualquier otro formato no simple.

El código QR no se muestra

Verifica que tu hosting permite la escritura del directorio wp-content/uploads/ y que la extensión GD está activada en PHP (necesaria para la generación PNG). Si estás en un entorno restringido, fuerza el formato SVG en los ajustes: no depende de GD.

¿Cómo proporcionar la trazabilidad a un socio externo?

Usa la API REST. Crea un Application Password dedicado al socio en su cuenta de usuario WordPress (Usuarios → Perfil → Application Passwords), luego proporciónale la documentación de un endpoint PATCH para que empuje sus propios eventos de trazabilidad con el tiempo.

¿Puedo generar los códigos QR en masa?

Sí, vía WP-CLI. Un script personalizado puede iterar sobre los productos y llamar a DFDPP_QRCode::output_png() o ::as_svg() para generar los archivos. Contacta al soporte si quieres un comando WP-CLI llave en mano para tu catálogo.

¿Funciona con productos variables?

Sí, el pasaporte está vinculado al producto padre. Si necesitas un pasaporte distinto por variación (típico en electrónica donde cada configuración tiene una huella de carbono diferente), contáctanos para discutir una extensión.

Desinstalación

La desactivación simple del plugin conserva todos los datos. Tus pasaportes permanecen en base, listos para ser reactivados.

La desinstalación completa (botón Eliminar en la página de plugins) dispara uninstall.php, que:

• Elimina las 5 tablas personalizadas
• Elimina todas las opciones dfdpp_*
• Limpia los transients eventuales
• Flushea las rewrite rules

Soporte

El soporte técnico se presta por correo en francés e inglés. Escribe a support@datafirefly.com especificando la versión del plugin, la versión de WordPress y WooCommerce, así como un extracto de los logs si tienes un mensaje de error PHP.