DataFirefly Digital Product Passport — Documentazione

Introduzione

Il plugin DataFirefly Digital Product Passport aggiunge a WooCommerce tutto il necessario per generare un Passaporto Digitale di Prodotto (DPP) conforme al Regolamento europeo Ecodesign per Prodotti Sostenibili (ESPR). Questo passaporto diventa progressivamente obbligatorio nell’Unione Europea a partire dal 2027, iniziando dal tessile, le batterie e l’elettronica di consumo, prima di estendersi alla quasi totalità dei prodotti immessi sul mercato europeo.

Concretamente, ogni prodotto WooCommerce ottiene un identificativo unico stabile (UUID v4), un QR code nativo, una URL pubblica pulita tipo /dpp/{uuid}, un registro completo di componenti e materiali, una timeline di tracciabilità e un’API REST pubblica. Nessuna chiamata esterna: tutto è generato lato server.

Requisiti

• WordPress 6.0 o superiore
• WooCommerce 7.0 o superiore, attivato
• PHP 7.4 minimo (testato fino a PHP 8.3)
• Un permalink diverso da “Semplice” (Impostazioni → Permalink)

Installazione

1. Scarica lo ZIP dfdpp-1.0.0.zip dal tuo account DataFirefly.
2. Vai su Plugin → Aggiungi nuovo → Carica plugin, seleziona lo ZIP e premi Installa ora.
3. Premi Attiva. Le 5 tabelle personalizzate vengono create automaticamente (wp_dfdpp_passports, wp_dfdpp_components, wp_dfdpp_materials, wp_dfdpp_suppliers, wp_dfdpp_events) e le opzioni di default vengono impostate.
4. Se l’URL pubblica /dpp/{uuid} non risponde immediatamente, vai su Impostazioni → Permalink e premi Salva modifiche (senza cambiare nulla) per forzare il flush.

Configurazione globale

Vai su WooCommerce → Passaporto DPP. Questa schermata raggruppa tutte le impostazioni del plugin.

URL pubblica e QR Code

• Prefisso URL: predefinito dpp, che dà tuodominio.com/dpp/{uuid}. Cambialo se preferisci passaporto, product-passport o altro. Ricorda di visitare Impostazioni → Permalink dopo la modifica.
• Dimensione QR: fattore di zoom da 1 a 10. Il valore 6 (predefinito) produce circa 240 px per lato.
• Margine: numero di moduli bianchi attorno al QR (4 predefinito).
• Correzione errori: L / M / Q / H. Resta su H se il QR sarà stampato su etichetta: fino al 30% del codice può danneggiarsi senza compromettere la lettura.
• Formato preferito: PNG (raster, universale) o SVG (vettoriale, migliore per stampa a grande formato).

Identità fabbricante di default

Compila qui le informazioni che non vuoi riscrivere prodotto per prodotto:

• Ragione sociale, indirizzo, paese di fabbricazione
• Paese di default applicato a componenti e materiali
• Categoria ESPR di default (tessile, batteria, elettronica, mobili, ecc.)

Visualizzazione pubblica

Cinque interruttori indipendenti controllano ciò che i tuoi clienti vedono sulla pagina pubblica del passaporto:

• Impronta di carbonio (attivata di default)
• Fornitori (disattivata di default — dati sensibili)
• Composizione materica (attivata)
• Riparabilità e pezzi di ricambio (attivata)
• Timeline di tracciabilità (attivata)

Pubblicazione automatica

Se spunti questa opzione, ogni passaporto passa automaticamente a pubblicato quando il prodotto WooCommerce stesso è pubblicato. Utile per un catalogo di centinaia di prodotti gestito da un team non tecnico. Altrimenti, ogni passaporto deve essere pubblicato manualmente — il che garantisce un controllo finale.

Branding

