Většina článků o evropském digitálním pasu produktu (EU DPP) vysvětluje, co musí pas obsahovat. Mnohem méně jich ukazuje, jak takový pas vytvořit — a téměř žádný neukazuje, jak to udělat pro katalog 500 nebo 50 000 SKU, aniž byste 50 000krát proklikávali formulář.
Tento průvodce je verzí pro vývojáře. Každý krok níže je reálné, funkční volání proti API qr3.app (https://qr3.app/v1). Pokud spravujete data o produktech v ERP, PIM nebo databázi, můžete generování DPP zapojit přímo do své stávající pipeline.
Proč na DPP záleží API
Digitální pas produktu není jednorázový dokument. Podle nařízení o ekodesignu pro udržitelné produkty (ESPR, EU 2024/1781) a nařízení EU o bateriích 2023/1542 potřebuje každá regulovaná jednotka pas, který zůstává aktuální po celou dobu své životnosti. Pro výrobce to znamená:
- Škálu — stovky až desetitisíce produktů, každý s vlastním GTIN/sériovým číslem.
- Aktuálnost — data (uhlíková stopa, podíl recyklovaného obsahu, informace o opravách) se mění a musí být aktualizována, nikoli vytvářena znovu.
- Integraci — zdrojem pravdy je vaše ERP/PIM, nikoli webový formulář.
To je problém pro API. Manuální webový nástroj vám dá prvních deset pasů; API vám dá všechny.
1. Autentizace
Každý požadavek používá bearer token (vytvořte si API klíč v nástěnce). Základní URL je https://qr3.app/v1.
curl https://qr3.app/v1/dpp \
-H "Authorization: Bearer $QR3_API_KEY"
Nebo pomocí oficiálního SDK:
import { QR3 } from "@qr3/sdk";
const client = new QR3({ apiKey: process.env.QR3_API_KEY! });
2. Vytvoření pasu baterie
DPP se vytváří pomocí POST /dpp. Pole na nejvyšší úrovni jsou stejná pro každou kategorii; data specifická pro danou kategorii se uvádějí v battery_data, textile_data nebo 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"]
}
}'
Totéž volání pomocí 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
Odpověď zahrnuje vstupní stránku pro spotřebitele (lokalizovanou do 25 jazyků EU) a QR kód GS1 Digital Link připravený k tisku na etiketu — žádný samostatný krok pro QR není potřeba.
3. Validujte před vytvořením
Chcete zachytit chybějící nebo neplatná pole ještě před uložením? POST /dpp/validate spustí přesně ta validační pravidla EU, aniž by cokoli vytvořilo. Ideální jako kontrola před commitem v 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. Hromadné vytvoření celého katalogu
Pro produktový katalog odešlete až 100 pasů na jeden požadavek na POST /dpp/batch. Projděte ve smyčce svůj export z ERP a celý sortiment máte během několika 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. Získání QR kódu pro tisk na etiketu
Každý pas zpřístupňuje svůj QR kód GS1 Digital Link ve čtyřech tiskových formátech. Stáhněte je prostřednictvím objektu pasu nebo přímo:
curl https://qr3.app/v1/dpp/dpp_xxxxxxxx/qr.svg \
-H "Authorization: Bearer $QR3_API_KEY" -o label.svg
K dispozici jsou qr.svg, qr.png, qr.pdf i qr.eps — SVG/EPS pro vaši etiketovací tiskárnu, PNG pro web.
6. Udržujte data aktuální (aniž byste rozbili QR)
GTIN/sériové číslo/šarže jsou po vytvoření neměnné — to udržuje vytištěné GS1 URI navždy stabilní. Vše ostatní lze aktualizovat 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,
},
});
QR na fyzickém produktu se nikdy nemění; data za ním ano. To je celý smysl dynamického pasu.
7. Odeslání do registru EU
Když je pro váš produkt v rozsahu centrální registr DPP EU, odešlete pas jediným voláním (plán Business a vyšší):
const reg = await client.dpp.registerForEuRegistry(passport.id);
console.log(reg.data.eu_registry_status); // "pending"
console.log(reg.data.registry_request_id);
8. Reagujte na naskenování pomocí webhooků
Naskenování DPP jsou události. Přihlaste se k odběru qr.scanned a můžete je v reálném čase přenášet do své analytiky, spouštět doobjednávky nebo signalizovat stažení z trhu. Datové zprávy jsou podepsané (HMAC-SHA256); vždy ověřte 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);
});
Spojeno dohromady: generování DPP v CI
Cílový stav, který chce většina výrobců: data o produktech žijí v ERP/PIM a naplánovaná úloha udržuje pasy synchronizované.
- Exportujte změněné produkty z vašeho ERP.
client.dpp.validate(...)u každého z nich — při validačních chybách nechte build selhat.client.dpp.batch(...)nové produkty;client.dpp.update(...)ty změněné.- Předejte vrácené URL
qr.svgsvému systému pro tisk etiket.
Žádný webový formulář, žádné kopírování a vkládání, žádný rozdíl mezi vašimi kmenovými daty a vašimi pasy.
Časté dotazy
Potřebuji samostatný nástroj pro QR kódy? Ne. Každý DPP vrací QR kód GS1 Digital Link ve formátech SVG/PNG/PDF/EPS. Tento QR je přístupovým bodem k pasu.
Mohu pas aktualizovat poté, co je etiketa vytištěna?
Ano — to je hlavní myšlenka. GTIN/sériové číslo jsou neměnné, takže vytištěné URI zůstává platné; všechna datová pole lze aktualizovat pomocí PUT /dpp/{id}.
Kolik pasů mohu vytvořit najednou?
Až 100 na jeden požadavek POST /dpp/batch. Větší katalogy rozdělte do dávek; limity četnosti platí podle plánu.
Které kategorie jsou podporovány?
battery a textile dnes přicházejí s plnou validací EU; general pokrývá ostatní typy produktů. Baterie a textil zahrnují živou kontrolu shody s předpisy EU (ESPR / AGEC).
Zdroje
Začněte zdarma a vytvořte svůj první DPP přes API: app.qr3.app/sign-up
