DataFirefly Digital Product Passport — Dokumentation

Einführung

Das DataFirefly Digital Product Passport Plugin ergänzt WooCommerce um alles Notwendige zur Erstellung eines Digitalen Produktpasses (DPP) gemäß der europäischen Ökodesign-Verordnung für nachhaltige Produkte (ESPR). Dieser Pass wird ab 2027 in der Europäischen Union schrittweise verpflichtend, beginnend mit Textilien, Batterien und Unterhaltungselektronik, bevor er sich auf nahezu alle auf dem europäischen Markt platzierten Produkte ausdehnt.

Konkret erhält jedes WooCommerce-Produkt einen stabilen einzigartigen Identifier (UUID v4), einen nativen QR-Code, eine saubere öffentliche URL wie /dpp/{uuid}, ein vollständiges Register von Komponenten und Materialien, eine Rückverfolgbarkeits-Timeline und eine öffentliche REST-API. Keine externen Aufrufe: alles wird serverseitig generiert.

Voraussetzungen

• WordPress 6.0 oder höher
• WooCommerce 7.0 oder höher, aktiviert
• PHP 7.4 mindestens (getestet bis PHP 8.3)
• Ein Permalink außer „Einfach“ (Einstellungen → Permalinks)

Installation

1. Laden Sie das ZIP dfdpp-1.0.0.zip aus Ihrem DataFirefly-Konto herunter.
2. Gehen Sie zu Plugins → Installieren → Plugin hochladen, wählen Sie das ZIP aus und klicken Sie auf Jetzt installieren.
3. Klicken Sie auf Aktivieren. Die 5 individuellen Tabellen werden automatisch angelegt (wp_dfdpp_passports, wp_dfdpp_components, wp_dfdpp_materials, wp_dfdpp_suppliers, wp_dfdpp_events) und die Standardoptionen gesetzt.
4. Wenn die öffentliche URL /dpp/{uuid} nicht sofort antwortet, gehen Sie zu Einstellungen → Permalinks und klicken Sie auf Änderungen speichern (ohne etwas zu ändern), um einen Flush zu erzwingen.

Globale Konfiguration

Gehen Sie zu WooCommerce → Pass DPP. Dieser Bildschirm fasst alle Plugin-Einstellungen zusammen.

Öffentliche URL und QR-Code

• URL-Präfix: standardmäßig dpp, was ihredomain.com/dpp/{uuid} ergibt. Ändern Sie es, wenn Sie pass, product-passport oder anderes bevorzugen. Denken Sie daran, nach der Änderung Einstellungen → Permalinks aufzurufen.
• QR-Größe: Zoom-Faktor 1 bis 10. Wert 6 (Standard) erzeugt etwa 240 px pro Seite.
• Rand: Anzahl weißer Module um den QR (4 standardmäßig).
• Fehlerkorrektur: L / M / Q / H. Bleiben Sie bei H, wenn der QR auf ein Etikett gedruckt wird: bis zu 30% des Codes können beschädigt werden, ohne die Lesbarkeit zu gefährden.
• Bevorzugtes Format: PNG (Raster, universell) oder SVG (Vektor, besser für großformatiges Drucken).

Standard-Herstelleridentität

Tragen Sie hier Informationen ein, die Sie nicht Produkt für Produkt neu eingeben möchten:

• Firmenname, Adresse, Herstellungsland
• Standardland für Komponenten und Materialien
• Standard-ESPR-Kategorie (Textil, Batterie, Elektronik, Möbel usw.)

Öffentliche Anzeige

Fünf unabhängige Umschalter steuern, was Ihre Kunden auf der öffentlichen Pass-Seite sehen:

• CO2-Fußabdruck (standardmäßig aktiviert)
• Lieferanten (standardmäßig deaktiviert — sensible Daten)
• Materialzusammensetzung (aktiviert)
• Reparierbarkeit und Ersatzteile (aktiviert)
• Rückverfolgbarkeits-Timeline (aktiviert)

