Lielākā daļa rakstu par ES digitālo produktu pasi (DPP) skaidro, kas pasei jāietver. Daudz mazāk parāda, kā to izveidot — un gandrīz neviens neparāda, kā to izdarīt 500 vai 50 000 SKU katalogam, neaizpildot formu 50 000 reižu.
Šī rokasgrāmata ir izstrādātāja versija. Katrs solis tālāk ir reāls, strādājošs izsaukums pret qr3.app API (https://qr3.app/v1). Ja jūs pārvaldāt produktu datus ERP, PIM vai datubāzē, DPP ģenerēšanu varat iebūvēt tieši savā esošajā plūsmā.
Kāpēc API ir svarīgs DPP gadījumā
Digitālā produktu pase nav vienreizējs dokuments. Saskaņā ar Ekodizaina regulu attiecībā uz ilgtspējīgiem produktiem (ESPR, ES 2024/1781) un ES Bateriju regulu 2023/1542 katrai regulētai vienībai ir nepieciešama pase, kas paliek aktuāla visā tās dzīves ciklā. Ražotājam tas nozīmē:
- Mērogs — simtiem līdz desmitiem tūkstošu produktu, katrs ar savu GTIN/sērijas numuru.
- Aktualitāte — dati (oglekļa pēdas nospiedums, pārstrādātais saturs, remonta informācija) mainās, un tie ir jāatjaunina, nevis jāizveido no jauna.
- Integrācija — patiesības avots ir jūsu ERP/PIM, nevis tīmekļa forma.
Tā ir API problēma. Manuāls tīmekļa rīks sniedz pirmās desmit pases; API sniedz tās visas.
1. Autentifikācija
Katrā pieprasījumā tiek izmantots bearer žetons (izveidojiet API atslēgu informācijas panelī). Bāzes URL ir https://qr3.app/v1.
curl https://qr3.app/v1/dpp \
-H "Authorization: Bearer $QR3_API_KEY"
Vai ar oficiālo SDK:
import { QR3 } from "@qr3/sdk";
const client = new QR3({ apiKey: process.env.QR3_API_KEY! });
2. Izveidojiet baterijas pasi
DPP tiek izveidota ar POST /dpp. Augstākā līmeņa lauki ir vienādi katrai kategorijai; kategorijai specifiskie dati nonāk laukos battery_data, textile_data vai 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"]
}
}'
Tas pats izsaukums ar 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
Atbilde ietver patērētājam paredzētu galveno lapu (lokalizētu 25 ES valodās) un GS1 Digital Link QR kodu, kas ir gatavs etiķešu drukāšanai — atsevišķs QR solis nav nepieciešams.
3. Validējiet pirms izveidošanas
Vēlaties pamanīt trūkstošos vai nederīgos laukus pirms saglabāšanas? POST /dpp/validate palaiž tieši tos pašus ES validācijas noteikumus, neko neizveidojot. Ideāli piemērots kā pirmsiesniegšanas pārbaude CI vidē.
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. Izveidojiet veselu katalogu vienā partijā
Produktu katalogam nosūtiet līdz 100 pasēm vienā pieprasījumā uz POST /dpp/batch. Veiciet cilpu pa savu ERP eksportu, un visa jūsu produktu līnija ir gatava dažu minūšu laikā.
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. Iegūstiet QR kodu etiķešu drukāšanai
Katra pase atklāj savu GS1 Digital Link QR kodu četros drukas formātos. Iegūstiet tos, izmantojot pases objektu vai tieši:
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 un qr.eps ir pieejami visi — SVG/EPS jūsu etiķešu printerim, PNG tīmeklim.
6. Uzturiet datus aktuālus (nesabojājot QR kodu)
GTIN/sērijas numurs/partija pēc izveidošanas ir nemaināmi — tas saglabā izdrukāto GS1 URI stabilu uz visiem laikiem. Visu pārējo var atjaunināt ar 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 kods uz fiziskā produkta nekad nemainās; mainās dati aiz tā. Tas ir viss dinamiskas pases jēgas pamatā.
7. Iesniedziet ES reģistrā
Kad ES centrālais DPP reģistrs ir piemērojams jūsu produktam, iesniedziet pasi ar vienu izsaukumu (Business plāns un augstāk):
const reg = await client.dpp.registerForEuRegistry(passport.id);
console.log(reg.data.eu_registry_status); // "pending"
console.log(reg.data.registry_request_id);
8. Reaģējiet uz skenēšanu ar webhooks
DPP skenēšanas ir notikumi. Abonējiet qr.scanned, un jūs varat tos pārraidīt savā analītikā, izraisīt atkārtotus pasūtījumus vai atzīmēt atsaukšanu — reāllaikā. Lietderīgās slodzes ir parakstītas (HMAC-SHA256); vienmēr pārbaudiet parakstu.
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);
});
Saliekot kopā: DPP ģenerēšana CI vidē
Galastāvoklis, ko vēlas lielākā daļa ražotāju: produktu dati atrodas ERP/PIM, un ieplānots uzdevums uztur pases sinhronizētas.
- Eksportējiet mainītos produktus no sava ERP.
client.dpp.validate(...)katram no tiem — neizdodiet būvējumu validācijas kļūdu gadījumā.client.dpp.batch(...)jauniem produktiem;client.dpp.update(...)mainītajiem.- Nosūtiet atgrieztos
qr.svgURL uz savu etiķešu drukāšanas sistēmu.
Nav tīmekļa formas, nav kopēšanas un ielīmēšanas, nav novirzes starp jūsu pamatdatiem un jūsu pasēm.
Biežāk uzdotie jautājumi
Vai man ir nepieciešams atsevišķs QR koda rīks? Nē. Katra DPP atgriež GS1 Digital Link QR kodu formātā SVG/PNG/PDF/EPS. QR kods ir piekļuves punkts pasei.
Vai es varu atjaunināt pasi pēc etiķetes izdrukāšanas?
Jā — tā ir pamatideja. GTIN/sērijas numurs ir nemaināmi, tāpēc izdrukātais URI paliek derīgs; visi datu lauki ir atjaunināmi, izmantojot PUT /dpp/{id}.
Cik pases es varu izveidot vienlaikus?
Līdz 100 uz vienu POST /dpp/batch pieprasījumu. Sadaliet lielākus katalogus daļās; pieprasījumu ierobežojumi attiecas atkarībā no plāna.
Kuras kategorijas tiek atbalstītas?
battery un textile jau šodien tiek piegādātas ar pilnu ES validāciju; general aptver citus produktu veidus. Baterijas un tekstilizstrādājumi ietver tiešo ES atbilstības pārbaudi (ESPR / AGEC).
Avoti
Sāciet bez maksas un izveidojiet savu pirmo DPP, izmantojot API: app.qr3.app/sign-up
