DataFirefly Digital Product Passport: dokumentacja

Wprowadzenie

Wtyczka DataFirefly Digital Product Passport dodaje do WooCommerce wszystko, co potrzebne do wygenerowania Cyfrowego Paszportu Produktu (DPP) zgodnego z europejskim rozporządzeniem o ekoprojektowaniu produktów zrównoważonych (ESPR). Paszport ten staje się w Unii Europejskiej stopniowo obowiązkowy od 2027 roku, zaczynając od tekstyliów, baterii i elektroniki konsumenckiej, a docelowo obejmie niemal wszystkie produkty wprowadzane na rynek europejski.

Konkretnie: każdy produkt WooCommerce otrzymuje stabilny unikalny identyfikator (UUID v4), natywny kod QR, czysty publiczny adres URL w rodzaju /dpp/{uuid}, kompletny rejestr komponentów i materiałów, oś czasu identyfikowalności oraz publiczne REST API. Bez żadnych wywołań zewnętrznych: wszystko generowane jest po stronie serwera.

Wymagania

• WordPress 6.0 lub nowszy
• WooCommerce 7.0 lub nowszy, włączony
• PHP minimum 7.4 (testowane do PHP 8.3)
• Bezpośrednie odnośniki inne niż „Prosty” (Ustawienia → Bezpośrednie odnośniki)

Instalacja

1. Pobierz ZIP dfdpp-1.0.0.zip ze swojego konta DataFirefly.
2. Przejdź do Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer, wybierz ZIP, a następnie Zainstaluj teraz.
3. Kliknij Włącz. 5 własnych tabel tworzy się automatycznie (wp_dfdpp_passports, wp_dfdpp_components, wp_dfdpp_materials, wp_dfdpp_suppliers, wp_dfdpp_events), a opcje domyślne zostają założone.
4. Jeśli publiczny adres /dpp/{uuid} nie odpowiada od razu, przejdź do Ustawienia → Bezpośrednie odnośniki i kliknij Zapisz zmiany (bez żadnej zmiany), aby wymusić odświeżenie reguł.

Konfiguracja globalna

Przejdź do WooCommerce → Paszport DPP. Ten ekran zbiera wszystkie ustawienia wtyczki.

Publiczny adres URL i kod QR

• Przedrostek URL: domyślnie dpp, co daje twojadomena.pl/dpp/{uuid}. Zmień go, jeśli wolisz paszport, product-passport albo inny. Po zmianie odwiedź Ustawienia → Bezpośrednie odnośniki.
• Rozmiar QR: współczynnik powiększenia od 1 do 10. Wartość 6 (domyślna) daje około 240 px boku.
• Margines: liczba białych modułów wokół QR (domyślnie 4).
• Korekcja błędów: L / M / Q / H. Zostań przy H, jeśli QR będzie drukowany na etykiecie: do 30 % kodu może zostać uszkodzone bez utraty czytelności.
• Preferowany format: PNG (rastrowy, uniwersalny) albo SVG (wektorowy, lepszy do druku wielkoformatowego).

Domyślna tożsamość producenta

Wpisz tutaj informacje, których nie chcesz przepisywać produkt po produkcie:

• Nazwa firmy, adres, kraj produkcji
• Domyślny kraj stosowany do komponentów i materiałów
• Domyślna kategoria ESPR (tekstylia, bateria, elektronika, meble i tak dalej)

Wyświetlanie publiczne

Pięć niezależnych przełączników steruje tym, co klienci widzą na publicznej stronie paszportu:

• Ślad węglowy (domyślnie włączony)
• Dostawcy (domyślnie wyłączeni: dane wrażliwe)
• Skład materiałowy (włączony)
• Naprawialność i części zamienne (włączone)
• Oś czasu identyfikowalności (włączona)

Publikacja automatyczna

Po zaznaczeniu tej opcji każdy paszport automatycznie przechodzi w status published, gdy sam produkt WooCommerce zostaje opublikowany. Przydatne przy katalogu kilkuset produktów prowadzonym przez zespół nietechniczny. W przeciwnym razie każdy paszport trzeba opublikować ręcznie, co gwarantuje kontrolę końcową.

Branding