• Colore di accento: formato esadecimale (es. #0f172a). Si applica all’hero, titoli e pulsanti della pagina pubblica.
• URL del logo: mostrato in alto sulla pagina pubblica. Usa un’immagine trasparente (PNG o SVG) — sarà invertita sullo sfondo scuro.

Creare un passaporto per un prodotto

Apri qualsiasi prodotto in WooCommerce. Una nuova scheda Passaporto DPP appare nel pannello dati prodotto (accanto a Generale, Inventario, Spedizione, ecc.). Raggruppa 8 sezioni.

Scheda Identificazione

Il punto d’ingresso obbligatorio per pubblicare:

• Stato: Bozza / Pubblicato / Archiviato. Solo Pubblicato rende accessibile l’URL pubblica.
• Categoria ESPR: determina la struttura dati che gli auditor europei si aspettano di trovare. Scegli textile, battery, electronics, furniture, iron_steel, aluminium, tyres, detergents, paints, lubricants, chemicals, cosmetics, toys, construction o general.
• GTIN / EAN / UPC: codice a barre commerciale internazionale.
• Riferimento modello, Numero di lotto, Numero di serie: compila i campi applicabili al tuo prodotto.
• Fabbricante: nome, indirizzo, paese (pre-compilati dalle impostazioni globali se configurate).
• Data di fabbricazione e Sito di fabbricazione (città, fabbrica o laboratorio).

Scheda Sostenibilità e impronta

• Impronta di carbonio: valore numerico, unità (kgCO2e di default) e metodologia di calcolo di riferimento (PEF, ISO 14067, GHG Protocol). Compila l’impronta solo se puoi giustificarla con una metodologia documentata — è il punto più scrutinato negli audit.
• Indice di riparabilità: voto su 10.
• Durata di vita prevista in anni.
• Durata garanzia in mesi (obbligo di almeno 24 mesi in UE per beni di consumo).
• Disponibilità pezzi di ricambio in anni.
• Contenuto riciclato in percentuale.
• Contenuto riciclabile in percentuale.

Scheda Istruzioni

Quattro campi ricchi che accettano HTML di base (paragrafi, liste, link):

• Uso: consigli per sfruttare al meglio il prodotto e allungarne la vita utile.
• Cura: lavaggio, asciugatura, conservazione.
• Riciclaggio: filiera di riciclaggio, raccolta differenziata, punti di raccolta.
• Fine vita: cosa fare quando il prodotto non è più utilizzabile.

Scheda Conformità

• Sostanze preoccupanti (SCIP / REACH): elenco delle sostanze della lista candidata REACH presenti oltre lo 0,1% in peso. Formato libero; raccomandiamo un elenco puntato con nome e numero CAS.
• Materiali pericolosi: menzione delle classi di pericolo applicabili (CLP, GHS).
• Certificazioni ed etichette: OEKO-TEX, GOTS, GRS, Ecolabel, EPEAT, ecc.

Scheda Componenti

Registro piatto dei componenti che costituiscono il prodotto. Per ogni componente aggiungi:

• Nome (obbligatorio)
• Tipo: da una lista predefinita (tessuto principale, fodera, suola, fibbia, cerniera, ecc.)
• Peso in grammi
• Nome del fornitore (mai esposto pubblicamente salvo che tu attivi l’interruttore dedicato)
• Paese di origine su 3 caratteri ISO 3166 alpha-3 (es. FRA, ITA, CHN)
• Riciclabile: sì / no
• Sostituibile: sì / no (pertinente per elettronica, mobili)

Scheda Materiali

Registro materico più granulare con codici standardizzati:

• Codice materiale: elenco a tendina con i principali codici ISO 11469 / ISO 1043 per le plastiche (PET, PP, PE, PVC, PS, PA, ecc.), ISO 1833 per i tessili (WO lana, CO cotone, PL poliestere, VI viscosa, EL elastan, ecc.), DIN 6120 per i metalli, e chimiche batterie (Li-ion, LFP, NMC, NCA, NiMH, Pb).
• Nome personalizzato: se il codice predefinito non si adatta.
• Percentuale: quota di questo materiale nel prodotto (fino a 4 decimali).
• Riciclato + % riciclato: se è contenuto riciclato, e in quale proporzione.
• Rinnovabile: materiale di origine biologica rinnovabile.
• N° CAS: identificativo CAS della sostanza (per sostanze chimiche regolamentate).

Scheda Tracciabilità

Timeline degli eventi chiave del ciclo di vita. Ogni evento associa data, tipo, attore, luogo e descrizione. I tipi disponibili coprono l’intero ciclo:

• Produzione
• Controllo qualità
• Trasporto
• Importazione / Esportazione
• Distribuzione
• Vendita
• Riparazione
• Ricondizionamento
• Riciclaggio
• Fine vita

Scheda QR Code

Questa scheda diventa attiva appena il prodotto viene salvato per la prima volta. Mostra:

• Il QR code generato (anteprima in data-URI)
• L’UUID del passaporto
• L’URL pubblica cliccabile
• Tre pulsanti di download: PNG, SVG e JSON grezzo

Pubblicare un passaporto

Un passaporto in stato Bozza non è accessibile pubblicamente — l’URL restituisce un 404. Per pubblicarlo:

1. Apri il prodotto, vai alla scheda Passaporto DPP → Identificazione.
2. Passa Stato a Pubblicato.
3. Premi Aggiorna in alto a destra del prodotto.

La data di prima pubblicazione viene memorizzata automaticamente in published_at. Un passaporto pubblicato può essere rimesso in Bozza o passato ad Archiviato in qualsiasi momento.

Pagina pubblica del passaporto

L’URL del tipo tuodominio.com/dpp/8f3a2c1d-4b5e-6f7a-8b9c-0d1e2f3a4b5c apre una pagina responsive con:

• Un hero con il nome del prodotto, la categoria ESPR, il logo del marchio e l’immagine del prodotto
• Un banner identificativi (UUID, GTIN, modello, lotto, serie, SKU)
• Una card fabbricante con indirizzo e data di produzione
• Una card sostenibilità e impronta con le metriche in forma di tessere
• Le tabelle componenti e materiali (secondo gli interruttori di visualizzazione)
• Le istruzioni (uso, cura, riciclaggio, fine vita)
• La conformità normativa (certificazioni, sostanze, materiali pericolosi)
• Una timeline di tracciabilità verticale con date e luoghi
• Una sidebar QR code con download PNG / SVG / JSON
• Un blocco JSON-LD schema.org Product iniettato automaticamente per SEO e interoperabilità

Sulla pagina pubblica del prodotto WooCommerce, un blocco discreto invita i visitatori a consultare il passaporto, con un QR miniatura. Questo blocco viene aggiunto automaticamente sotto il riassunto del prodotto (hook woocommerce_after_single_product_summary, priorità 25).

Formati alternativi

La stessa URL accetta due suffissi:

• /dpp/{uuid}?dfdpp_format=json o /dpp/{uuid}.json: restituisce il payload JSON completo, compreso il blocco JSON-LD.
• /dpp/{uuid}?dfdpp_format=qr o /dpp/{uuid}/qr: scarica direttamente il QR code PNG.

API REST

Tutti gli endpoint sono esposti sotto il namespace dfdpp/v1.

Endpoint pubblici

• GET /wp-json/dfdpp/v1/passport/{uuid} — restituisce il payload JSON completo del passaporto.
• GET /wp-json/dfdpp/v1/passport/by-product/{product_id} — lo stesso ma cercato per identificativo prodotto WooCommerce.
• GET /wp-json/dfdpp/v1/passport/{uuid}/qr — restituisce il QR code in SVG vettoriale.

Questi endpoint restituiscono solo passaporti in stato Pubblicato.

Endpoint autenticati

Richiedono autenticazione Application Password o OAuth e una capability manage_woocommerce o edit_products:

• PATCH /wp-json/dfdpp/v1/passport/{product_id} — aggiorna parzialmente i campi di un passaporto.
• POST /wp-json/dfdpp/v1/passport/{product_id}/publish — pubblica il passaporto (scorciatoia senza passare dall’amministrazione).

Personalizzazione

Sovrascrivere la pagina pubblica

Copia public/templates/dpp-public.php dal plugin in una cartella dfdpp/ alla radice del tuo tema attivo. Il plugin utilizzerà prioritariamente questo file, il che ti permette di rifare completamente il rendering senza toccare il plugin. La logica di recupero dei dati resta invariata: disponi delle variabili $passport e $data esattamente come nel template originale.

Filtro del payload JSON

Il filtro dfdpp_passport_payload ti permette di aggiungere o modificare campi nel payload JSON esposto. Esempio: aggiungere un campo proprietario internal_reference visibile solo al tuo 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 );

