# 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…
- Strona:
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [fr](https://www.datafirefly.com/documentation/dfdpp-doc/index.md), [en](https://www.datafirefly.com/en/documentation/dfdpp-doc/index.md), [es](https://www.datafirefly.com/es/documentation/dfdpp-doc/index.md), [de](https://www.datafirefly.com/de/documentation/dfdpp-doc/index.md), [it](https://www.datafirefly.com/it/documentation/dfdpp-doc/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfdpp-doc/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfdpp-doc/index.md)
- Indeks:
## 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.
**Dla kogo to jest?**
Dla każdego sklepu WooCommerce sprzedającego w UE: tekstylia, moda, baterie, elektronika, meble, materiały budowlane, kosmetyki, zabawki, detergenty, smary albo farby. Jeśli nie należysz do pierwszych fal, i tak warto uporządkować dane już teraz.
## 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)
Możesz włączyć dostawców, aby wzmocnić narrację radykalnej transparentności, ale najpierw uzgodnij to ze swoimi zakupami i prawnikami: to informacja wrażliwa kontraktowo.
### 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)
Komponenty zapisywane są przez AJAX: każde dodanie albo usunięcie jest natychmiastowe, bez przeładowania strony. Produkt musi istnieć (choćby jako szkic), aby paszport mógł przyjmować komponenty.
### 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
Absolutne minimum na audyt ESPR: produkcja początkowa i sprzedaż. Najlepiej udokumentuj też etapy kontroli jakości i dystrybucji. Zdarzenia posprzedażowe (naprawa, recykling) może dopisywać na bieżąco zewnętrzny partner przez REST API.
### 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).
REST API to idealny kanał do synchronizacji paszportów z PIM-a, ERP-a albo zautomatyzowanej linii produkcyjnej. Pozwala też zewnętrznemu partnerowi (warsztatowi naprawczemu, sieci recyklingu) dopisywać zdarzenia identyfikowalności w trakcie cyklu życia produktu.
## 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
Deinstalacja jest nieodwracalna: zrób kopię bazy albo eksport JSON swoich paszportów (przez REST API), jeśli chcesz później odzyskać dane.
## Wsparcie
Wsparcie techniczne prowadzone jest e-mailem po francusku i angielsku. Napisz na [support@datafirefly.com](mailto:support@datafirefly.com), podając wersję wtyczki, wersję WordPressa i WooCommerce oraz fragment logów, jeśli masz komunikat błędu PHP.