Väčšina článkov o digitálnom produktovom pase EÚ (EU DPP) vysvetľuje, čo musí pas obsahovať. Oveľa menej z nich vám ukáže, ako ho vytvoriť — a takmer žiadny vám neukáže, ako to urobiť pre katalóg 500 alebo 50 000 SKU bez toho, aby ste 50 000-krát preklikávali formulár.
Tento návod je verziou pre vývojárov. Každý krok nižšie je reálne, funkčné volanie API qr3.app (https://qr3.app/v1). Ak spravujete produktové dáta v ERP, PIM alebo databáze, môžete generovanie DPP zapojiť priamo do svojho existujúceho pipeline.
Prečo na DPP záleží API
Digitálny produktový pas nie je jednorazový dokument. Podľa nariadenia o ekodizajne pre udržateľné produkty (ESPR, EU 2024/1781) a nariadenia EÚ o batériách 2023/1542 potrebuje každá regulovaná jednotka pas, ktorý zostáva aktuálny po celú dobu svojej životnosti. Pre výrobcu to znamená:
- Škálovanie — stovky až desaťtisíce produktov, každý s vlastným GTIN/sériovým číslom.
- Aktuálnosť — dáta (uhlíková stopa, podiel recyklovaného materiálu, informácie o oprave) sa menia a musia sa aktualizovať, nie vytvárať nanovo.
- Integrácia — zdrojom pravdy je vaše ERP/PIM, nie webový formulár.
To je problém pre API. Manuálny webový nástroj vám dá prvých desať pasov; API vám dá všetky.
1. Autentifikácia
Každá požiadavka používa bearer token (vytvorte si API kľúč v dashboarde). Základná URL je https://qr3.app/v1.
curl https://qr3.app/v1/dpp \
-H "Authorization: Bearer $QR3_API_KEY"
Alebo pomocou oficiálneho SDK:
import { QR3 } from "@qr3/sdk";
const client = new QR3({ apiKey: process.env.QR3_API_KEY! });
2. Vytvorenie pasu pre batériu
DPP sa vytvára pomocou POST /dpp. Polia najvyššej úrovne sú rovnaké pre každú kategóriu; dáta špecifické pre kategóriu idú do battery_data, textile_data alebo 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 isté volanie pomocou 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
Odpoveď obsahuje vstupnú stránku určenú pre spotrebiteľa (lokalizovanú do 25 jazykov EÚ) a QR kód GS1 Digital Link pripravený na tlač etikiet — žiadny samostatný krok s QR nie je potrebný.
3. Validujte pred vytvorením
Chcete zachytiť chýbajúce alebo neplatné polia ešte pred uložením? POST /dpp/validate spustí presne tie isté validačné pravidlá EÚ bez toho, aby čokoľvek vytvoril. Ideálne ako pre-commit kontrola 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é vytvorenie celého katalógu
Pre produktový katalóg odošlite až 100 pasov na požiadavku na POST /dpp/batch. Prejdite cyklom cez svoj export z ERP a celý svoj sortiment máte za pár minút.
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ískanie QR kódu na tlač etikiet
Každý pas sprístupňuje svoj QR kód GS1 Digital Link v štyroch tlačových formátoch. Získajte ich cez objekt pasu alebo priamo:
curl https://qr3.app/v1/dpp/dpp_xxxxxxxx/qr.svg \
-H "Authorization: Bearer $QR3_API_KEY" -o label.svg
K dispozícii sú qr.svg, qr.png, qr.pdf aj qr.eps — SVG/EPS pre vašu tlačiareň etikiet, PNG pre web.
6. Udržiavanie dát aktuálnych (bez narušenia QR)
GTIN/sériové číslo/šarža sú po vytvorení nemenné — vďaka tomu zostáva vytlačená GS1 URI navždy stabilná. Všetko ostatné možno aktualizovať pomocou 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 fyzickom produkte sa nikdy nemení; dáta za ním áno. To je celý zmysel dynamického pasu.
7. Odoslanie do registra EÚ
Keď je centrálny register DPP EÚ relevantný pre váš produkt, odošlite pas jediným volaním (plán Business a vyššie):
const reg = await client.dpp.registerForEuRegistry(passport.id);
console.log(reg.data.eu_registry_status); // "pending"
console.log(reg.data.registry_request_id);
8. Reagovanie na skenovania pomocou webhookov
Skenovania DPP sú udalosti. Prihláste sa na odber qr.scanned a môžete ich streamovať do svojej analytiky, spúšťať doobjednávky alebo označiť stiahnutie z trhu — v reálnom čase. Payloady sú podpísané (HMAC-SHA256); vždy overte 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);
});
Poskladané dohromady: generovanie DPP v CI
Cieľový stav, ktorý chce väčšina výrobcov: produktové dáta žijú v ERP/PIM a naplánovaná úloha udržiava pasy synchronizované.
- Exportujte zmenené produkty zo svojho ERP.
client.dpp.validate(...)každý z nich — pri validačných chybách nechajte zlyhať build.client.dpp.batch(...)pre nové produkty;client.dpp.update(...)pre zmenené.- Pošlite vrátené URL adresy
qr.svgdo svojho systému tlače etikiet.
Žiadny webový formulár, žiadne kopírovanie a vkladanie, žiadny rozkol medzi vašimi kmeňovými dátami a vašimi pasmi.
FAQ
Potrebujem samostatný nástroj na QR kódy? Nie. Každý DPP vracia QR kód GS1 Digital Link vo formátoch SVG/PNG/PDF/EPS. QR je prístupovým bodom k pasu.
Môžem pas aktualizovať aj potom, čo je etiketa vytlačená?
Áno — to je základná myšlienka. GTIN/sériové číslo sú nemenné, takže vytlačená URI zostáva platná; všetky dátové polia sú aktualizovateľné cez PUT /dpp/{id}.
Koľko pasov môžem vytvoriť naraz?
Až 100 na požiadavku POST /dpp/batch. Väčšie katalógy rozdeľte na časti; rate limity platia podľa plánu.
Ktoré kategórie sú podporované?
battery a textile dnes prichádzajú s plnou validáciou EÚ; general pokrýva ostatné typy produktov. Batéria a textil zahŕňajú živú kontrolu súladu s EÚ (ESPR / AGEC).
Zdroje
Začnite zadarmo a vytvorte svoj prvý DPP cez API: app.qr3.app/sign-up
