Ħafna artikli dwar il-Passaport Diġitali tal-Prodott (DPP) tal-UE jispjegaw *x'*għandu jkun fih passaport. Ħafna inqas juruk kif toħloq wieħed — u kważi ebda wieħed ma jurik kif tagħmel dan għal katalgu ta' 500 jew 50,000 SKU mingħajr ma tikklikkja minn formola 50,000 darba.
Din il-gwida hija l-verżjoni tal-iżviluppatur. Kull pass hawn taħt huwa sejħa reali u funzjonali kontra l-API ta' qr3.app (https://qr3.app/v1). Jekk timmaniġġja d-data tal-prodott f'ERP, f'PIM jew f'database, tista' tgħaqqad il-ġenerazzjoni tal-DPP direttament fil-pipeline eżistenti tiegħek.
Għaliex API tagħmel differenza għad-DPPs
Passaport Diġitali tal-Prodott mhuwiex dokument ta' darba. Skont ir-Regolament dwar l-Ekodisinn għal Prodotti Sostenibbli (ESPR, UE 2024/1781) u r-Regolament tal-UE dwar il-Batteriji 2023/1542, kull unità rregolata teħtieġ passaport li jibqa' aġġornat tul il-ħajja kollha tiegħu. Għal manifattur dan ifisser:
- Skala — mijiet sa għexieren ta' eluf ta' prodotti, kull wieħed bil-GTIN/serjal tiegħu.
- Freskezza — id-data (impronta tal-karbonju, kontenut riċiklat, informazzjoni dwar it-tiswija) tinbidel u trid tiġi aġġornata, mhux maħluqa mill-ġdid.
- Integrazzjoni — is-sors tal-verità huwa l-ERP/PIM tiegħek, mhux formola tal-web.
Dik hija problema ta' API. Għodda tal-web manwali ġġiblek l-ewwel għaxar passaporti; API ġġiblek kollha kemm huma.
1. Awtentikazzjoni
Kull talba tuża bearer token (oħloq API key fid-dashboard). L-URL bażi huwa https://qr3.app/v1.
curl https://qr3.app/v1/dpp \
-H "Authorization: Bearer $QR3_API_KEY"
Jew bl-SDK uffiċjali:
import { QR3 } from "@qr3/sdk";
const client = new QR3({ apiKey: process.env.QR3_API_KEY! });
2. Oħloq passaport ta' batterija
DPP jinħoloq b'POST /dpp. Il-kampijiet tal-livell ogħla huma l-istess għal kull kategorija; id-data speċifika għall-kategorija tmur f'battery_data, textile_data jew 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"]
}
}'
L-istess sejħa bl-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
It-tweġiba tinkludi paġna ta' ndirizzar għall-konsumatur (lokalizzata f'25 lingwa tal-UE) u kodiċi QR GS1 Digital Link lest għall-istampar tat-tikketti — ebda pass QR separat mhu meħtieġ.
3. Validazzjoni qabel ma toħloq
Trid taqbad kampijiet nieqsa jew invalidi qabel ma tippersisti? POST /dpp/validate iħaddem ir-regoli eżatti tal-validazzjoni tal-UE mingħajr ma joħloq xejn. Ideali bħala kontroll pre-commit fis-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. Oħloq f'lott katalgu sħiħ
Għal katalgu ta' prodotti, ibgħat sa 100 passaport għal kull talba lil POST /dpp/batch. Idur fuq l-esportazzjoni tal-ERP tiegħek u jkollok il-firxa kollha tiegħek f'minuti.
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. Ikseb il-kodiċi QR għall-istampar tat-tikketti
Kull passaport jesponi l-QR tal-GS1 Digital Link tiegħu f'erba' formati ta' stampar. Iġbidhom permezz tal-oġġett tal-passaport jew direttament:
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 u qr.eps huma kollha disponibbli — SVG/EPS għall-istampatur tat-tikketti tiegħek, PNG għall-web.
6. Żomm id-data aġġornata (mingħajr ma tkisser il-QR)
Il-GTIN/serjal/lott huma immutabbli wara l-ħolqien — dan iżomm il-GS1 URI stampat stabbli għal dejjem. Kull ħaġa oħra tista' tiġi aġġornata b'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,
},
});
Il-QR fuq il-prodott fiżiku qatt ma jinbidel; id-data ta' warajh tinbidel. Dak huwa l-iskop kollu ta' passaport dinamiku.
7. Ibgħat lir-reġistru tal-UE
Meta r-reġistru ċentrali tad-DPP tal-UE jkun fl-ambitu għall-prodott tiegħek, ibgħat passaport b'sejħa waħda (pjan Business u 'l fuq):
const reg = await client.dpp.registerForEuRegistry(passport.id);
console.log(reg.data.eu_registry_status); // "pending"
console.log(reg.data.registry_request_id);
8. Irreaġixxi għall-iskanjar bil-webhooks
L-iskanjar tad-DPP huma avvenimenti. Abbona għal qr.scanned u tista' tibgħathom fl-analytics tiegħek, tikkawża ordnijiet mill-ġdid, jew timmarka sejħa lura — f'ħin reali. Il-payloads huma ffirmati (HMAC-SHA256); dejjem ivverifika l-firma.
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);
});
Inġemgħu kollox flimkien: ġenerazzjoni tad-DPP fis-CI
L-istat finali li jridu l-biċċa l-kbira tal-manifatturi: id-data tal-prodott tgħix fl-ERP/PIM, u xogħol skedat iżomm il-passaporti sinkronizzati.
- Esporta l-prodotti li nbidlu mill-ERP tiegħek.
client.dpp.validate(...)kull wieħed — ġib il-build jonqos fuq żbalji ta' validazzjoni.client.dpp.batch(...)prodotti ġodda;client.dpp.update(...)dawk li nbidlu.- Imbotta l-URLs ta'
qr.svgmibgħuta lura lis-sistema tal-istampar tat-tikketti tiegħek.
Ebda formola tal-web, ebda copy-paste, ebda devjazzjoni bejn id-data ewlenija tiegħek u l-passaporti tiegħek.
FAQ
Għandi bżonn għodda separata tal-kodiċi QR? Le. Kull DPP jirritorna QR tal-GS1 Digital Link f'SVG/PNG/PDF/EPS. Il-QR huwa l-punt ta' aċċess għall-passaport.
Nista' naġġorna passaport wara li t-tikketta tkun stampata?
Iva — dik hija l-idea ewlenija. Il-GTIN/serjal huma immutabbli sabiex il-URI stampat jibqa' validu; il-kampijiet kollha tad-data jistgħu jiġu aġġornati permezz ta' PUT /dpp/{id}.
Kemm-il passaport nista' noħloq f'daqqa?
Sa 100 għal kull talba POST /dpp/batch. Aqsam katalgi akbar f'biċċiet; il-limiti tar-rata japplikaw għal kull pjan.
Liema kategoriji huma appoġġjati?
battery u textile jiġu b'validazzjoni sħiħa tal-UE llum; general ikopri tipi oħra ta' prodotti. Il-batterija u t-tessut jinkludu kontroll ta' konformità tal-UE f'ħin reali (ESPR / AGEC).
Sorsi
Ibda b'xejn u oħloq l-ewwel DPP tiegħek permezz tal-API: app.qr3.app/sign-up
