Τα περισσότερα άρθρα για το EU Digital Product Passport (DPP) εξηγούν τι πρέπει να περιέχει ένα διαβατήριο. Πολύ λιγότερα σας δείχνουν πώς να δημιουργήσετε ένα — και σχεδόν κανένα δεν σας δείχνει πώς να το κάνετε για έναν κατάλογο 500 ή 50.000 SKU χωρίς να κάνετε κλικ σε μια φόρμα 50.000 φορές.
Αυτός ο οδηγός είναι η έκδοση για προγραμματιστές. Κάθε βήμα παρακάτω είναι μια πραγματική, λειτουργική κλήση προς το API του qr3.app (https://qr3.app/v1). Αν διαχειρίζεστε δεδομένα προϊόντων σε ένα ERP, ένα PIM ή μια βάση δεδομένων, μπορείτε να συνδέσετε τη δημιουργία DPP απευθείας στην υπάρχουσα ροή σας.
Γιατί ένα API έχει σημασία για τα DPP
Ένα Digital Product Passport δεν είναι ένα εφάπαξ έγγραφο. Σύμφωνα με τον Κανονισμό για τον Οικολογικό Σχεδιασμό Βιώσιμων Προϊόντων (ESPR, EU 2024/1781) και τον Κανονισμό της ΕΕ για τις Μπαταρίες 2023/1542, κάθε ρυθμιζόμενη μονάδα χρειάζεται ένα διαβατήριο που παραμένει επίκαιρο καθ' όλη τη διάρκεια ζωής της. Για έναν κατασκευαστή αυτό σημαίνει:
- Κλίμακα — εκατοντάδες έως δεκάδες χιλιάδες προϊόντα, καθένα με το δικό του GTIN/σειριακό αριθμό.
- Επικαιρότητα — τα δεδομένα (αποτύπωμα άνθρακα, ανακυκλωμένο περιεχόμενο, πληροφορίες επισκευής) αλλάζουν και πρέπει να ενημερώνονται, όχι να αναδημιουργούνται.
- Ενσωμάτωση — η πηγή αλήθειας είναι το ERP/PIM σας, όχι μια φόρμα ιστού.
Αυτό είναι ένα πρόβλημα API. Ένα χειροκίνητο εργαλείο ιστού σας δίνει τα πρώτα δέκα διαβατήρια· ένα API σας δίνει όλα.
1. Έλεγχος ταυτότητας
Κάθε αίτημα χρησιμοποιεί ένα bearer token (δημιουργήστε ένα κλειδί API στον πίνακα ελέγχου). Το βασικό URL είναι https://qr3.app/v1.
curl https://qr3.app/v1/dpp \
-H "Authorization: Bearer $QR3_API_KEY"
Ή με το επίσημο SDK:
import { QR3 } from "@qr3/sdk";
const client = new QR3({ apiKey: process.env.QR3_API_KEY! });
2. Δημιουργία διαβατηρίου μπαταρίας
Ένα DPP δημιουργείται με POST /dpp. Τα πεδία ανώτατου επιπέδου είναι τα ίδια για κάθε κατηγορία· τα δεδομένα που αφορούν συγκεκριμένη κατηγορία μπαίνουν στο battery_data, το textile_data ή το 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"]
}
}'
Η ίδια κλήση με το 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
Η απάντηση περιλαμβάνει μια σελίδα προορισμού για τον καταναλωτή (τοπικοποιημένη σε 25 γλώσσες της ΕΕ) και έναν GS1 Digital Link QR κωδικό έτοιμο για εκτύπωση ετικέτας — δεν απαιτείται ξεχωριστό βήμα QR.
3. Επικύρωση πριν τη δημιουργία
Θέλετε να εντοπίσετε ελλιπή ή μη έγκυρα πεδία πριν την αποθήκευση; Το POST /dpp/validate εκτελεί ακριβώς τους κανόνες επικύρωσης της ΕΕ χωρίς να δημιουργεί τίποτα. Ιδανικό ως έλεγχος pre-commit στο 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. Μαζική δημιουργία ολόκληρου καταλόγου
Για έναν κατάλογο προϊόντων, στείλτε έως και 100 διαβατήρια ανά αίτημα στο POST /dpp/batch. Επαναλάβετε πάνω από την εξαγωγή του ERP σας και έχετε ολόκληρη τη γκάμα σας σε λεπτά.
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. Λήψη του QR κωδικού για εκτύπωση ετικέτας
Κάθε διαβατήριο εκθέτει τον GS1 Digital Link QR κωδικό του σε τέσσερις μορφές εκτύπωσης. Ανακτήστε τις μέσω του αντικειμένου διαβατηρίου ή απευθείας:
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 και qr.eps είναι όλα διαθέσιμα — SVG/EPS για τον εκτυπωτή ετικετών σας, PNG για τον ιστό.
6. Διατηρήστε τα δεδομένα επίκαιρα (χωρίς να χαλάσετε τον QR)
Το GTIN/σειριακός/παρτίδα είναι αμετάβλητα μετά τη δημιουργία — αυτό κρατά το εκτυπωμένο GS1 URI σταθερό για πάντα. Όλα τα υπόλοιπα μπορούν να ενημερωθούν με 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 κωδικός στο φυσικό προϊόν δεν αλλάζει ποτέ· τα δεδομένα πίσω από αυτόν αλλάζουν. Αυτό είναι ολόκληρο το νόημα ενός δυναμικού διαβατηρίου.
7. Υποβολή στο μητρώο της ΕΕ
Όταν το κεντρικό μητρώο DPP της ΕΕ εμπίπτει στο πεδίο εφαρμογής του προϊόντος σας, υποβάλετε ένα διαβατήριο με μία κλήση (πλάνο Business και άνω):
const reg = await client.dpp.registerForEuRegistry(passport.id);
console.log(reg.data.eu_registry_status); // "pending"
console.log(reg.data.registry_request_id);
8. Αντιδράστε στις σαρώσεις με webhooks
Οι σαρώσεις DPP είναι συμβάντα. Εγγραφείτε στο qr.scanned και μπορείτε να τις διοχετεύσετε στα analytics σας, να ενεργοποιήσετε επαναπαραγγελίες ή να επισημάνετε μια ανάκληση — σε πραγματικό χρόνο. Τα payloads είναι υπογεγραμμένα (HMAC-SHA256)· επαληθεύετε πάντα την υπογραφή.
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);
});
Βάζοντάς τα όλα μαζί: δημιουργία DPP στο CI
Η τελική κατάσταση που θέλουν οι περισσότεροι κατασκευαστές: τα δεδομένα προϊόντων ζουν στο ERP/PIM, και μια προγραμματισμένη εργασία κρατά τα διαβατήρια συγχρονισμένα.
- Εξαγάγετε τα προϊόντα που άλλαξαν από το ERP σας.
client.dpp.validate(...)το καθένα — αποτυχία του build σε σφάλματα επικύρωσης.client.dpp.batch(...)τα νέα προϊόντα·client.dpp.update(...)αυτά που άλλαξαν.- Προωθήστε τα επιστρεφόμενα
qr.svgURL στο σύστημα εκτύπωσης ετικετών σας.
Καμία φόρμα ιστού, καμία αντιγραφή-επικόλληση, καμία απόκλιση μεταξύ των κύριων δεδομένων σας και των διαβατηρίων σας.
Συχνές ερωτήσεις
Χρειάζομαι ξεχωριστό εργαλείο QR κωδικών; Όχι. Κάθε DPP επιστρέφει έναν GS1 Digital Link QR σε SVG/PNG/PDF/EPS. Ο QR είναι το σημείο πρόσβασης στο διαβατήριο.
Μπορώ να ενημερώσω ένα διαβατήριο αφού εκτυπωθεί η ετικέτα;
Ναι — αυτή είναι η βασική ιδέα. Το GTIN/σειριακός είναι αμετάβλητα, οπότε το εκτυπωμένο URI παραμένει έγκυρο· όλα τα πεδία δεδομένων μπορούν να ενημερωθούν μέσω PUT /dpp/{id}.
Πόσα διαβατήρια μπορώ να δημιουργήσω ταυτόχρονα;
Έως 100 ανά αίτημα POST /dpp/batch. Χωρίστε σε τμήματα τους μεγαλύτερους καταλόγους· τα όρια ρυθμού ισχύουν ανά πλάνο.
Ποιες κατηγορίες υποστηρίζονται;
Οι battery και textile διατίθενται με πλήρη επικύρωση ΕΕ σήμερα· η general καλύπτει άλλους τύπους προϊόντων. Η μπαταρία και τα κλωστοϋφαντουργικά περιλαμβάνουν έναν ζωντανό έλεγχο συμμόρφωσης με την ΕΕ (ESPR / AGEC).
Πηγές
Ξεκινήστε δωρεάν και δημιουργήστε το πρώτο σας DPP μέσω API: app.qr3.app/sign-up
