Повечето статии за цифровия продуктов паспорт на ЕС (DPP) обясняват какво трябва да съдържа един паспорт. Далеч по-малко показват как да създадете такъв — и почти нито една не показва как да го направите за каталог от 500 или 50 000 SKU-та, без да щраквате през формуляр 50 000 пъти.
Това ръководство е версията за разработчици. Всяка стъпка по-долу е реално, работещо извикване към API на qr3.app (https://qr3.app/v1). Ако управлявате продуктови данни в ERP, в PIM или в база данни, можете да вградите генерирането на DPP директно в съществуващия си процес.
Защо API е важен за DPP-тата
Цифровият продуктов паспорт не е еднократен документ. Съгласно Регламента за екодизайн на устойчиви продукти (ESPR, ЕС 2024/1781) и Регламента на ЕС за батериите 2023/1542 всяка регулирана единица се нуждае от паспорт, който остава актуален през целия си жизнен цикъл. За един производител това означава:
- Мащаб — стотици до десетки хиляди продукти, всеки със собствен GTIN/сериен номер.
- Актуалност — данните (въглеродeн отпечатък, рециклирано съдържание, информация за ремонт) се променят и трябва да бъдат актуализирани, а не пресъздадени.
- Интеграция — източникът на истина е вашият ERP/PIM, а не уеб формуляр.
Това е проблем за API. Един ръчен уеб инструмент ви осигурява първите десет паспорта; един API ви осигурява всичките.
1. Удостоверяване
Всяка заявка използва bearer токен (създайте API ключ в таблото за управление). Базовият URL е https://qr3.app/v1.
curl https://qr3.app/v1/dpp \
-H "Authorization: Bearer $QR3_API_KEY"
Или с официалния SDK:
import { QR3 } from "@qr3/sdk";
const client = new QR3({ apiKey: process.env.QR3_API_KEY! });
2. Създаване на паспорт за батерия
DPP се създава с POST /dpp. Полетата от най-високо ниво са едни и същи за всяка категория; специфичните за категорията данни отиват в battery_data, textile_data или 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"]
}
}'
Същото извикване със 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
Отговорът включва насочена към потребителите landing страница (локализирана на 25 езика на ЕС) и QR код GS1 Digital Link, готов за печат на етикети — не е необходима отделна стъпка за QR.
3. Валидирайте, преди да създавате
Искате да уловите липсващи или невалидни полета, преди да запишете данните? POST /dpp/validate изпълнява точно същите правила за валидиране на ЕС, без да създава нищо. Идеален като предварителна проверка преди commit в 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. Групово създаване на цял каталог
За продуктов каталог изпратете до 100 паспорта на заявка към POST /dpp/batch. Преминете в цикъл през експорта от вашия ERP и целият ви асортимент е готов за минути.
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. Вземане на QR кода за печат на етикети
Всеки паспорт предоставя своя GS1 Digital Link QR в четири формата за печат. Изтеглете ги чрез обекта на паспорта или директно:
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 и qr.eps са налични — SVG/EPS за вашия принтер за етикети, PNG за уеб.
6. Поддържане на данните актуални (без да нарушавате QR кода)
GTIN/серийният номер/партидата са непроменими след създаването — това поддържа отпечатания GS1 URI стабилен завинаги. Всичко останало може да бъде актуализирано с 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 кодът върху физическия продукт никога не се променя; данните зад него — да. Това е целият смисъл на един динамичен паспорт.
7. Подаване в регистъра на ЕС
Когато централният регистър за DPP на ЕС е приложим за вашия продукт, подайте паспорт с едно извикване (план Business и нагоре):
const reg = await client.dpp.registerForEuRegistry(passport.id);
console.log(reg.data.eu_registry_status); // "pending"
console.log(reg.data.registry_request_id);
8. Реагиране на сканирания с webhook-ове
Сканиранията на DPP са събития. Абонирайте се за qr.scanned и можете да ги предавате към вашата аналитика, да задействате повторни поръчки или да маркирате изтегляне от пазара — в реално време. Полезните товари са подписани (HMAC-SHA256); винаги проверявайте подписа.
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);
});
Сглобяване на всичко: генериране на DPP в CI
Крайното състояние, което повечето производители искат: продуктовите данни се намират в ERP/PIM, а планирана задача поддържа паспортите синхронизирани.
- Експортирайте променените продукти от вашия ERP.
client.dpp.validate(...)за всеки от тях — провалете билда при грешки във валидирането.client.dpp.batch(...)за новите продукти;client.dpp.update(...)за променените.- Изпратете върнатите URL адреси на
qr.svgкъм вашата система за печат на етикети.
Без уеб формуляр, без копиране и поставяне, без разминаване между вашите основни данни и вашите паспорти.
Често задавани въпроси
Нуждая ли се от отделен инструмент за QR кодове? Не. Всеки DPP връща GS1 Digital Link QR в SVG/PNG/PDF/EPS. QR кодът е точката за достъп до паспорта.
Мога ли да актуализирам паспорт, след като етикетът е отпечатан?
Да — това е основната идея. GTIN/серийният номер са непроменими, така че отпечатаният URI остава валиден; всички полета с данни могат да се актуализират чрез PUT /dpp/{id}.
Колко паспорта мога да създам наведнъж?
До 100 на заявка POST /dpp/batch. Разделяйте по-големите каталози; ограниченията на скоростта се прилагат според плана.
Кои категории се поддържат?
battery и textile се предлагат с пълно валидиране за ЕС днес; general покрива други видове продукти. Battery и textile включват жива проверка за съответствие с ЕС (ESPR / AGEC).
Източници
Започнете безплатно и създайте първия си DPP чрез API: app.qr3.app/sign-up
