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) oraz unijnego rozporządzenia bateryjnego 2023/1542 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);
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 { verifyWebhook } from "@qr3/sdk";
app.post("/webhooks/qr3", async (req, res) => {
const event = verifyWebhook(req.body, req.headers["qr3-signature"], secret);
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.
- Wyeksportuj zmienione produkty ze swojego ERP.
client.dpp.validate(...)dla każdego z nich — przerwij build przy błędach walidacji.client.dpp.batch(...)dla nowych produktów;client.dpp.update(...)dla zmienionych.- Wypchnij zwrócone adresy URL
qr.svgdo 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 żądanie POST /dpp/batch. Większe katalogi dziel na fragmenty; limity zapytań obowiązują w zależności od planu.
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
Zacznij za darmo i utwórz swój pierwszy DPP przez API: app.qr3.app/sign-up