Blocco sulla pagina prodotto

Il blocco che invita a consultare il passaporto sulla pagina pubblica del prodotto WooCommerce può essere spostato, disattivato o sostituito manipolando l’hook:

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

// Piazzarlo altrove, es. sopra il pulsante Aggiungi al carrello
add_action( 'woocommerce_single_product_summary', array( dfdpp()->frontend, 'render_product_dpp_link' ), 25 );

Traduzioni

Il plugin è fornito con una traduzione francese completa (languages/dfdpp-fr_FR.po e .mo) e un file template dfdpp.pot (291 stringhe uniche) per tradurre verso altre lingue con Poedit o qualsiasi strumento compatibile gettext.

Polylang Pro e WPML sono supportati per la traduzione dei contenuti prodotto (nome, descrizione, categoria ESPR). Il passaporto resta legato al prodotto sorgente, il che garantisce un’unica fonte di verità per i dati di conformità permettendo al contempo una visualizzazione multilingue della pagina pubblica.

Compatibilità HPOS

Il plugin dichiara esplicitamente la compatibilità con l’archiviazione ad alte prestazioni degli ordini WooCommerce (High-Performance Order Storage). Non memorizza alcun dato nel custom post type shop_order — le 5 tabelle dedicate sono indipendenti. Puoi attivare HPOS senza timore di rompere il plugin.

