La plupart des articles sur le passeport numérique de produit (EU DPP) européen expliquent ce que doit contenir un passeport. Beaucoup plus rares sont ceux qui vous montrent comment en créer un — et presque aucun ne vous explique comment le faire pour un catalogue de 500 ou 50 000 références sans cliquer 50 000 fois dans un formulaire.
Ce guide est la version pour développeurs. Chaque étape ci-dessous correspond à un appel réel et fonctionnel vers l'API qr3.app (https://qr3.app/v1). Si vous gérez vos données produit dans un ERP, un PIM ou une base de données, vous pouvez intégrer la génération de DPP directement dans votre pipeline existant.
Pourquoi une API est essentielle pour les DPP
Un passeport numérique de produit n'est pas un document ponctuel. En vertu du règlement sur l'écoconception des produits durables (ESPR, EU 2024/1781) et du règlement européen sur les batteries 2023/1542, chaque unité réglementée a besoin d'un passeport qui reste à jour pendant toute sa durée de vie. Pour un fabricant, cela signifie :
- L'échelle — de centaines à des dizaines de milliers de produits, chacun avec son propre GTIN/numéro de série.
- L'actualité — les données (empreinte carbone, contenu recyclé, informations de réparation) évoluent et doivent être mises à jour, et non recréées.
- L'intégration — la source de vérité est votre ERP/PIM, pas un formulaire web.
C'est un problème d'API. Un outil web manuel vous permet de créer les dix premiers passeports ; une API vous permet de les créer tous.
1. Authentification
Chaque requête utilise un jeton bearer (créez une clé API dans le tableau de bord). L'URL de base est https://qr3.app/v1.
curl https://qr3.app/v1/dpp \
-H "Authorization: Bearer $QR3_API_KEY"
Ou avec le SDK officiel :
import { QR3 } from "@qr3/sdk";
const client = new QR3({ apiKey: process.env.QR3_API_KEY! });
2. Créer un passeport de batterie
Un DPP se crée avec POST /dpp. Les champs de premier niveau sont les mêmes pour chaque catégorie ; les données spécifiques à la catégorie vont dans battery_data, textile_data ou 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"]
}
}'
Le même appel avec le 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 réponse inclut une page de destination orientée consommateur (localisée dans 25 langues de l'UE) et un QR code GS1 Digital Link prêt pour l'impression d'étiquettes — aucune étape QR distincte n'est nécessaire.
3. Valider avant de créer
Vous voulez détecter les champs manquants ou invalides avant la persistance ? POST /dpp/validate applique exactement les règles de validation de l'UE sans rien créer. Idéal comme vérification pre-commit dans une 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. Créer un catalogue entier par lots
Pour un catalogue de produits, envoyez jusqu'à 100 passeports par requête à POST /dpp/batch. Parcourez votre export ERP en boucle et vous obtenez toute votre gamme en quelques minutes.
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. Récupérer le QR code pour l'impression d'étiquettes
Chaque passeport expose son QR code GS1 Digital Link dans quatre formats d'impression. Récupérez-les via l'objet passeport ou directement :
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 et qr.eps sont tous disponibles — SVG/EPS pour votre imprimante d'étiquettes, PNG pour le web.
6. Maintenir les données à jour (sans casser le QR)
Le GTIN/numéro de série/lot sont immuables après la création — cela garde l'URI GS1 imprimée stable pour toujours. Tout le reste peut être mis à jour avec 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,
},
});
Le QR code sur le produit physique ne change jamais ; les données qui se trouvent derrière, si. C'est tout l'intérêt d'un passeport dynamique.
7. Soumettre au registre de l'UE
Lorsque le registre central des DPP de l'UE concerne votre produit, soumettez un passeport en un seul appel (à partir du plan 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. Réagir aux scans avec les webhooks
Les scans de DPP sont des événements. Abonnez-vous à qr.scanned et vous pouvez les transmettre en flux vers votre outil d'analytics, déclencher des réapprovisionnements ou signaler un rappel — en temps réel. Les charges utiles sont signées (HMAC-SHA256) ; vérifiez toujours la signature.
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);
});
Tout assembler : la génération de DPP en CI
L'état final que souhaitent la plupart des fabricants : les données produit vivent dans l'ERP/PIM, et une tâche planifiée maintient les passeports synchronisés.
- Exportez les produits modifiés depuis votre ERP.
- Validez chacun avec
client.dpp.validate(...)— faites échouer le build en cas d'erreurs de validation. - Créez les nouveaux produits avec
client.dpp.batch(...); mettez à jour ceux qui ont changé avecclient.dpp.update(...). - Transmettez les URL
qr.svgretournées à votre système d'impression d'étiquettes.
Aucun formulaire web, aucun copier-coller, aucune dérive entre vos données de référence et vos passeports.
FAQ
Ai-je besoin d'un outil de QR code séparé ? Non. Chaque DPP retourne un QR code GS1 Digital Link au format SVG/PNG/PDF/EPS. Le QR code est le point d'accès au passeport.
Puis-je mettre à jour un passeport une fois l'étiquette imprimée ?
Oui — c'est l'idée centrale. Le GTIN/numéro de série étant immuables, l'URI imprimée reste valide ; tous les champs de données sont modifiables via PUT /dpp/{id}.
Combien de passeports puis-je créer en une seule fois ?
Jusqu'à 100 par requête POST /dpp/batch. Découpez les catalogues plus volumineux ; des limites de débit s'appliquent selon le plan.
Quelles catégories sont prises en charge ?
battery et textile sont livrés aujourd'hui avec une validation UE complète ; general couvre les autres types de produits. Les batteries et les textiles incluent un contrôle de conformité UE en direct (ESPR / AGEC).
Sources
Commencez gratuitement et créez votre premier DPP via API : app.qr3.app/sign-up