Automatische Veröffentlichung

Wenn Sie diese Option ankreuzen, wird jeder Pass automatisch auf veröffentlicht gesetzt, sobald das WooCommerce-Produkt selbst veröffentlicht wird. Nützlich für einen Katalog mit hunderten Produkten, der von einem nicht-technischen Team verwaltet wird. Andernfalls muss jeder Pass manuell veröffentlicht werden — was eine finale Kontrolle gewährleistet.

Branding

• Akzentfarbe: hexadezimales Format (z.B. #0f172a). Wird auf Hero, Titel und Buttons der öffentlichen Seite angewendet.
• Logo-URL: oben auf der öffentlichen Seite angezeigt. Verwenden Sie ein transparentes Bild (PNG oder SVG) — es wird auf dem dunklen Hintergrund invertiert.

Einen Pass für ein Produkt erstellen

Öffnen Sie ein beliebiges Produkt in WooCommerce. Ein neuer Tab Pass DPP erscheint im Produktdaten-Panel (neben Allgemein, Bestand, Versand usw.). Er fasst 8 Bereiche zusammen.

Identifikations-Tab

Der obligatorische Einstiegspunkt für die Veröffentlichung:

• Status: Entwurf / Veröffentlicht / Archiviert. Nur Veröffentlicht macht die öffentliche URL zugänglich.
• ESPR-Kategorie: bestimmt die Datenstruktur, die europäische Prüfer erwarten. Wählen Sie textile, battery, electronics, furniture, iron_steel, aluminium, tyres, detergents, paints, lubricants, chemicals, cosmetics, toys, construction oder general.
• GTIN / EAN / UPC: internationaler Handels-Barcode.
• Modellreferenz, Chargennummer, Seriennummer: füllen Sie die auf Ihr Produkt anwendbaren Felder aus.
• Hersteller: Name, Adresse, Land (vorausgefüllt aus den globalen Einstellungen, falls konfiguriert).
• Herstellungsdatum und Herstellungsstandort (Stadt, Fabrik oder Werkstatt).

Tab Nachhaltigkeit und Fußabdruck

• CO2-Fußabdruck: numerischer Wert, Einheit (kgCO2e standardmäßig) und referenzierte Berechnungsmethodik (PEF, ISO 14067, GHG Protocol). Tragen Sie den Fußabdruck nur ein, wenn Sie ihn mit einer dokumentierten Methodik belegen können — das ist der am stärksten geprüfte Punkt bei Audits.
• Reparierbarkeitsindex: Bewertung auf 10.
• Erwartete Lebensdauer in Jahren.
• Garantiedauer in Monaten (EU-Verpflichtung von mindestens 24 Monaten für Verbrauchsgüter).
• Ersatzteilverfügbarkeit in Jahren.
• Recycelter Anteil in Prozent.
• Recyclingfähiger Anteil in Prozent.

Tab Anleitungen

Vier reichhaltige Felder, die grundlegendes HTML (Absätze, Listen, Links) akzeptieren:

• Verwendung: Tipps, um das Beste aus dem Produkt herauszuholen und seine Lebensdauer zu verlängern.
• Pflege: Waschen, Trocknen, Lagerung.
• Recycling: Recyclingstrang, Mülltrennung, Sammelstellen.
• Ende der Lebensdauer: was zu tun ist, wenn das Produkt nicht mehr nutzbar ist.

Tab Konformität

• Besorgniserregende Stoffe (SCIP / REACH): Liste der Stoffe aus der REACH-Kandidatenliste, die zu mehr als 0,1% des Gewichts enthalten sind. Freies Format; wir empfehlen eine Aufzählung mit Name und CAS-Nummer.
• Gefahrstoffe: Nennung anwendbarer Gefahrenklassen (CLP, GHS).
• Zertifizierungen und Labels: OEKO-TEX, GOTS, GRS, Ecolabel, EPEAT usw.

Tab Komponenten

Flaches Register der Komponenten, die das Produkt bilden. Für jede Komponente fügen Sie hinzu:

• Name (erforderlich)
• Typ: aus einer vordefinierten Liste (Hauptstoff, Futter, Sohle, Schnalle, Reißverschluss usw.)
• Gewicht in Gramm
• Lieferantenname (nie öffentlich sichtbar, es sei denn, Sie aktivieren den dedizierten Umschalter)
• Herkunftsland in 3-Zeichen ISO 3166 alpha-3 (z.B. FRA, ITA, CHN)
• Recyclingfähig: ja / nein
• Ersetzbar: ja / nein (relevant für Elektronik, Möbel)

Tab Materialien

Granulareres Materialregister mit standardisierten Codes:

• Materialcode: Dropdown mit den wichtigsten ISO 11469 / ISO 1043 Codes für Kunststoffe (PET, PP, PE, PVC, PS, PA usw.), ISO 1833 für Textilien (WO Wolle, CO Baumwolle, PL Polyester, VI Viskose, EL Elastan usw.), DIN 6120 für Metalle, und Batterie-Chemien (Li-ion, LFP, NMC, NCA, NiMH, Pb).
• Benutzerdefinierter Name: falls der vordefinierte Code nicht passt.
• Prozentsatz: Anteil dieses Materials am Produkt (bis zu 4 Dezimalstellen).
• Recycelt + % recycelt: ob es recycelter Inhalt ist, und wenn ja, zu welchem Anteil.
• Erneuerbar: Material biologischer erneuerbarer Herkunft.
• CAS-Nr.: CAS-Identifier des Stoffes (für regulierte chemische Stoffe).

Tab Rückverfolgbarkeit

Timeline der Schlüsselereignisse des Lebenszyklus. Jedes Ereignis verknüpft ein Datum, einen Typ, einen Akteur, einen Ort und eine Beschreibung. Die verfügbaren Typen decken den gesamten Zyklus ab:

• Produktion
• Qualitätskontrolle
• Transport
• Import / Export
• Distribution
• Verkauf
• Reparatur
• Aufarbeitung
• Recycling
• Ende der Lebensdauer

Tab QR-Code

Dieser Tab wird aktiv, sobald das Produkt zum ersten Mal gespeichert wird. Er zeigt:

• Den generierten QR-Code (Data-URI-Vorschau)
• Die Pass-UUID
• Die anklickbare öffentliche URL
• Drei Download-Buttons: PNG, SVG und rohes JSON

Einen Pass veröffentlichen

Ein Pass im Entwurf-Status ist nicht öffentlich zugänglich — die URL gibt einen 404 zurück. So veröffentlichen Sie ihn:

1. Öffnen Sie das Produkt, gehen Sie zum Tab Pass DPP → Identifikation.
2. Setzen Sie Status auf Veröffentlicht.
3. Klicken Sie oben rechts am Produkt auf Aktualisieren.

Das Erstveröffentlichungsdatum wird automatisch in published_at gespeichert. Ein veröffentlichter Pass kann jederzeit wieder auf Entwurf zurückgesetzt oder auf Archiviert gesetzt werden.

Öffentliche Pass-Seite

Die URL vom Typ ihredomain.com/dpp/8f3a2c1d-4b5e-6f7a-8b9c-0d1e2f3a4b5c öffnet eine responsive Seite mit:

• Einem Hero mit Produktname, ESPR-Kategorie, Markenlogo und Produktbild
• Einem Identifier-Banner (UUID, GTIN, Modell, Charge, Serie, SKU)
• Einer Hersteller-Karte mit Adresse und Produktionsdatum
• Einer Nachhaltigkeits- und Fußabdruck-Karte mit Metriken als Kacheln
• Den Tabellen Komponenten und Materialien (je nach Anzeige-Umschaltern)
• Den Anleitungen (Verwendung, Pflege, Recycling, Ende der Lebensdauer)
• Der regulatorischen Konformität (Zertifizierungen, Stoffe, Gefahrstoffe)
• Einer vertikalen Rückverfolgbarkeits-Timeline mit Datumsangaben und Orten
• Einer QR-Code-Sidebar mit PNG / SVG / JSON Download
• Einem schema.org Product JSON-LD Block, der automatisch für SEO und Interoperabilität eingefügt wird

Auf der öffentlichen WooCommerce-Produktseite lädt ein dezenter Block Besucher ein, den Pass anzusehen, mit einem QR-Miniatur. Dieser Block wird automatisch unter der Produktzusammenfassung hinzugefügt (Hook woocommerce_after_single_product_summary, Priorität 25).

Alternative Formate

Dieselbe URL akzeptiert zwei Suffixe:

• /dpp/{uuid}?dfdpp_format=json oder /dpp/{uuid}.json: gibt die vollständige JSON-Nutzlast zurück, einschließlich des JSON-LD-Blocks.
• /dpp/{uuid}?dfdpp_format=qr oder /dpp/{uuid}/qr: lädt den QR-Code PNG direkt herunter.

REST-API

Alle Endpunkte sind unter dem Namespace dfdpp/v1 verfügbar.

Öffentliche Endpunkte

• GET /wp-json/dfdpp/v1/passport/{uuid} — gibt die vollständige JSON-Nutzlast des Passes zurück.
• GET /wp-json/dfdpp/v1/passport/by-product/{product_id} — dasselbe, aber gesucht nach WooCommerce-Produkt-Identifier.
• GET /wp-json/dfdpp/v1/passport/{uuid}/qr — gibt den QR-Code als Vektor-SVG zurück.

Diese Endpunkte geben nur Pässe im Veröffentlicht-Status zurück.

Authentifizierte Endpunkte

Erfordern Application Password oder OAuth Authentifizierung und eine Capability manage_woocommerce oder edit_products:

• PATCH /wp-json/dfdpp/v1/passport/{product_id} — aktualisiert teilweise die Felder eines Passes.
• POST /wp-json/dfdpp/v1/passport/{product_id}/publish — veröffentlicht den Pass (Abkürzung ohne Weg über die Administration).

Anpassung

Die öffentliche Seite überschreiben

Kopieren Sie public/templates/dpp-public.php aus dem Plugin in einen dfdpp/-Ordner im Stammverzeichnis Ihres aktiven Themes. Das Plugin verwendet vorrangig diese Datei, sodass Sie das Rendering komplett überarbeiten können, ohne das Plugin anzufassen. Die Datenabruflogik bleibt unverändert: Sie haben die Variablen $passport und $data genau wie in der ursprünglichen Vorlage.

JSON-Nutzlast-Filter

Der Filter dfdpp_passport_payload erlaubt Ihnen, Felder in der exponierten JSON-Nutzlast hinzuzufügen oder zu ändern. Beispiel: ein proprietäres Feld internal_reference nur für Ihr ERP sichtbar machen.

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 );

