La maggior parte degli articoli sul Passaporto Digitale di Prodotto UE (DPP) spiega cosa deve contenere un passaporto. Molti meno ti mostrano come crearne uno — e quasi nessuno ti mostra come farlo per un catalogo di 500 o 50.000 SKU senza compilare un modulo 50.000 volte.
Questa guida è la versione per sviluppatori. Ogni passo qui sotto è una chiamata reale e funzionante verso l'API di qr3.app (https://qr3.app/v1). Se gestisci i dati di prodotto in un ERP, in un PIM o in un database, puoi integrare la generazione dei DPP direttamente nella tua pipeline esistente.
Perché un'API è importante per i DPP
Un Passaporto Digitale di Prodotto non è un documento una tantum. Ai sensi del Regolamento sulla progettazione ecocompatibile dei prodotti sostenibili (ESPR, UE 2024/1781) e del Regolamento UE sulle batterie 2023/1542, ogni unità regolamentata ha bisogno di un passaporto che resti aggiornato per tutta la sua durata di vita. Per un produttore questo significa:
- Scala — da centinaia a decine di migliaia di prodotti, ciascuno con il proprio GTIN/numero di serie.
- Aggiornamento — i dati (impronta di carbonio, contenuto riciclato, informazioni sulle riparazioni) cambiano e devono essere aggiornati, non ricreati.
- Integrazione — la fonte di verità è il tuo ERP/PIM, non un modulo web.
Questo è un problema da API. Uno strumento web manuale ti porta ai primi dieci passaporti; un'API te li dà tutti.
1. Autenticazione
Ogni richiesta usa un bearer token (crea una chiave API nella dashboard). L'URL di base è https://qr3.app/v1.
curl https://qr3.app/v1/dpp \
-H "Authorization: Bearer $QR3_API_KEY"
Oppure con l'SDK ufficiale:
import { QR3 } from "@qr3/sdk";
const client = new QR3({ apiKey: process.env.QR3_API_KEY! });
2. Creare un passaporto per batteria
Un DPP si crea con POST /dpp. I campi di primo livello sono uguali per ogni categoria; i dati specifici della categoria vanno in battery_data, textile_data o 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"]
}
}'
La stessa chiamata con l'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
La risposta include una landing page rivolta al consumatore (localizzata in 25 lingue UE) e un QR code GS1 Digital Link pronto per la stampa delle etichette — non serve un passaggio QR separato.
3. Validare prima di creare
Vuoi individuare campi mancanti o non validi prima di salvare? POST /dpp/validate esegue esattamente le regole di validazione UE senza creare nulla. Ideale come controllo pre-commit in 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. Creare in batch un intero catalogo
Per un catalogo di prodotti, invia fino a 100 passaporti per richiesta a POST /dpp/batch. Itera sull'export del tuo ERP e avrai l'intera gamma in pochi 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. Ottenere il QR code per la stampa delle etichette
Ogni passaporto espone il proprio QR GS1 Digital Link in quattro formati di stampa. Recuperali tramite l'oggetto passaporto o direttamente:
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 e qr.eps sono tutti disponibili — SVG/EPS per la tua stampante di etichette, PNG per il web.
6. Mantenere i dati aggiornati (senza rompere il QR)
GTIN/numero di serie/lotto sono immutabili dopo la creazione — questo mantiene stabile per sempre l'URI GS1 stampato. Tutto il resto può essere aggiornato con 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 sul prodotto fisico non cambia mai; cambiano i dati dietro di esso. È esattamente questo il punto di un passaporto dinamico.
7. Inviare al registro UE
Quando il registro centrale DPP dell'UE rientra nell'ambito del tuo prodotto, invia un passaporto con una sola chiamata (piano Business e superiori):
const reg = await client.dpp.registerForEuRegistry(passport.id);
console.log(reg.data.eu_registry_status); // "pending"
console.log(reg.data.registry_request_id);
8. Reagire alle scansioni con i webhook
Le scansioni dei DPP sono eventi. Iscriviti a qr.scanned e potrai inviarle in streaming nelle tue analisi, attivare riordini o segnalare un richiamo — in tempo reale. I payload sono firmati (HMAC-SHA256); verifica sempre la 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);
});
Mettere tutto insieme: generazione dei DPP in CI
Lo stato finale che la maggior parte dei produttori desidera: i dati di prodotto vivono nell'ERP/PIM e un job pianificato mantiene i passaporti sincronizzati.
- Esporta i prodotti modificati dal tuo ERP.
client.dpp.validate(...)su ciascuno — fai fallire la build in caso di errori di validazione.client.dpp.batch(...)per i nuovi prodotti;client.dpp.update(...)per quelli modificati.- Invia gli URL
qr.svgrestituiti al tuo sistema di stampa delle etichette.
Nessun modulo web, nessun copia-incolla, nessuna divergenza tra i tuoi dati anagrafici e i tuoi passaporti.
FAQ
Mi serve uno strumento separato per i QR code? No. Ogni DPP restituisce un QR GS1 Digital Link in SVG/PNG/PDF/EPS. Il QR è il punto di accesso al passaporto.
Posso aggiornare un passaporto dopo che l'etichetta è stata stampata?
Sì — è questa l'idea centrale. GTIN/numero di serie sono immutabili, quindi l'URI stampato resta valido; tutti i campi dati sono aggiornabili tramite PUT /dpp/{id}.
Quanti passaporti posso creare in una volta?
Fino a 100 per richiesta POST /dpp/batch. Suddividi i cataloghi più grandi; i limiti di frequenza si applicano per piano.
Quali categorie sono supportate?
battery e textile includono già oggi la validazione UE completa; general copre gli altri tipi di prodotto. Battery e textile includono un controllo di conformità UE in tempo reale (ESPR / AGEC).
Fonti
Inizia gratis e crea il tuo primo DPP tramite API: app.qr3.app/sign-up
