--- title: "Generare Passaporti Digitali di Prodotto UE tramite API — qr3.app Blog" description: "La maggior parte delle guide sul DPP ti dice cosa deve contenere un passaporto. Questa ti mostra come creare Passaporti Digitali di Prodotto conformi alla normativa UE in modo programmatico — con curl, l" canonical: "https://qr3.app/it/blog/dpp-api-generate-passports/" lang: "it" robots: "index,follow,max-image-preview:large,max-snippet:-1" --- # Generare Passaporti Digitali di Prodotto UE tramite API — qr3.app Blog > La maggior parte delle guide sul DPP ti dice cosa deve contenere un passaporto. Questa ti mostra come creare Passaporti Digitali di Prodotto conformi alla normativa UE in modo programmatico — con curl, l Canonical: [← Blog](/it/blog/) [Tutorials](/it/blog/category/tutorials/) 30 maggio 2026 4 min di lettura [Tutorials](/it/blog/category/tutorials/) [dpp](/it/blog/tag/dpp/)[api](/it/blog/tag/api/)[gs1-digital-link](/it/blog/tag/gs1-digital-link/)[developers](/it/blog/tag/developers/)[eu-2024-1781](/it/blog/tag/eu-2024-1781/) # Generare Passaporti Digitali di Prodotto UE tramite API La maggior parte delle guide sul DPP ti dice cosa deve contenere un passaporto. Questa ti mostra come creare Passaporti Digitali di Prodotto conformi alla normativa UE in modo programmatico — con curl, l'SDK qr3, creazione in batch, validazione, QR code GS1 e webhook. di **QR3 Redaktion** ![Generare Passaporti Digitali di Prodotto UE tramite API](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/dpp-api-generate-passports/hero.png) 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)](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R1781) e del [Regolamento UE sulle batterie 2023/1542](https://eur-lex.europa.eu/eli/reg/2023/1542/oj), 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); ``` > **Situazione attuale:** l’UE non ha ancora pubblicato l’API del suo registro DPP centrale. Fino ad allora, questa chiamata è un percorso di test — lo stato rimane `pending` e nessuna autorità riceve il passaporto. Non appena l’API sarà live, la stessa chiamata diventerà una registrazione reale. ## 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 { createHmac, timingSafeEqual } from "crypto"; app.post("/webhooks/qr3", express.raw({ type: "application/json" }), (req, res) => { const expected = createHmac("sha256", secret).update(req.body).digest("hex"); const expectedBytes = Buffer.from(`sha256=${expected}`); const receivedBytes = Buffer.from(String(req.headers["x-qr3-signature"] ?? "")); const ok = expectedBytes.length === receivedBytes.length && timingSafeEqual(expectedBytes, receivedBytes); if (!ok) return res.sendStatus(401); const event = JSON.parse(req.body.toString("utf8")); 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. 1. Esporta i prodotti modificati dal tuo ERP. 2. `client.dpp.validate(...)` su ciascuno — fai fallire la build in caso di errori di validazione. 3. `client.dpp.batch(...)` per i nuovi prodotti; `client.dpp.update(...)` per quelli modificati. 4. Invia gli URL `qr.svg` restituiti 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; il limite è di 60 richieste al minuto per chiave API, su tutti i piani. **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 - [ESPR — Regolamento (UE) 2024/1781](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R1781) - [Regolamento UE sulle batterie 2023/1542](https://eur-lex.europa.eu/eli/reg/2023/1542/oj) - [GS1 Digital Link](https://www.gs1.org/standards/gs1-digital-link) **Inizia gratis** e crea il tuo primo DPP tramite API: [app.qr3.app/sign-up](https://app.qr3.app/sign-up) ## Articoli correlati - [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/gs1-resolver-test-suite-dpp-links/hero.png) Tutorials Suite di test GS1 Resolver: DPP-Verificare in modo affidabile i link prima del go-live La stabile suite di test GS1 consente di verificare Resolver 1.2. Ecco come testare redirect, linkset, CORS, lingue e casi di errore prima del go-live.](/it/blog/gs1-resolver-test-suite-dpp-links/) - [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/dpp-battery-passport-2027-20260715/hero.png) Notizie di settore BatteryPass-Ready avvia l’ambiente di test per il Passaporto Digitale delle Batterie Il consorzio BatteryPass-Ready ha avviato il 24 giugno 2026 un ambiente di test pubblico per il Passaporto Digitale delle Batterie, in vista dell’obbligo UE da febbraio 2027.](/it/blog/dpp-battery-passport-2027-20260715/) - [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/sector-20260713/hero.png) Notizie di settore Passaporto digitale delle batterie 2027: cosa devono sapere ora i produttori Webinar, strumenti open source e nuove norme: il passaporto UE delle batterie sta prendendo slancio. Una panoramica sulla situazione a luglio 2026 e sulle questioni aperte fino a febbraio 2027.](/it/blog/sector-20260713/) - [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/sector-20260711/hero.png) Notizie di settore Passaporto digitale delle batterie 2026: ambienti di test, norme e questioni aperte A che punto è l’industria con il Passaporto digitale delle batterie? Una panoramica su ambienti di test, norme CEN/CENELEC, strumenti open source e orientamenti normativi a luglio 2026.](/it/blog/sector-20260711/) [← Tutti gli articoli](/it/blog/) [Inizia gratis](https://app.qr3.app/sign-up)