Block auf der Produktseite

Der Block, der zur Ansicht des Passes auf der öffentlichen WooCommerce-Produktseite einlädt, kann durch Manipulation des Hooks verschoben, deaktiviert oder ersetzt werden:

// Komplett entfernen
remove_action( 'woocommerce_after_single_product_summary', array( dfdpp()->frontend, 'render_product_dpp_link' ), 25 );

// Woanders platzieren, z.B. über dem In-den-Warenkorb-Button
add_action( 'woocommerce_single_product_summary', array( dfdpp()->frontend, 'render_product_dpp_link' ), 25 );

Übersetzungen

Das Plugin wird mit einer vollständigen französischen Übersetzung ausgeliefert (languages/dfdpp-fr_FR.po und .mo) und einer Vorlagendatei dfdpp.pot (291 einzigartige Zeichenketten) zur Übersetzung in andere Sprachen mit Poedit oder einem gettext-kompatiblen Werkzeug.

Polylang Pro und WPML werden für die Übersetzung von Produktinhalten (Name, Beschreibung, ESPR-Kategorie) unterstützt. Der Pass bleibt mit dem Quellprodukt verknüpft, was eine einzige Wahrheitsquelle für die Konformitätsdaten gewährleistet und gleichzeitig eine mehrsprachige Anzeige der öffentlichen Seite ermöglicht.

