Većina članaka o EU digitalnoj putovnici proizvoda (DPP) objašnjava što putovnica mora sadržavati. Daleko ih manje pokazuje kako je kreirati — a gotovo nijedan ne pokazuje kako to učiniti za katalog od 500 ili 50.000 SKU-ova bez 50.000 puta ispunjavanja obrasca.
Ovaj vodič je programerska verzija. Svaki korak u nastavku stvaran je, funkcionalan poziv prema qr3.app API-ju (https://qr3.app/v1). Ako podatke o proizvodima vodite u ERP-u, PIM-u ili bazi podataka, generiranje DPP-a možete izravno povezati sa svojim postojećim procesom.
Zašto je API važan za DPP-ove
Digitalna putovnica proizvoda nije jednokratni dokument. Prema Uredbi o ekološkom dizajnu održivih proizvoda (ESPR, EU 2024/1781) i EU Uredbi o baterijama 2023/1542, svaka regulirana jedinica treba putovnicu koja ostaje ažurna tijekom cijelog svog životnog vijeka. Za proizvođača to znači:
- Razmjer — od stotina do desetaka tisuća proizvoda, svaki sa svojim GTIN-om/serijskim brojem.
- Aktualnost — podaci (ugljični otisak, udio recikliranog materijala, informacije o popravku) se mijenjaju i moraju se ažurirati, a ne iznova kreirati.
- Integracija — izvor istine je vaš ERP/PIM, a ne web obrazac.
To je problem za API. Ručni web alat dovede vas do prvih deset putovnica; API vam donosi sve.
1. Autentikacija
Svaki zahtjev koristi bearer token (kreirajte API ključ na nadzornoj ploči). Osnovni URL je https://qr3.app/v1.
curl https://qr3.app/v1/dpp \
-H "Authorization: Bearer $QR3_API_KEY"
Ili pomoću službenog SDK-a:
import { QR3 } from "@qr3/sdk";
const client = new QR3({ apiKey: process.env.QR3_API_KEY! });
2. Kreiranje putovnice za bateriju
DPP se kreira pomoću POST /dpp. Polja najviše razine ista su za svaku kategoriju; podaci specifični za kategoriju idu u battery_data, textile_data ili 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"]
}
}'
Isti poziv pomoću SDK-a:
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); // GS1 Digital Link QR spreman za ispis
Odgovor uključuje odredišnu stranicu namijenjenu potrošačima (lokaliziranu na 25 EU jezika) i GS1 Digital Link QR kod spreman za ispis naljepnica — bez zasebnog koraka za QR.
3. Validirajte prije kreiranja
Želite uhvatiti polja koja nedostaju ili su nevažeća prije pohrane? POST /dpp/validate pokreće točno ista EU pravila validacije bez kreiranja ičega. Idealno kao provjera prije commita u CI-ju.
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. Skupno kreiranje cijelog kataloga
Za katalog proizvoda pošaljite do 100 putovnica po zahtjevu na POST /dpp/batch. Prođite kroz svoj ERP izvoz i imate cijeli asortiman u nekoliko minuta.
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,
},
}));
// Podijeli u skupine po 100
const result = await client.dpp.batch({ items: items.slice(0, 100) });
5. Dohvaćanje QR koda za ispis naljepnica
Svaka putovnica izlaže svoj GS1 Digital Link QR u četiri formata za ispis. Dohvatite ih putem objekta putovnice ili izravno:
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 i qr.eps svi su dostupni — SVG/EPS za vaš pisač naljepnica, PNG za web.
6. Održavajte podatke ažurnima (bez razbijanja QR-a)
GTIN/serijski broj/lot su nepromjenjivi nakon kreiranja — time se ispisani GS1 URI zauvijek održava stabilnim. Sve ostalo može se ažurirati pomoću PUT /dpp/{id}:
await client.dpp.update(passport.id, {
battery_data: {
capacity_kwh: 5,
carbon_footprint_kg: 58, // ponovno izmjereno, manji otisak
recycled_content_pct: 16, // cilj za 2031. dostignut ranije
recyclability_pct: 95,
manufacturer_warranty_years: 8,
},
});
QR na fizičkom proizvodu nikada se ne mijenja; podaci iza njega se mijenjaju. To je cijela poanta dinamičke putovnice.
7. Predaja u EU registar
Kada je središnji EU DPP registar relevantan za vaš proizvod, predajte putovnicu jednim pozivom (Business plan i više):
const reg = await client.dpp.registerForEuRegistry(passport.id);
console.log(reg.data.eu_registry_status); // "pending"
console.log(reg.data.registry_request_id);
8. Reagirajte na skeniranja pomoću webhookova
Skeniranja DPP-a su događaji. Pretplatite se na qr.scanned i možete ih strujati u svoju analitiku, pokrenuti ponovne narudžbe ili označiti opoziv — u stvarnom vremenu. Sadržaji su potpisani (HMAC-SHA256); uvijek provjerite potpis.
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);
});
Sve zajedno: generiranje DPP-a u CI-ju
Završno stanje koje većina proizvođača želi: podaci o proizvodima žive u ERP-u/PIM-u, a zakazani posao održava putovnice usklađenima.
- Izvezite promijenjene proizvode iz svog ERP-a.
client.dpp.validate(...)za svaki — neka build padne kod pogrešaka validacije.client.dpp.batch(...)nove proizvode;client.dpp.update(...)promijenjene.- Proslijedite vraćene
qr.svgURL-ove svom sustavu za ispis naljepnica.
Bez web obrasca, bez kopiranja i lijepljenja, bez odstupanja između vaših matičnih podataka i vaših putovnica.
Često postavljana pitanja
Trebam li zaseban alat za QR kodove? Ne. Svaki DPP vraća GS1 Digital Link QR u SVG/PNG/PDF/EPS formatu. QR jest pristupna točka do putovnice.
Mogu li ažurirati putovnicu nakon što je naljepnica ispisana?
Da — to je sama srž ideje. GTIN/serijski broj su nepromjenjivi pa ispisani URI ostaje važeći; sva polja s podacima mogu se ažurirati putem PUT /dpp/{id}.
Koliko putovnica mogu kreirati odjednom?
Do 100 po POST /dpp/batch zahtjevu. Veće kataloge podijelite u skupine; ograničenja brzine primjenjuju se po planu.
Koje kategorije su podržane?
battery i textile danas dolaze s punom EU validacijom; general pokriva ostale vrste proizvoda. Baterija i tekstil uključuju aktivnu provjeru usklađenosti s EU-om (ESPR / AGEC).
Izvori
Započnite besplatno i kreirajte svoj prvi DPP putem API-ja: app.qr3.app/sign-up