• Kolor akcentu: format szesnastkowy (np. #0f172a). Stosowany do hero, tytułów i przycisków strony publicznej.
• Adres URL logo: wyświetlane u góry strony publicznej. Użyj obrazu z przezroczystością (PNG albo SVG), będzie odwracany na ciemnym tle.

Tworzenie paszportu dla produktu

Otwórz dowolny produkt w WooCommerce. W panelu danych produktu (obok Ogólne, Magazyn, Wysyłka i pozostałych) pojawia się nowa zakładka Paszport DPP. Zbiera 8 sekcji.

Zakładka Identyfikacja

Obowiązkowy punkt wejścia do publikacji:

• Status: Szkic / Opublikowany / Zarchiwizowany. Tylko Opublikowany udostępnia publiczny adres URL.
• Kategoria ESPR: określa strukturę danych, jakiej oczekują europejscy audytorzy. Wybierz textile, battery, electronics, furniture, iron_steel, aluminium, tyres, detergents, paints, lubricants, chemicals, cosmetics, toys, construction albo general.
• GTIN / EAN / UPC: międzynarodowy handlowy kod kreskowy.
• Oznaczenie modelu, Numer partii, Numer seryjny: uzupełnij pola dotyczące Twojego produktu.
• Producent: nazwa, adres, kraj (wstępnie wypełnione z ustawień globalnych, jeśli je skonfigurowano).
• Data produkcji i Miejsce produkcji (miasto, fabryka albo warsztat).

Zakładka Trwałość i ślad

• Ślad węglowy: wartość liczbowa, jednostka (domyślnie kgCO2e) i referencyjna metodologia obliczeń (PEF, ISO 14067, GHG Protocol). Wpisuj ślad tylko wtedy, gdy potrafisz go uzasadnić udokumentowaną metodologią: to punkt najbardziej prześwietlany przez audyty.
• Indeks naprawialności: ocena w skali do 10.
• Przewidywany czas życia w latach.
• Okres gwarancji w miesiącach (w UE dla dóbr konsumpcyjnych obowiązek co najmniej 24 miesięcy).
• Dostępność części zamiennych w latach.
• Zawartość z recyklingu w procentach.
• Zawartość nadająca się do recyklingu w procentach.

Zakładka Instrukcje

Cztery pola tekstowe akceptujące podstawowy HTML (akapity, listy, linki):

• Użytkowanie: porady, jak najlepiej korzystać z produktu i wydłużyć jego życie.
• Pielęgnacja: pranie, suszenie, przechowywanie.
• Recykling: ścieżka recyklingu, segregacja, punkty zbiórki.
• Koniec życia: co zrobić, gdy produkt nie nadaje się już do użytku.

Zakładka Zgodność

• Substancje wzbudzające obawy (SCIP / REACH): lista substancji z listy kandydackiej REACH obecnych w stężeniu powyżej 0,1 % wagowo. Format dowolny, zalecamy listę punktowaną z nazwą i numerem CAS.
• Materiały niebezpieczne: wskazanie właściwych klas zagrożenia (CLP, GHS).
• Certyfikaty i etykiety: OEKO-TEX, GOTS, GRS, Ecolabel, EPEAT i inne.

Zakładka Komponenty

Płaski rejestr komponentów tworzących produkt. Dla każdego komponentu dodajesz:

• Nazwę (obowiązkowa)
• Typ: z predefiniowanej listy (tkanina główna, podszewka, podeszwa, klamra, zamek i tak dalej)
• Wagę w gramach
• Nazwę dostawcy (nigdy nie pokazywaną publicznie, chyba że włączysz dedykowany przełącznik)
• Kraj pochodzenia w 3-znakowym kodzie ISO 3166 alpha-3 (np. POL, ITA, CHN)
• Recyklowalny: tak / nie
• Wymienny: tak / nie (istotne dla elektroniki, mebli)

Zakładka Materiały

Bardziej szczegółowy rejestr materiałowy, ze znormalizowanymi kodami:

• Kod materiału: lista rozwijana z głównymi kodami ISO 11469 / ISO 1043 dla tworzyw sztucznych (PET, PP, PE, PVC, PS, PA i pozostałe), ISO 1833 dla tekstyliów (WO wełna, CO bawełna, PL poliester, VI wiskoza, EL elastan i pozostałe), DIN 6120 dla metali oraz chemie baterii (Li-ion, LFP, NMC, NCA, NiMH, Pb).
• Nazwa własna: jeśli predefiniowany kod nie pasuje.
• Procent: udział tego materiału w produkcie (do 4 miejsc po przecinku).
• Z recyklingu + % z recyklingu: czy to zawartość z recyklingu, a jeśli tak, w jakiej proporcji.
• Odnawialny: materiał pochodzenia biologicznego odnawialnego.
• Nr CAS: identyfikator CAS substancji (dla regulowanych substancji chemicznych).

Zakładka Identyfikowalność

Oś czasu kluczowych zdarzeń cyklu życia. Każde zdarzenie łączy datę, typ, aktora, miejsce i opis. Dostępne typy pokrywają cały cykl:

• Produkcja
• Kontrola jakości
• Transport
• Import / Eksport
• Dystrybucja
• Sprzedaż
• Naprawa
• Odnowienie (refurbishment)
• Recykling
• Koniec życia

Zakładka Kod QR

Ta zakładka staje się aktywna po pierwszym zapisaniu produktu. Wyświetla:

• Wygenerowany kod QR (podgląd w data-URI)
• UUID paszportu
• Klikalny publiczny adres URL
• Trzy przyciski pobierania: PNG, SVG i surowy JSON

Publikowanie paszportu

Paszport w statusie Szkic nie jest dostępny publicznie: adres zwraca 404. Aby go opublikować:

1. Otwórz produkt, przejdź do Paszport DPP → Identyfikacja.
2. Przełącz Status na Opublikowany.
3. Kliknij Zaktualizuj w prawym górnym rogu produktu.

Data pierwszej publikacji zapamiętywana jest automatycznie w published_at. Opublikowany paszport można w każdej chwili cofnąć do Szkicu albo przenieść do Zarchiwizowanych.

Publiczna strona paszportu

Adres w postaci twojadomena.pl/dpp/8f3a2c1d-4b5e-6f7a-8b9c-0d1e2f3a4b5c otwiera responsywną stronę z:

• Hero z nazwą produktu, kategorią ESPR, logo marki i obrazem produktu
• Pasem identyfikatorów (UUID, GTIN, model, partia, numer seryjny, SKU)
• Kartą producenta z adresem i datą produkcji
• Kartą trwałości i śladu z metrykami w formie kafelków
• Tabelami komponentów i materiałów (według przełączników wyświetlania)
• Instrukcjami (użytkowanie, pielęgnacja, recykling, koniec życia)
• Zgodnością regulacyjną (certyfikaty, substancje, materiały niebezpieczne)
• Pionową osią czasu identyfikowalności z datami i miejscami
• Panelem bocznym z kodem QR i pobieraniem PNG / SVG / JSON
• Blokiem JSON-LD schema.org Product wstrzykiwanym automatycznie dla SEO i interoperacyjności

Na publicznej karcie produktu WooCommerce dyskretny blok zaprasza odwiedzających do obejrzenia paszportu, z miniaturowym QR. Blok dodawany jest automatycznie pod podsumowaniem produktu (hook woocommerce_after_single_product_summary, priorytet 25).

Formaty alternatywne

Ten sam adres akceptuje dwa sufiksy:

• /dpp/{uuid}?dfdpp_format=json albo /dpp/{uuid}.json: zwraca pełny payload JSON, łącznie z blokiem JSON-LD.
• /dpp/{uuid}?dfdpp_format=qr albo /dpp/{uuid}/qr: pobiera bezpośrednio kod QR w PNG.

REST API

Wszystkie endpointy udostępniane są w przestrzeni nazw dfdpp/v1.

Endpointy publiczne

• GET /wp-json/dfdpp/v1/passport/{uuid} — zwraca pełny payload JSON paszportu.
• GET /wp-json/dfdpp/v1/passport/by-product/{product_id} — to samo, ale wyszukiwane po identyfikatorze produktu WooCommerce.
• GET /wp-json/dfdpp/v1/passport/{uuid}/qr — zwraca kod QR w wektorowym SVG.

Te endpointy zwracają wyłącznie paszporty w statusie Opublikowany.

Endpointy uwierzytelnione

Wymagają uwierzytelniania Application Password albo OAuth oraz zdolności manage_woocommerce albo edit_products:

• PATCH /wp-json/dfdpp/v1/passport/{product_id} — częściowo aktualizuje pola paszportu.
• POST /wp-json/dfdpp/v1/passport/{product_id}/publish — publikuje paszport (skrót bez wchodzenia do panelu).

Personalizacja

Nadpisanie strony publicznej

Skopiuj public/templates/dpp-public.php z wtyczki do katalogu dfdpp/ w katalogu głównym aktywnego motywu. Wtyczka użyje w pierwszej kolejności tego pliku, co pozwala całkowicie przebudować wygląd bez dotykania wtyczki. Logika pobierania danych pozostaje bez zmian: masz do dyspozycji zmienne $passport i $data dokładnie jak w oryginalnym szablonie.

Filtr payloadu JSON

Filtr dfdpp_passport_payload pozwala dodać albo zmienić pola w udostępnianym ładunku JSON. Przykład: dodanie własnego pola internal_reference widocznego tylko dla Twojego 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 );