HPOS-Kompatibilität

Das Plugin deklariert explizit seine Kompatibilität mit dem High-Performance Order Storage von WooCommerce. Es speichert keine Daten im Custom Post Type shop_order — die 5 dedizierten Tabellen sind unabhängig. Sie können HPOS aktivieren, ohne Angst haben zu müssen, das Plugin zu brechen.

FAQ und Fehlerbehebung

Die öffentliche URL gibt einen 404 zurück

Drei mögliche Ursachen:

• Der Pass ist im Entwurf- oder Archiviert-Status — setzen Sie ihn auf Veröffentlicht.
• Rewrite-Regeln wurden nicht geflusht — gehen Sie zu Einstellungen → Permalinks und speichern Sie (ohne etwas zu ändern).
• Ein „Einfach“-Permalink ist aktiv — wechseln Sie zu „Beitragsname“ oder einem anderen nicht-einfachen Format.

Der QR-Code wird nicht angezeigt

Überprüfen Sie, ob Ihr Hoster das Schreiben in das Verzeichnis wp-content/uploads/ zulässt und ob die GD-Erweiterung in PHP aktiviert ist (erforderlich für die PNG-Generierung). Wenn Sie in einer eingeschränkten Umgebung sind, erzwingen Sie das SVG-Format in den Einstellungen: es hängt nicht von GD ab.