FAQ e risoluzione problemi

L’URL pubblica restituisce un 404

Tre cause possibili:

• Il passaporto è in stato Bozza o Archiviato — passalo a Pubblicato.
• Le rewrite rules non sono state flushate — vai su Impostazioni → Permalink e salva (senza cambiare nulla).
• Un permalink “Semplice” è attivo — passa a “Nome articolo” o qualsiasi altro formato non semplice.

Il QR code non si visualizza

Verifica che il tuo hosting permetta la scrittura della directory wp-content/uploads/ e che l’estensione GD sia attivata in PHP (necessaria per la generazione PNG). Se sei in un ambiente vincolato, forza il formato SVG nelle impostazioni: non dipende da GD.

Come fornire la tracciabilità a un partner esterno?

Usa l’API REST. Crea un Application Password dedicato al partner nel suo account utente WordPress (Utenti → Profilo → Application Passwords), poi forniscigli la documentazione di un endpoint PATCH perché possa pushare i suoi eventi di tracciabilità nel tempo.

Posso generare i QR code in massa?

Sì, via WP-CLI. Uno script personalizzato può iterare sui prodotti e chiamare DFDPP_QRCode::output_png() o ::as_svg() per generare i file. Contatta il supporto se vuoi un comando WP-CLI chiavi in mano per il tuo catalogo.

Funziona con i prodotti variabili?

Sì, il passaporto è legato al prodotto padre. Se hai bisogno di un passaporto distinto per variazione (tipico per l’elettronica dove ogni configurazione ha un’impronta di carbonio diversa), contattaci per discutere un’estensione.

Disinstallazione

La disattivazione semplice del plugin conserva tutti i dati. I tuoi passaporti rimangono in base, pronti per essere riattivati.

La disinstallazione completa (pulsante Elimina sulla pagina dei plugin) attiva uninstall.php, che:

• Elimina le 5 tabelle personalizzate
• Elimina tutte le opzioni dfdpp_*
• Pulisce i transient eventuali
• Flusha le rewrite rules

Supporto

Il supporto tecnico viene erogato via e-mail in francese e inglese. Scrivi a support@datafirefly.com specificando la versione del plugin, la versione di WordPress e WooCommerce, e un estratto dei log se hai un messaggio d’errore PHP.