Blok na karcie produktu

Blok zapraszający do obejrzenia paszportu na publicznej karcie produktu WooCommerce można przenieść, wyłączyć albo zastąpić, manipulując hookiem:

// Remove it completely
remove_action( 'woocommerce_after_single_product_summary', array( dfdpp()->frontend, 'render_product_dpp_link' ), 25 );

// Place it elsewhere, e.g. above the Add to cart button
add_action( 'woocommerce_single_product_summary', array( dfdpp()->frontend, 'render_product_dpp_link' ), 25 );

Tłumaczenia

Wtyczka dostarczana jest z kompletnym tłumaczeniem francuskim (languages/dfdpp-fr_FR.po i .mo) oraz plikiem szablonu dfdpp.pot (291 unikalnych ciągów) do tłumaczenia na inne języki przy pomocy Poedit albo dowolnego narzędzia zgodnego z gettext.

Polylang Pro i WPML są wspierane dla tłumaczenia treści produktowych (nazwa, opis, kategoria ESPR). Paszport pozostaje przypięty do produktu źródłowego, co gwarantuje jedno źródło prawdy dla danych zgodności, a jednocześnie pozwala wyświetlać stronę publiczną wielojęzycznie.

Zgodność z HPOS

Wtyczka wprost deklaruje zgodność z wydajnym magazynem zamówień WooCommerce (High-Performance Order Storage). Nie przechowuje żadnych danych we własnym typie wpisu shop_order: 5 dedykowanych tabel jest niezależnych. Możesz włączyć HPOS bez obaw o konflikt z wtyczką.

