Az EU digitális termékútleveléről (DPP) szóló cikkek többsége azt magyarázza el, mit kell tartalmaznia egy útlevélnek. Sokkal kevesebb mutatja meg, hogyan hozz létre egyet — és szinte egyik sem mutatja meg, hogyan tedd ezt 500 vagy 50 000 SKU-ból álló katalógus esetében anélkül, hogy 50 000-szer kellene végigkattintanod egy űrlapon.
Ez az útmutató a fejlesztői változat. Az alábbi minden lépés egy valódi, működő hívás a qr3.app API-jával szemben (https://qr3.app/v1). Ha egy ERP-ben, egy PIM-ben vagy egy adatbázisban kezeled a termékadatokat, a DPP-generálást közvetlenül beépítheted a meglévő folyamatodba.
Miért fontos az API a DPP-knél
A digitális termékútlevél nem egyszeri dokumentum. A fenntartható termékek környezetbarát tervezéséről szóló rendelet (ESPR, EU 2024/1781) és az EU akkumulátor-rendelet 2023/1542 értelmében minden szabályozott egységnek olyan útlevélre van szüksége, amely a teljes élettartama alatt naprakész marad. Egy gyártó számára ez a következőket jelenti:
- Méretezhetőség — több száztól több tízezer termékig, mindegyik saját GTIN/sorozatszámmal.
- Naprakészség — az adatok (szénlábnyom, újrahasznosított tartalom, javítási információk) változnak, és frissíteni kell őket, nem újból létrehozni.
- Integráció — az igazság forrása az ERP/PIM, nem egy webes űrlap.
Ez egy API-feladat. Egy manuális webes eszközzel megvan az első tíz útleveled; egy API-val mindegyik megvan.
1. Hitelesítés
Minden kérés bearer tokent használ (hozz létre egy API-kulcsot a vezérlőpulton). Az alap-URL https://qr3.app/v1.
curl https://qr3.app/v1/dpp \
-H "Authorization: Bearer $QR3_API_KEY"
Vagy a hivatalos SDK-val:
import { QR3 } from "@qr3/sdk";
const client = new QR3({ apiKey: process.env.QR3_API_KEY! });
2. Akkumulátor-útlevél létrehozása
Egy DPP-t a POST /dpp hívással hozhatsz létre. A felső szintű mezők minden kategóriánál azonosak; a kategória-specifikus adatok a battery_data, textile_data vagy general_data mezőkbe kerülnek.
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"]
}
}'
Ugyanez a hívás az SDK-val:
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
A válasz tartalmaz egy fogyasztóknak szóló céloldalt (25 EU-nyelvre lokalizálva) és egy nyomtatásra kész, címkenyomtatáshoz használható GS1 Digital Link QR-kódot — külön QR-lépésre nincs szükség.
3. Validálj a létrehozás előtt
Szeretnéd a hiányzó vagy érvénytelen mezőket még a tárolás előtt elkapni? A POST /dpp/validate pontosan ugyanazokat az EU-validálási szabályokat futtatja le anélkül, hogy bármit is létrehozna. Ideális előzetes ellenőrzésként a CI-ban.
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. Kötegelt létrehozás egy teljes katalógushoz
Egy termékkatalógushoz kérésenként akár 100 útlevelet is küldhetsz a POST /dpp/batch végpontra. Iterálj végig az ERP-exportodon, és perceken belül megvan a teljes termékkínálatod.
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. A QR-kód lekérése címkenyomtatáshoz
Minden útlevél négy nyomtatási formátumban teszi elérhetővé a GS1 Digital Link QR-kódját. Lekérheted őket az útlevélobjektumon keresztül vagy közvetlenül:
curl https://qr3.app/v1/dpp/dpp_xxxxxxxx/qr.svg \
-H "Authorization: Bearer $QR3_API_KEY" -o label.svg
A qr.svg, qr.png, qr.pdf és qr.eps mind elérhető — SVG/EPS a címkenyomtatódhoz, PNG a webre.
6. Tartsd naprakészen az adatokat (a QR-kód feltörése nélkül)
A GTIN/sorozatszám/tétel a létrehozás után megváltoztathatatlan — ez örökre stabilan tartja a nyomtatott GS1 URI-t. Minden más frissíthető a PUT /dpp/{id} hívással:
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,
},
});
A fizikai terméken lévő QR-kód soha nem változik; a mögötte lévő adat viszont igen. Pontosan ez a dinamikus útlevél lényege.
7. Beküldés az EU-nyilvántartásba
Amikor a központi EU DPP-nyilvántartás a termékedre vonatkozik, egyetlen hívással beküldhetsz egy útlevelet (Business csomagtól felfelé):
const reg = await client.dpp.registerForEuRegistry(passport.id);
console.log(reg.data.eu_registry_status); // "pending"
console.log(reg.data.registry_request_id);
8. Reagálj a beolvasásokra webhookokkal
A DPP-beolvasások események. Iratkozz fel a qr.scanned eseményre, és valós időben streamelheted őket az analitikádba, indíthatsz utánrendeléseket, vagy jelölhetsz meg egy visszahívást. A payloadok aláírtak (HMAC-SHA256); mindig ellenőrizd az aláírást.
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);
});
Mindent összerakva: DPP-generálás a CI-ban
A legtöbb gyártó által kívánt végállapot: a termékadatok az ERP/PIM-ben élnek, és egy ütemezett feladat tartja szinkronban az útleveleket.
- Exportáld a megváltozott termékeket az ERP-edből.
client.dpp.validate(...)mindegyikre — buktasd el a buildet validálási hibák esetén.client.dpp.batch(...)az új termékekre;client.dpp.update(...)a megváltozottakra.- Küldd a visszakapott
qr.svgURL-eket a címkenyomtató rendszeredbe.
Nincs webes űrlap, nincs másol-beilleszt, nincs eltérés a törzsadataid és az útleveleid között.
GYIK
Szükségem van külön QR-kód eszközre? Nem. Minden DPP egy GS1 Digital Link QR-kódot ad vissza SVG/PNG/PDF/EPS formátumban. A QR-kód maga az útlevélhez vezető hozzáférési pont.
Frissíthetek egy útlevelet a címke kinyomtatása után?
Igen — ez a lényeg. A GTIN/sorozatszám megváltoztathatatlan, így a nyomtatott URI érvényes marad; minden adatmező frissíthető a PUT /dpp/{id} hívással.
Hány útlevelet hozhatok létre egyszerre?
POST /dpp/batch kérésenként akár 100-at. Darabold fel a nagyobb katalógusokat; a rate limitek csomagonként érvényesek.
Mely kategóriák támogatottak?
A battery és a textile ma már teljes EU-validálással érkezik; a general az egyéb terméktípusokat fedi le. Az akkumulátor és a textil tartalmaz egy élő EU-megfelelőségi ellenőrzést (ESPR / AGEC).
Források
Kezdd el ingyen, és hozd létre az első DPP-det API-n keresztül: app.qr3.app/sign-up
