--- title: "Generowanie unijnych cyfrowych paszportów produktów przez API — qr3.app Blog" description: "Większość poradników o DPP mówi, co paszport musi zawierać. Ten pokazuje, jak programowo tworzyć zgodne z UE cyfrowe paszporty produktów — z curl, SDK qr3, tworzeniem wsadowym, walidacją, kodami QR GS1 i webhookami." canonical: "https://qr3.app/pl/blog/dpp-api-generate-passports/" lang: "pl" robots: "index,follow,max-image-preview:large,max-snippet:-1" --- # Generowanie unijnych cyfrowych paszportów produktów przez API — qr3.app Blog > Większość poradników o DPP mówi, co paszport musi zawierać. Ten pokazuje, jak programowo tworzyć zgodne z UE cyfrowe paszporty produktów — z curl, SDK qr3, tworzeniem wsadowym, walidacją, kodami QR GS1 i webhookami. Canonical: [← Blog](/pl/blog/) [Poradniki](/pl/blog/category/tutorials/) 30 maja 2026 4 min czytania [Poradniki](/pl/blog/category/tutorials/) [dpp](/pl/blog/tag/dpp/)[api](/pl/blog/tag/api/)[gs1-digital-link](/pl/blog/tag/gs1-digital-link/)[developers](/pl/blog/tag/developers/)[eu-2024-1781](/pl/blog/tag/eu-2024-1781/) # Generowanie unijnych cyfrowych paszportów produktów przez API Większość poradników o DPP mówi, co paszport musi zawierać. Ten pokazuje, jak programowo tworzyć zgodne z UE cyfrowe paszporty produktów — z curl, SDK qr3, tworzeniem wsadowym, walidacją, kodami QR GS1 i webhookami. autor: **QR3 Redaktion** ![Generowanie unijnych cyfrowych paszportów produktów przez API](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/dpp-api-generate-passports/hero.png) Większość artykułów o unijnym cyfrowym paszporcie produktu (EU DPP) wyjaśnia, *co* paszport musi zawierać. Znacznie mniej z nich pokazuje, *jak* go utworzyć — a niemal żaden nie pokazuje, jak zrobić to dla katalogu liczącego 500 lub 50 000 SKU bez przeklikiwania się przez formularz 50 000 razy. To jest wersja dla deweloperów. Każdy poniższy krok to prawdziwe, działające wywołanie API qr3.app (`https://qr3.app/v1`). Jeśli zarządzasz danymi produktowymi w systemie ERP, PIM lub bazie danych, możesz wpiąć generowanie DPP bezpośrednio w swój istniejący pipeline. ## Dlaczego API ma znaczenie dla DPP Cyfrowy paszport produktu nie jest jednorazowym dokumentem. Na mocy [rozporządzenia w sprawie ekoprojektu dla zrównoważonych produktów (ESPR, EU 2024/1781)](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R1781) oraz [unijnego rozporządzenia bateryjnego 2023/1542](https://eur-lex.europa.eu/eli/reg/2023/1542/oj) każda regulowana jednostka potrzebuje paszportu, który pozostaje aktualny przez cały okres jej życia. Dla producenta oznacza to: - **Skalę** — od setek do dziesiątek tysięcy produktów, każdy z własnym GTIN/numerem seryjnym. - **Aktualność** — dane (ślad węglowy, zawartość materiałów z recyklingu, informacje o naprawie) zmieniają się i muszą być aktualizowane, a nie tworzone od nowa. - **Integrację** — źródłem prawdy jest Twój ERP/PIM, a nie formularz internetowy. To jest problem dla API. Ręczne narzędzie internetowe da Ci pierwszych dziesięć paszportów; API da Ci je wszystkie. ## 1. Uwierzytelnianie Każde żądanie używa tokena bearer (utwórz klucz API w panelu). Bazowy adres URL to `https://qr3.app/v1`. ``` curl https://qr3.app/v1/dpp \ -H "Authorization: Bearer $QR3_API_KEY" ``` Lub z oficjalnym SDK: ``` import { QR3 } from "@qr3/sdk"; const client = new QR3({ apiKey: process.env.QR3_API_KEY! }); ``` ## 2. Utwórz paszport baterii DPP tworzy się za pomocą `POST /dpp`. Pola najwyższego poziomu są takie same dla każdej kategorii; dane specyficzne dla kategorii trafiają do `battery_data`, `textile_data` lub `general_data`. ``` curl -X POST https://qr3.app/v1/dpp \ -H "Authorization: Bearer $QR3_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "gtin": "09506000134376", "serial": "SN-00012345", "product_name": "PowerCell 5 kWh LFP", "manufacturer": "ExampleTech GmbH", "origin_country": "DE", "category": "battery", "market_countries": ["DE", "FR", "AT"], "status": "live", "battery_data": { "capacity_kwh": 5, "carbon_footprint_kg": 62, "carbon_footprint_class": "B", "recycled_content_pct": 12, "recyclability_pct": 95, "manufacturer_warranty_years": 8, "lithium_content_pct": 6.5, "certifications": ["CE", "UN38.3"] } }' ``` To samo wywołanie z SDK: ``` const passport = await client.dpp.create({ gtin: "09506000134376", serial: "SN-00012345", product_name: "PowerCell 5 kWh LFP", manufacturer: "ExampleTech GmbH", origin_country: "DE", category: "battery", market_countries: ["DE", "FR", "AT"], battery_data: { capacity_kwh: 5, carbon_footprint_kg: 62, recycled_content_pct: 12, recyclability_pct: 95, manufacturer_warranty_years: 8, }, }); console.log(passport.id); // dpp_xxxxxxxx console.log(passport.qr.svg); // print-ready GS1 Digital Link QR ``` Odpowiedź zawiera stronę docelową skierowaną do konsumenta (zlokalizowaną w 25 językach UE) oraz kod QR **GS1 Digital Link** gotowy do druku na etykiecie — bez osobnego kroku generowania QR. ## 3. Waliduj, zanim utworzysz Chcesz wychwycić brakujące lub nieprawidłowe pola przed zapisem? `POST /dpp/validate` uruchamia dokładnie te same reguły walidacji UE bez tworzenia czegokolwiek. Idealne jako kontrola pre-commit w CI. ``` const result = await client.dpp.validate({ gtin: "09506000134376", product_name: "PowerCell 5 kWh LFP", manufacturer: "ExampleTech GmbH", origin_country: "DE", category: "battery", battery_data: { capacity_kwh: 5, carbon_footprint_kg: 62, recycled_content_pct: 12, recyclability_pct: 95, manufacturer_warranty_years: 8, }, }); if (!result.valid) { console.error(result.errors); // [{ field: "battery_data.recyclability_pct", message: "..." }] } ``` ## 4. Utwórz wsadowo cały katalog Dla katalogu produktów wyślij do **100 paszportów na żądanie** do `POST /dpp/batch`. Przejdź pętlą po eksporcie z ERP i masz cały asortyment w kilka minut. ``` const items = products.map((p) => ({ gtin: p.gtin, serial: p.serial, product_name: p.name, manufacturer: "ExampleTech GmbH", origin_country: "DE", category: "battery" as const, battery_data: { capacity_kwh: p.capacityKwh, carbon_footprint_kg: p.co2Kg, recycled_content_pct: p.recycledPct, recyclability_pct: p.recyclablePct, manufacturer_warranty_years: p.warrantyYears, }, })); // Chunk into batches of 100 const result = await client.dpp.batch({ items: items.slice(0, 100) }); ``` ## 5. Pobierz kod QR do druku etykiet Każdy paszport udostępnia swój kod QR GS1 Digital Link w czterech formatach do druku. Pobierz je przez obiekt paszportu lub bezpośrednio: ``` curl https://qr3.app/v1/dpp/dpp_xxxxxxxx/qr.svg \ -H "Authorization: Bearer $QR3_API_KEY" -o label.svg ``` `qr.svg`, `qr.png`, `qr.pdf` oraz `qr.eps` są wszystkie dostępne — SVG/EPS dla Twojej drukarki etykiet, PNG dla sieci. ## 6. Utrzymuj dane aktualne (bez psucia kodu QR) GTIN/numer seryjny/partia są **niezmienne** po utworzeniu — dzięki temu wydrukowany URI GS1 pozostaje stabilny na zawsze. Wszystko inne można zaktualizować za pomocą `PUT /dpp/{id}`: ``` await client.dpp.update(passport.id, { battery_data: { capacity_kwh: 5, carbon_footprint_kg: 58, // re-measured, lower footprint recycled_content_pct: 16, // 2031 target reached early recyclability_pct: 95, manufacturer_warranty_years: 8, }, }); ``` Kod QR na fizycznym produkcie nigdy się nie zmienia; dane stojące za nim — owszem. Na tym właśnie polega cały sens *dynamicznego* paszportu. ## 7. Prześlij do rejestru UE Gdy centralny rejestr DPP UE obejmuje Twój produkt, prześlij paszport jednym wywołaniem (plan Business i wyższe): ``` const reg = await client.dpp.registerForEuRegistry(passport.id); console.log(reg.data.eu_registry_status); // "pending" console.log(reg.data.registry_request_id); ``` > **Stan na dziś:** UE nie opublikowała jeszcze API swojego centralnego rejestru DPP. Do tego czasu to wywołanie jest ścieżką testową — status pozostaje `pending`, a żaden urząd nie otrzyma paszportu. Gdy tylko API będzie aktywne, to samo wywołanie stanie się rzeczywistą rejestracją. ## 8. Reaguj na skany za pomocą webhooków Skany DPP to zdarzenia. Zasubskrybuj `qr.scanned`, a będziesz mógł przesyłać je strumieniowo do swojej analityki, wyzwalać ponowne zamówienia lub oznaczać wycofanie produktu — w czasie rzeczywistym. Ładunki są podpisane (HMAC-SHA256); zawsze weryfikuj podpis. ``` import { createHmac, timingSafeEqual } from "crypto"; app.post("/webhooks/qr3", express.raw({ type: "application/json" }), (req, res) => { const expected = createHmac("sha256", secret).update(req.body).digest("hex"); const expectedBytes = Buffer.from(`sha256=${expected}`); const receivedBytes = Buffer.from(String(req.headers["x-qr3-signature"] ?? "")); const ok = expectedBytes.length === receivedBytes.length && timingSafeEqual(expectedBytes, receivedBytes); if (!ok) return res.sendStatus(401); const event = JSON.parse(req.body.toString("utf8")); if (event.type === "qr.scanned") { console.log(event.data.country, event.data.dpp_id); } res.sendStatus(200); }); ``` ## Wszystko razem: generowanie DPP w CI Stan docelowy, którego chce większość producentów: dane produktowe znajdują się w ERP/PIM, a zaplanowane zadanie utrzymuje paszporty w synchronizacji. 1. Wyeksportuj zmienione produkty ze swojego ERP. 2. `client.dpp.validate(...)` dla każdego z nich — przerwij build przy błędach walidacji. 3. `client.dpp.batch(...)` dla nowych produktów; `client.dpp.update(...)` dla zmienionych. 4. Wypchnij zwrócone adresy URL `qr.svg` do swojego systemu druku etykiet. Żadnego formularza internetowego, żadnego kopiuj-wklej, żadnej rozbieżności między Twoimi danymi podstawowymi a paszportami. ## FAQ **Czy potrzebuję osobnego narzędzia do kodów QR?** Nie. Każdy DPP zwraca kod QR GS1 Digital Link w formacie SVG/PNG/PDF/EPS. Kod QR *jest* punktem dostępu do paszportu. **Czy mogę zaktualizować paszport po wydrukowaniu etykiety?** Tak — to jest sedno idei. GTIN/numer seryjny są niezmienne, więc wydrukowany URI pozostaje ważny; wszystkie pola danych można aktualizować przez `PUT /dpp/{id}`. **Ile paszportów mogę utworzyć naraz?** Do 100 na zapytanie `POST /dpp/batch`. Większe katalogi dziel na fragmenty; obowiązuje limit 60 zapytań na minutę na klucz API, w każdym planie. **Które kategorie są obsługiwane?** `battery` i `textile` mają dziś pełną walidację UE; `general` obejmuje inne typy produktów. Battery i textile zawierają aktywne sprawdzenie zgodności z UE (ESPR / AGEC). ## Źródła - [ESPR — rozporządzenie (UE) 2024/1781](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R1781) - [Unijne rozporządzenie bateryjne 2023/1542](https://eur-lex.europa.eu/eli/reg/2023/1542/oj) - [GS1 Digital Link](https://www.gs1.org/standards/gs1-digital-link) **Zacznij za darmo** i utwórz swój pierwszy DPP przez API: [app.qr3.app/sign-up](https://app.qr3.app/sign-up) ## Powiązane artykuły - [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/gs1-resolver-test-suite-dpp-links/hero.png) Poradniki Pakiet testów Resolvera GS1: DPP-Linki — rzetelna weryfikacja przed uruchomieniem produkcyjnym Stabilny pakiet testów GS1 umożliwia weryfikację Resolvera 1.2. Sprawdź przekierowania, zestawy linków, CORS, języki i przypadki błędów przed uruchomieniem produkcyjnym.](/pl/blog/gs1-resolver-test-suite-dpp-links/) - [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/dpp-battery-passport-2027-20260715/hero.png) Wiadomości branżowe BatteryPass-Ready uruchamia środowisko testowe dla Cyfrowego Paszportu Baterii Konsorcjum BatteryPass-Ready uruchomiło 24 czerwca 2026 r. publiczne środowisko testowe dla Cyfrowego Paszportu Baterii, z myślą o obowiązku UE od lutego 2027 r.](/pl/blog/dpp-battery-passport-2027-20260715/) - [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/sector-20260713/hero.png) Wiadomości branżowe Cyfrowy paszport baterii 2027: co producenci muszą wiedzieć już teraz Webinary, narzędzia open source i nowe normy: unijny paszport baterii nabiera tempa. Przegląd sytuacji w lipcu 2026 r. i otwartych kwestii do lutego 2027 r.](/pl/blog/sector-20260713/) - [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/sector-20260711/hero.png) Wiadomości branżowe Cyfrowy paszport baterii 2026: środowiska testowe, normy i otwarte pytania Jak przemysł radzi sobie z Cyfrowym Paszportem Baterii? Przegląd środowisk testowych, norm CEN/CENELEC, narzędzi open source i zmian regulacyjnych w lipcu 2026 r.](/pl/blog/sector-20260711/) [← Wszystkie artykuły](/pl/blog/) [Zacznij za darmo](https://app.qr3.app/sign-up)