FAQ i rozwiązywanie problemów

Publiczny adres zwraca 404

Trzy możliwe przyczyny:

• Paszport ma status Szkic albo Zarchiwizowany: przełącz go na Opublikowany.
• Reguły przepisywania nie zostały odświeżone: przejdź do Ustawienia → Bezpośrednie odnośniki i zapisz (bez żadnej zmiany).
• Aktywny jest odnośnik „Prosty”: przełącz na „Nazwa wpisu” albo dowolny inny format nieprosty.

Kod QR się nie wyświetla

Sprawdź, czy hosting pozwala na zapis w katalogu wp-content/uploads/ i czy rozszerzenie GD jest włączone w PHP (potrzebne do generowania PNG). W środowisku ograniczonym wymuś format SVG w ustawieniach: nie zależy on od GD.

Jak udostępnić identyfikowalność zewnętrznemu partnerowi?

Użyj REST API. Utwórz dedykowane Application Password dla partnera na jego koncie użytkownika WordPressa (Użytkownicy → Profil → Application Passwords), a następnie przekaż mu dokumentację endpointu PATCH, aby na bieżąco wypychał własne zdarzenia identyfikowalności.

Czy mogę generować kody QR masowo?

Tak, przez WP-CLI. Własny skrypt może iterować po produktach i wywoływać DFDPP_QRCode::output_png() albo ::as_svg(), aby wygenerować pliki. Skontaktuj się ze wsparciem, jeśli chcesz otrzymać gotową komendę WP-CLI dla swojego katalogu.

Czy działa z produktami wariantowymi?

Tak, paszport jest przypięty do produktu nadrzędnego. Jeśli potrzebujesz osobnego paszportu per wariant (typowe w elektronice, gdzie każda konfiguracja ma inny ślad węglowy), skontaktuj się z nami, aby omówić rozszerzenie.

Deinstalacja

Zwykłe wyłączenie wtyczki zachowuje wszystkie dane. Twoje paszporty pozostają w bazie, gotowe do ponownej aktywacji.

Pełna deinstalacja (przycisk Usuń na stronie wtyczek) uruchamia uninstall.php, który:

• Usuwa 5 własnych tabel
• Usuwa wszystkie opcje dfdpp_*
• Czyści ewentualne transienty
• Odświeża reguły przepisywania

Wsparcie

Wsparcie techniczne prowadzone jest e-mailem po francusku i angielsku. Napisz na support@datafirefly.com, podając wersję wtyczki, wersję WordPressa i WooCommerce oraz fragment logów, jeśli masz komunikat błędu PHP.