DataFirefly Digital Product Passport: documentatie

Inleiding

De plugin DataFirefly Digital Product Passport geeft WooCommerce alles wat nodig is om een Digitaal Productpaspoort (DPP) te genereren dat voldoet aan de Europese verordening Ecodesign for Sustainable Products (ESPR). Dit paspoort wordt vanaf 2027 stapsgewijs verplicht in de Europese Unie, te beginnen bij textiel, batterijen en consumentenelektronica, en breidt zich daarna uit naar vrijwel alle producten die op de Europese markt komen.

Concreet krijgt elk WooCommerce-product een stabiele unieke identificatie (UUID v4), een ingebouwde QR-code, een nette publieke URL van het type /dpp/{uuid}, een volledig register van onderdelen en materialen, een traceerbaarheidstijdlijn en een publieke REST API. Er zijn geen externe aanroepen: alles wordt aan de serverzijde gegenereerd.

Vereisten

• WordPress 6.0 of hoger
• WooCommerce 7.0 of hoger, geactiveerd
• PHP 7.4 minimaal (getest tot en met PHP 8.3)
• Een andere permalinkstructuur dan “Eenvoudig” (Instellingen → Permalinks)

Installatie

1. Download de ZIP dfdpp-1.0.0.zip vanuit je DataFirefly-account.
2. Ga naar Plugins → Nieuwe plugin → Plugin uploaden, selecteer de ZIP en klik op Nu installeren.
3. Klik op Activeren. De 5 eigen tabellen worden automatisch aangemaakt (wp_dfdpp_passports, wp_dfdpp_components, wp_dfdpp_materials, wp_dfdpp_suppliers, wp_dfdpp_events) en de standaardopties worden ingesteld.
4. Reageert de publieke URL /dpp/{uuid} niet meteen, ga dan naar Instellingen → Permalinks en klik op Wijzigingen opslaan (zonder iets te wijzigen) om een flush af te dwingen.

Algemene configuratie

Ga naar WooCommerce → DPP-paspoort. Op dit scherm staan alle instellingen van de plugin bij elkaar.

Publieke URL en QR-code

• URL-voorvoegsel: standaard dpp, wat leidt tot jouwdomein.com/dpp/{uuid}. Wijzig dit als je liever paspoort, product-passport of iets anders gebruikt. Bezoek na een wijziging Instellingen → Permalinks.
• Grootte van de QR: zoomfactor van 1 tot 10. Waarde 6 (standaard) levert ongeveer 240 px per zijde op.
• Marge: aantal witte modules rond de QR (standaard 4).
• Foutcorrectie: L / M / Q / H. Blijf op H als de QR op een etiket wordt gedrukt: tot 30 procent van de code mag beschadigd zijn zonder dat het uitlezen mislukt.
• Voorkeursformaat: PNG (raster, universeel) of SVG (vectorieel, beter voor grootformaatdruk).

Standaardidentiteit van de fabrikant

Vul hier de gegevens in die je niet per product wilt overtypen:

• Bedrijfsnaam, adres, land van fabricage
• Standaardland dat op onderdelen en materialen wordt toegepast
• Standaard ESPR-categorie (textiel, batterij, elektronica, meubilair en zo verder)

Publieke weergave

Vijf onafhankelijke schakelaars bepalen wat je klanten op de publieke paspoortpagina zien:

• Koolstofvoetafdruk (standaard aan)
• Leveranciers (standaard uit, gevoelige gegevens)
• Materiaalsamenstelling (aan)
• Repareerbaarheid en reserveonderdelen (aan)
• Traceerbaarheidstijdlijn (aan)

Automatisch publiceren

Vink je deze optie aan, dan gaat elk paspoort automatisch naar published zodra het WooCommerce-product zelf wordt gepubliceerd. Handig bij een catalogus van enkele honderden producten die door een niet-technisch team wordt beheerd. Anders moet elk paspoort handmatig worden gepubliceerd, wat een laatste controle garandeert.

Branding

