Daugumoje straipsnių apie ES skaitmeninį produkto pasą (DPP) paaiškinama, ką turi turėti pasas. Kur kas mažiau paaiškina, kaip jį sukurti — ir beveik nė vienas neparodo, kaip tai padaryti 500 ar 50 000 SKU katalogui, nespaudant formos 50 000 kartų.
Šis vadovas yra kūrėjams skirta versija. Kiekvienas toliau pateiktas žingsnis yra realus, veikiantis užklausimas į qr3.app API (https://qr3.app/v1). Jei produktų duomenis tvarkote ERP, PIM sistemoje ar duomenų bazėje, DPP generavimą galite tiesiogiai integruoti į esamą savo procesą.
Kodėl DPP atveju svarbus API
Skaitmeninis produkto pasas nėra vienkartinis dokumentas. Pagal Tvarių produktų ekologinio projektavimo reglamentą (ESPR, ES 2024/1781) ir ES baterijų reglamentą 2023/1542 kiekvienam reguliuojamam vienetui reikalingas pasas, kuris išliktų aktualus per visą jo gyvavimo laikotarpį. Gamintojui tai reiškia:
- Mastas — nuo šimtų iki dešimčių tūkstančių produktų, kiekvienas su savo GTIN/serijos numeriu.
- Aktualumas — duomenys (anglies pėdsakas, perdirbtų medžiagų kiekis, remonto informacija) keičiasi ir turi būti atnaujinami, o ne kuriami iš naujo.
- Integracija — tiesos šaltinis yra jūsų ERP/PIM, o ne žiniatinklio forma.
Tai yra API uždavinys. Rankinis žiniatinklio įrankis duos jums pirmuosius dešimt pasų; API duos visus.
1. Autentifikacija
Kiekvienoje užklausoje naudojamas bearer žetonas (API raktą sukurkite valdymo skydelyje). Bazinis URL adresas yra https://qr3.app/v1.
curl https://qr3.app/v1/dpp \
-H "Authorization: Bearer $QR3_API_KEY"
Arba su oficialiu SDK:
import { QR3 } from "@qr3/sdk";
const client = new QR3({ apiKey: process.env.QR3_API_KEY! });
2. Sukurkite baterijos pasą
DPP sukuriamas su POST /dpp. Aukščiausio lygio laukai yra vienodi kiekvienai kategorijai; konkrečiai kategorijai būdingi duomenys patenka į battery_data, textile_data arba 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"]
}
}'
Tas pats užklausimas su 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
Atsakymas apima vartotojui skirtą nukreipimo puslapį (lokalizuotą į 25 ES kalbas) ir spausdinti etiketei paruoštą GS1 Digital Link QR kodą — atskiro QR žingsnio nereikia.
3. Validuokite prieš kurdami
Norite aptikti trūkstamus ar netinkamus laukus prieš įrašydami? POST /dpp/validate paleidžia tiksliai tas pačias ES validavimo taisykles nieko nesukurdamas. Idealiai tinka kaip patikra prieš įsipareigojant CI procese.
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. Paketinis viso katalogo kūrimas
Produktų katalogui siųskite iki 100 pasų vienoje užklausoje į POST /dpp/batch. Pereikite per savo ERP eksportą ciklu ir per kelias minutes turėsite visą savo asortimentą.
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. Gaukite QR kodą etiketei spausdinti
Kiekvienas pasas pateikia savo GS1 Digital Link QR keturiais spausdinimo formatais. Gaukite juos per paso objektą arba tiesiogiai:
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 ir qr.eps — visi prieinami: SVG/EPS jūsų etikečių spausdintuvui, PNG žiniatinkliui.
6. Palaikykite duomenis aktualius (nesugadindami QR)
GTIN/serijos numeris/partija po sukūrimo yra nekintami — tai amžinai išlaiko stabilų atspausdintą GS1 URI. Visa kita galima atnaujinti su 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,
},
});
QR ant fizinio produkto niekada nesikeičia; už jo esantys duomenys keičiasi. Tai ir yra visa dinaminio paso esmė.
7. Pateikimas į ES registrą
Kai ES centrinis DPP registras yra aktualus jūsų produktui, pateikite pasą viena užklausa (Business planas ir aukštesni):
const reg = await client.dpp.registerForEuRegistry(passport.id);
console.log(reg.data.eu_registry_status); // "pending"
console.log(reg.data.registry_request_id);
8. Reaguokite į nuskaitymus su webhook'ais
DPP nuskaitymai yra įvykiai. Užsiprenumeruokite qr.scanned ir galėsite juos realiuoju laiku perduoti į savo analitiką, suaktyvinti pakartotinius užsakymus arba pažymėti atšaukimą. Naudingosios apkrovos yra pasirašytos (HMAC-SHA256); visada patikrinkite parašą.
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);
});
Viską sudėjus į vietą: DPP generavimas CI procese
Galutinė būsena, kurios nori dauguma gamintojų: produktų duomenys gyvuoja ERP/PIM, o suplanuota užduotis nuolat sinchronizuoja pasus.
- Eksportuokite pasikeitusius produktus iš savo ERP.
client.dpp.validate(...)kiekvieną iš jų — nutraukite kūrimą, jei yra validavimo klaidų.client.dpp.batch(...)naujus produktus;client.dpp.update(...)pasikeitusius.- Perduokite grąžintus
qr.svgURL adresus į savo etikečių spausdinimo sistemą.
Jokios žiniatinklio formos, jokio kopijavimo-įklijavimo, jokio neatitikimo tarp jūsų pagrindinių duomenų ir pasų.
DUK
Ar man reikia atskiro QR kodų įrankio? Ne. Kiekvienas DPP grąžina GS1 Digital Link QR formatu SVG/PNG/PDF/EPS. QR yra prieigos prie paso taškas.
Ar galiu atnaujinti pasą po to, kai etiketė atspausdinta?
Taip — tai yra pagrindinė idėja. GTIN/serijos numeris yra nekintami, todėl atspausdintas URI lieka galiojantis; visus duomenų laukus galima atnaujinti per PUT /dpp/{id}.
Kiek pasų galiu sukurti vienu metu?
Iki 100 vienoje POST /dpp/batch užklausoje. Didesnius katalogus skaidykite dalimis; pagal planą taikomi spartos apribojimai.
Kurios kategorijos palaikomos?
battery ir textile šiandien pateikiamos su visu ES validavimu; general apima kitus produktų tipus. Baterijos ir tekstilė apima realaus laiko ES atitikties patikrą (ESPR / AGEC).
Šaltiniai
Pradėkite nemokamai ir sukurkite savo pirmąjį DPP per API: app.qr3.app/sign-up