Wie stelle ich einem externen Partner Rückverfolgbarkeit zur Verfügung?

Nutzen Sie die REST-API. Erstellen Sie ein dediziertes Application Password für den Partner in seinem WordPress-Benutzerkonto (Benutzer → Profil → Application Passwords) und stellen Sie ihm die Dokumentation eines PATCH-Endpunkts zur Verfügung, damit er seine eigenen Rückverfolgbarkeitsereignisse nach und nach pushen kann.

Kann ich QR-Codes in Masse generieren?

Ja, über WP-CLI. Ein benutzerdefiniertes Skript kann über die Produkte iterieren und DFDPP_QRCode::output_png() oder ::as_svg() aufrufen, um die Dateien zu generieren. Kontaktieren Sie den Support, wenn Sie einen schlüsselfertigen WP-CLI-Befehl für Ihren Katalog wünschen.

Funktioniert es mit variablen Produkten?

Ja, der Pass ist mit dem übergeordneten Produkt verknüpft. Wenn Sie einen separaten Pass pro Variation benötigen (typisch für Elektronik, bei der jede Konfiguration einen anderen CO2-Fußabdruck hat), kontaktieren Sie uns, um eine Erweiterung zu besprechen.

Deinstallation

Eine einfache Deaktivierung des Plugins bewahrt alle Daten. Ihre Pässe bleiben in der Datenbank, bereit zur Reaktivierung.

Eine vollständige Deinstallation (Löschen-Button auf der Plugins-Seite) löst uninstall.php aus, welches:

• Die 5 individuellen Tabellen entfernt
• Alle dfdpp_*-Optionen entfernt
• Eventuelle Transients bereinigt
• Die Rewrite-Regeln flusht

Support

Der technische Support wird per E-Mail auf Französisch und Englisch geleistet. Schreiben Sie an support@datafirefly.com und geben Sie die Plugin-Version, die WordPress- und WooCommerce-Version sowie einen Auszug aus den Logs an, falls Sie eine PHP-Fehlermeldung haben.