Majoritatea articolelor despre pașaportul digital al produsului din UE (EU DPP) explică ce trebuie să conțină un pașaport. Mult mai puține îți arată cum să creezi unul — și aproape niciunul nu îți arată cum să faci asta pentru un catalog de 500 sau 50.000 de SKU-uri fără să completezi un formular de 50.000 de ori.
Acest ghid este versiunea pentru dezvoltatori. Fiecare pas de mai jos este un apel real și funcțional către API-ul qr3.app (https://qr3.app/v1). Dacă gestionezi date despre produse într-un ERP, un PIM sau o bază de date, poți integra generarea DPP direct în pipeline-ul tău existent.
De ce contează un API pentru DPP-uri
Un pașaport digital al produsului nu este un document unic. Conform Regulamentului privind proiectarea ecologică a produselor durabile (ESPR, EU 2024/1781) și Regulamentului UE privind bateriile 2023/1542, fiecare unitate reglementată are nevoie de un pașaport care rămâne actualizat pe întreaga sa durată de viață. Pentru un producător, asta înseamnă:
- Scară — de la sute la zeci de mii de produse, fiecare cu propriul GTIN/serie.
- Actualitate — datele (amprenta de carbon, conținutul reciclat, informațiile despre reparații) se modifică și trebuie actualizate, nu recreate.
- Integrare — sursa adevărului este ERP-ul/PIM-ul tău, nu un formular web.
Aceasta este o problemă de API. Un instrument web manual îți aduce primele zece pașapoarte; un API ți le aduce pe toate.
1. Autentificare
Fiecare cerere folosește un token bearer (creează o cheie API în dashboard). URL-ul de bază este https://qr3.app/v1.
curl https://qr3.app/v1/dpp \
-H "Authorization: Bearer $QR3_API_KEY"
Sau cu SDK-ul oficial:
import { QR3 } from "@qr3/sdk";
const client = new QR3({ apiKey: process.env.QR3_API_KEY! });
2. Creează un pașaport pentru baterie
Un DPP se creează cu POST /dpp. Câmpurile de nivel superior sunt aceleași pentru fiecare categorie; datele specifice categoriei intră în battery_data, textile_data sau 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"]
}
}'
Același apel cu SDK-ul:
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); // cod QR GS1 Digital Link gata de tipărit
Răspunsul include o pagină de destinație orientată către consumator (localizată în 25 de limbi UE) și un cod QR GS1 Digital Link gata pentru tipărirea etichetei — fără pas QR separat.
3. Validează înainte de a crea
Vrei să prinzi câmpurile lipsă sau invalide înainte de a le persista? POST /dpp/validate rulează exact regulile de validare ale UE fără să creeze nimic. Ideal ca verificare pre-commit în 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. Creează în lot un catalog întreg
Pentru un catalog de produse, trimite până la 100 de pașapoarte per cerere către POST /dpp/batch. Parcurge în buclă exportul din ERP-ul tău și ai întreaga gamă în câteva minute.
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,
},
}));
// Împarte în loturi de 100
const result = await client.dpp.batch({ items: items.slice(0, 100) });
5. Obține codul QR pentru tipărirea etichetei
Fiecare pașaport își expune codul QR GS1 Digital Link în patru formate de tipărire. Extrage-le prin obiectul pașaport sau direct:
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 sunt toate disponibile — SVG/EPS pentru imprimanta ta de etichete, PNG pentru web.
6. Menține datele actualizate (fără să strici codul QR)
GTIN/seria/lotul sunt imutabile după creare — asta menține URI-ul GS1 tipărit stabil pentru totdeauna. Tot restul poate fi actualizat cu PUT /dpp/{id}:
await client.dpp.update(passport.id, {
battery_data: {
capacity_kwh: 5,
carbon_footprint_kg: 58, // remăsurat, amprentă mai mică
recycled_content_pct: 16, // ținta pentru 2031 atinsă mai devreme
recyclability_pct: 95,
manufacturer_warranty_years: 8,
},
});
Codul QR de pe produsul fizic nu se schimbă niciodată; datele din spatele lui se schimbă. Acesta este întregul scop al unui pașaport dinamic.
7. Trimite la registrul UE
Atunci când registrul central DPP al UE este aplicabil pentru produsul tău, trimite un pașaport cu un singur apel (planul Business și mai sus):
const reg = await client.dpp.registerForEuRegistry(passport.id);
console.log(reg.data.eu_registry_status); // "pending"
console.log(reg.data.registry_request_id);
8. Reacționează la scanări cu webhook-uri
Scanările DPP sunt evenimente. Abonează-te la qr.scanned și le poți transmite în analiticele tale, declanșa recomenzi sau semnala un rechemare — în timp real. Sarcinile utile sunt semnate (HMAC-SHA256); verifică întotdeauna semnătura.
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);
});
Punând totul cap la cap: generarea DPP în CI
Starea finală pe care o doresc majoritatea producătorilor: datele despre produse trăiesc în ERP/PIM, iar o sarcină programată menține pașapoartele sincronizate.
- Exportă produsele modificate din ERP-ul tău.
client.dpp.validate(...)pe fiecare — eșuează build-ul la erorile de validare.client.dpp.batch(...)pentru produsele noi;client.dpp.update(...)pentru cele modificate.- Trimite URL-urile
qr.svgreturnate către sistemul tău de tipărire a etichetelor.
Niciun formular web, niciun copy-paste, nicio nepotrivire între datele tale principale și pașapoartele tale.
Întrebări frecvente
Am nevoie de un instrument separat pentru coduri QR? Nu. Fiecare DPP returnează un cod QR GS1 Digital Link în SVG/PNG/PDF/EPS. Codul QR este punctul de acces la pașaport.
Pot actualiza un pașaport după ce eticheta a fost tipărită?
Da — aceasta este ideea de bază. GTIN/seria sunt imutabile, astfel încât URI-ul tipărit rămâne valabil; toate câmpurile de date pot fi actualizate prin PUT /dpp/{id}.
Câte pașapoarte pot crea deodată?
Până la 100 per cerere POST /dpp/batch. Împarte cataloagele mai mari în bucăți; limitele de rată se aplică per plan.
Care categorii sunt acceptate?
battery și textile vin astăzi cu validare UE completă; general acoperă alte tipuri de produse. Bateria și textilele includ o verificare live a conformității cu UE (ESPR / AGEC).
Surse
Începe gratuit și creează primul tău DPP prin API: app.qr3.app/sign-up