• Accentkleur: hexadecimaal formaat (bijvoorbeeld #0f172a). Ze wordt toegepast op de hero, de koppen en de knoppen van de publieke pagina.
• URL van het logo: wordt bovenaan de publieke pagina getoond. Gebruik een transparante afbeelding (PNG of SVG), want ze wordt op een donkere achtergrond omgekeerd.

Een paspoort voor een product aanmaken

Open een willekeurig product in WooCommerce. In het productgegevenspaneel verschijnt een nieuw tabblad DPP-paspoort (naast Algemeen, Voorraad, Verzending en zo verder). Het bestaat uit 8 onderdelen.

Tabblad Identificatie

Het verplichte startpunt om te kunnen publiceren:

• Status: Concept / Gepubliceerd / Gearchiveerd. Alleen Gepubliceerd maakt de publieke URL bereikbaar.
• ESPR-categorie: bepaalt de gegevensstructuur die Europese auditors verwachten aan te treffen. Kies textile, battery, electronics, furniture, iron_steel, aluminium, tyres, detergents, paints, lubricants, chemicals, cosmetics, toys, construction of general.
• GTIN / EAN / UPC: de internationale commerciële barcode.
• Modelreferentie, Batchnummer, Serienummer: vul de velden in die op je product van toepassing zijn.
• Fabrikant: naam, adres, land (vooraf ingevuld vanuit de algemene instellingen als je die hebt ingericht).
• Fabricagedatum en Productielocatie (stad, fabriek of atelier).

Tabblad Duurzaamheid en voetafdruk

• Koolstofvoetafdruk: numerieke waarde, eenheid (standaard kgCO2e) en de gehanteerde berekeningsmethode (PEF, ISO 14067, GHG Protocol). Vul de voetafdruk alleen in als je die met een gedocumenteerde methode kunt onderbouwen: dit is het punt waar audits het scherpst naar kijken.
• Repareerbaarheidsindex: score op 10.
• Verwachte levensduur in jaren.
• Garantieduur in maanden (in de EU geldt voor consumptiegoederen een minimum van 24 maanden).
• Beschikbaarheid van reserveonderdelen in jaren.
• Gerecycleerde inhoud in procenten.
• Recycleerbare inhoud in procenten.

Tabblad Instructies

Vier rijke velden die eenvoudige HTML accepteren (alinea’s, lijsten, links):

• Gebruik: tips om het meeste uit het product te halen en de levensduur te verlengen.
• Onderhoud: wassen, drogen, opbergen.
• Recycling: recyclingketen, gescheiden inzameling, inzamelpunten.
• Einde levensduur: wat te doen wanneer het product niet meer bruikbaar is.

Tabblad Conformiteit

• Zeer zorgwekkende stoffen (SCIP / REACH): lijst van stoffen van de REACH-kandidaatslijst die in meer dan 0,1 procent van het gewicht aanwezig zijn. Vrij formaat; we raden een opsomming aan met naam en CAS-nummer.
• Gevaarlijke stoffen: vermelding van de toepasselijke gevarenklassen (CLP, GHS).
• Certificeringen en labels: OEKO-TEX, GOTS, GRS, Ecolabel, EPEAT en dergelijke.

Tabblad Onderdelen

Vlak register van de onderdelen waaruit het product bestaat. Per onderdeel vul je in:

• Naam (verplicht)
• Type: uit een vaste lijst (hoofdstof, voering, zool, gesp, rits en zo verder)
• Gewicht in gram
• Naam van de leverancier (nooit publiek zichtbaar, tenzij je de bijbehorende schakelaar activeert)
• Land van herkomst in 3 tekens volgens ISO 3166 alpha-3 (bijvoorbeeld FRA, ITA, CHN)
• Recycleerbaar: ja / nee
• Vervangbaar: ja / nee (relevant voor elektronica en meubilair)

Tabblad Materialen

Fijnmaziger materiaalregister met genormeerde codes:

• Materiaalcode: keuzelijst met de belangrijkste codes uit ISO 11469 / ISO 1043 voor kunststoffen (PET, PP, PE, PVC, PS, PA en meer), ISO 1833 voor textiel (WO wol, CO katoen, PL polyester, VI viscose, EL elastaan en meer), DIN 6120 voor metalen, en de batterijchemieën (Li-ion, LFP, NMC, NCA, NiMH, Pb).
• Aangepaste naam: voor als de vaste code niet volstaat.
• Percentage: aandeel van dit materiaal in het product (tot 4 decimalen).
• Gerecycleerd plus % gerecycleerd: gaat het om gerecycleerde inhoud en zo ja, in welke verhouding.
• Hernieuwbaar: materiaal van hernieuwbare biologische oorsprong.
• CAS-nr.: CAS-identificatie van de stof (voor gereguleerde chemische stoffen).

Tabblad Traceerbaarheid

Tijdlijn met de sleutelmomenten in de levenscyclus. Elke gebeurtenis combineert een datum, een type, een betrokken partij, een locatie en een beschrijving. De beschikbare types dekken de hele cyclus:

• Productie
• Kwaliteitscontrole
• Transport
• Import / Export
• Distributie
• Verkoop
• Reparatie
• Refurbishment
• Recycling
• Einde levensduur

Tabblad QR-code

Dit tabblad wordt actief zodra het product één keer is opgeslagen. Het toont:

• De gegenereerde QR-code (voorbeeld als data-URI)
• De UUID van het paspoort
• De aanklikbare publieke URL
• Drie downloadknoppen: PNG, SVG en ruwe JSON

Een paspoort publiceren

Een paspoort met de status Concept is publiek niet bereikbaar: de URL geeft een 404. Publiceren doe je zo:

1. Open het product en ga naar het tabblad DPP-paspoort → Identificatie.
2. Zet Status op Gepubliceerd.
3. Klik rechtsboven bij het product op Bijwerken.

De datum van de eerste publicatie wordt automatisch opgeslagen in published_at. Een gepubliceerd paspoort kan op elk moment terug naar Concept of naar Gearchiveerd.

Publieke paspoortpagina

De URL in de vorm jouwdomein.com/dpp/8f3a2c1d-4b5e-6f7a-8b9c-0d1e2f3a4b5c opent een responsive pagina met:

• Een hero met de productnaam, de ESPR-categorie, het merklogo en de productafbeelding
• Een balk met identificaties (UUID, GTIN, model, batch, serie, SKU)
• Een kaart fabrikant met adres en productiedatum
• Een kaart duurzaamheid en voetafdruk met de meetwaarden als tegels
• De tabellen onderdelen en materialen (afhankelijk van de weergaveschakelaars)
• De instructies (gebruik, onderhoud, recycling, einde levensduur)
• De wettelijke conformiteit (certificeringen, stoffen, gevaarlijke materialen)
• Een verticale traceerbaarheidstijdlijn met datums en locaties
• Een zijbalk met QR-code en downloads in PNG / SVG / JSON
• Een blok JSON-LD schema.org Product dat automatisch wordt geïnjecteerd voor SEO en interoperabiliteit

Op de publieke WooCommerce-productpagina nodigt een subtiel blok bezoekers uit om het paspoort te raadplegen, met een miniatuur-QR. Dat blok wordt automatisch onder de productsamenvatting geplaatst (hook woocommerce_after_single_product_summary, prioriteit 25).

Alternatieve formaten

Dezelfde URL accepteert twee varianten:

• /dpp/{uuid}?dfdpp_format=json of /dpp/{uuid}.json: geeft de volledige JSON-payload terug, inclusief het JSON-LD-blok.
• /dpp/{uuid}?dfdpp_format=qr of /dpp/{uuid}/qr: downloadt de QR-code direct als PNG.

REST API

Alle endpoints zitten onder de namespace dfdpp/v1.

Publieke endpoints

• GET /wp-json/dfdpp/v1/passport/{uuid}: geeft de volledige JSON-payload van het paspoort terug.
• GET /wp-json/dfdpp/v1/passport/by-product/{product_id}: hetzelfde, maar opgezocht via de WooCommerce-productidentificatie.
• GET /wp-json/dfdpp/v1/passport/{uuid}/qr: geeft de QR-code als vectoriële SVG terug.

Deze endpoints geven uitsluitend paspoorten met de status Gepubliceerd terug.

Geauthenticeerde endpoints

Vereisen authenticatie via Application Password of OAuth en de capability manage_woocommerce of edit_products:

• PATCH /wp-json/dfdpp/v1/passport/{product_id}: werkt velden van een paspoort gedeeltelijk bij.
• POST /wp-json/dfdpp/v1/passport/{product_id}/publish: publiceert het paspoort (snelkoppeling zonder via de beheeromgeving te gaan).

Aanpassen

De publieke pagina overschrijven

Kopieer public/templates/dpp-public.php vanuit de plugin naar een map dfdpp/ in de hoofdmap van je actieve thema. De plugin gebruikt dat bestand met voorrang, waardoor je de weergave volledig kunt herbouwen zonder de plugin aan te raken. De logica voor het ophalen van de gegevens blijft ongewijzigd: je beschikt over de variabelen $passport en $data, precies zoals in het originele template.

Filter op de JSON-payload

Met het filter dfdpp_passport_payload voeg je velden toe aan de gepubliceerde JSON-payload of pas je die aan. Voorbeeld: een eigen veld internal_reference toevoegen dat alleen voor je ERP zichtbaar is.

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

Blok op de productpagina

Het blok dat op de publieke WooCommerce-productpagina naar het paspoort verwijst, kun je verplaatsen, uitschakelen of vervangen door de hook aan te passen:

// Volledig verwijderen
remove_action( 'woocommerce_after_single_product_summary', array( dfdpp()->frontend, 'render_product_dpp_link' ), 25 );

// Elders plaatsen, bijvoorbeeld boven de knop In winkelwagen
add_action( 'woocommerce_single_product_summary', array( dfdpp()->frontend, 'render_product_dpp_link' ), 25 );

Vertalingen

De plugin wordt geleverd met een volledige Franse vertaling (languages/dfdpp-fr_FR.po en .mo) en een sjabloonbestand dfdpp.pot (291 unieke teksten) om naar andere talen te vertalen met Poedit of een ander gettext-compatibel hulpmiddel.

Polylang Pro en WPML worden ondersteund voor het vertalen van de productinhoud (naam, beschrijving, ESPR-categorie). Het paspoort blijft gekoppeld aan het bronproduct, wat één enkele bron van waarheid voor de conformiteitsgegevens garandeert en tegelijk een meertalige weergave van de publieke pagina mogelijk maakt.

HPOS-compatibiliteit

De plugin verklaart uitdrukkelijk zijn compatibiliteit met de high performance order storage van WooCommerce. Ze slaat geen gegevens op in het custom post type shop_order: de 5 eigen tabellen staan los. Je kunt HPOS dus zonder zorgen inschakelen.

Veelgestelde vragen en probleemoplossing

De publieke URL geeft een 404

Drie mogelijke oorzaken:

• Het paspoort staat op Concept of Gearchiveerd: zet het op Gepubliceerd.
• De rewrite rules zijn niet geflusht: ga naar Instellingen → Permalinks en sla op (zonder iets te wijzigen).
• Er is een “Eenvoudige” permalinkstructuur actief: schakel over naar “Berichtnaam” of een andere niet-eenvoudige structuur.

De QR-code verschijnt niet

Controleer of je hostingpartij schrijven naar de map wp-content/uploads/ toestaat en of de GD-extensie in PHP is ingeschakeld (nodig voor PNG-generatie). Werk je in een beperkte omgeving, forceer dan het SVG-formaat in de instellingen: dat is niet van GD afhankelijk.

Hoe geef ik een externe partner toegang tot de traceerbaarheid?

Gebruik de REST API. Maak in het WordPress-gebruikersaccount van de partner een specifiek Application Password aan (Gebruikers → Profiel → Application Passwords) en geef hem de documentatie van een PATCH-endpoint mee, zodat hij gaandeweg zijn eigen traceerbaarheidsgebeurtenissen kan doorsturen.

Kan ik QR-codes in bulk genereren?

Ja, via WP-CLI. Een eigen script kan door de producten heen lopen en DFDPP_QRCode::output_png() of ::as_svg() aanroepen om de bestanden aan te maken. Neem contact op met de support als je een kant-en-klaar WP-CLI-commando voor je catalogus wilt.

Werkt dit met variabele producten?

Ja, het paspoort wordt aan het bovenliggende product gekoppeld. Heb je een apart paspoort per variatie nodig (typisch voor elektronica, waar elke configuratie een andere koolstofvoetafdruk heeft), neem dan contact met ons op om een uitbreiding te bespreken.

Verwijderen

Alleen de plugin deactiveren behoudt alle gegevens. Je paspoorten blijven in de database staan, klaar om weer in gebruik te worden genomen.

Een volledige verwijdering (knop Verwijderen op de pluginpagina) activeert uninstall.php, dat:

• de 5 eigen tabellen verwijdert
• alle opties dfdpp_* verwijdert
• eventuele transients opruimt
• de rewrite rules flusht

Support

Technische ondersteuning verloopt per e-mail in het Frans en het Engels. Schrijf naar support@datafirefly.com en vermeld de versie van de plugin, de versie van WordPress en WooCommerce, en een fragment uit de logs als je een PHP-foutmelding hebt.