La mayoría de los artículos sobre el Pasaporte Digital de Producto de la UE (EU DPP) explican qué debe contener un pasaporte. Muchos menos te muestran cómo crear uno — y casi ninguno te muestra cómo hacerlo para un catálogo de 500 o 50 000 SKU sin tener que rellenar un formulario 50 000 veces.
Esta guía es la versión para desarrolladores. Cada paso que sigue es una llamada real y funcional contra la API de qr3.app (https://qr3.app/v1). Si gestionas datos de producto en un ERP, un PIM o una base de datos, puedes integrar la generación de DPP directamente en tu pipeline actual.
Por qué importa una API para los DPP
Un Pasaporte Digital de Producto no es un documento puntual. Bajo el Reglamento de Diseño Ecológico para Productos Sostenibles (ESPR, UE 2024/1781) y el Reglamento de Baterías de la UE 2023/1542, cada unidad regulada necesita un pasaporte que se mantenga actualizado durante toda su vida útil. Para un fabricante, eso significa:
- Escala — de cientos a decenas de miles de productos, cada uno con su propio GTIN/número de serie.
- Actualidad — los datos (huella de carbono, contenido reciclado, información de reparación) cambian y deben actualizarse, no recrearse.
- Integración — la fuente de la verdad es tu ERP/PIM, no un formulario web.
Eso es un problema de API. Una herramienta web manual te lleva hasta los primeros diez pasaportes; una API te da todos ellos.
1. Autenticación
Cada solicitud usa un token bearer (crea una clave API en el panel de control). La URL base es https://qr3.app/v1.
curl https://qr3.app/v1/dpp \
-H "Authorization: Bearer $QR3_API_KEY"
O con el SDK oficial:
import { QR3 } from "@qr3/sdk";
const client = new QR3({ apiKey: process.env.QR3_API_KEY! });
2. Crear un pasaporte de batería
Un DPP se crea con POST /dpp. Los campos de nivel superior son los mismos para cada categoría; los datos específicos de la categoría van en 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 misma llamada con el 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); // GS1 Digital Link QR listo para imprimir
La respuesta incluye una página de aterrizaje orientada al consumidor (localizada en 25 idiomas de la UE) y un código QR GS1 Digital Link listo para imprimir en etiquetas — sin necesidad de un paso de QR aparte.
3. Validar antes de crear
¿Quieres detectar campos faltantes o no válidos antes de persistir? POST /dpp/validate ejecuta exactamente las reglas de validación de la UE sin crear nada. Ideal como comprobación previa al commit en 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. Crear un catálogo completo por lotes
Para un catálogo de productos, envía hasta 100 pasaportes por solicitud a POST /dpp/batch. Recorre tu exportación del ERP y tendrás toda tu gama en minutos.
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,
},
}));
// Dividir en lotes de 100
const result = await client.dpp.batch({ items: items.slice(0, 100) });
5. Obtener el código QR para imprimir etiquetas
Cada pasaporte expone su QR GS1 Digital Link en cuatro formatos de impresión. Recupéralos a través del objeto del pasaporte o directamente:
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 y qr.eps están todos disponibles — SVG/EPS para tu impresora de etiquetas, PNG para la web.
6. Mantener los datos actualizados (sin romper el QR)
El GTIN/número de serie/lote son inmutables tras la creación — eso mantiene la URI GS1 impresa estable para siempre. Todo lo demás puede actualizarse con PUT /dpp/{id}:
await client.dpp.update(passport.id, {
battery_data: {
capacity_kwh: 5,
carbon_footprint_kg: 58, // remedido, menor huella
recycled_content_pct: 16, // objetivo de 2031 alcanzado antes de tiempo
recyclability_pct: 95,
manufacturer_warranty_years: 8,
},
});
El QR del producto físico nunca cambia; los datos que hay detrás sí. Ese es justo el sentido de un pasaporte dinámico.
7. Enviar al registro de la UE
Cuando el registro central de DPP de la UE sea aplicable a tu producto, envía un pasaporte con una sola llamada (plan Business en adelante):
const reg = await client.dpp.registerForEuRegistry(passport.id);
console.log(reg.data.eu_registry_status); // "pending"
console.log(reg.data.registry_request_id);
8. Reaccionar a los escaneos con webhooks
Los escaneos de DPP son eventos. Suscríbete a qr.scanned y podrás transmitirlos a tu analítica, activar reposiciones o señalar una retirada — en tiempo real. Los payloads están firmados (HMAC-SHA256); verifica siempre 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);
});
Uniéndolo todo: generación de DPP en CI
El estado final que quiere la mayoría de los fabricantes: los datos de producto viven en el ERP/PIM y un trabajo programado mantiene los pasaportes sincronizados.
- Exporta los productos modificados desde tu ERP.
client.dpp.validate(...)cada uno — haz fallar la compilación ante errores de validación.client.dpp.batch(...)los productos nuevos;client.dpp.update(...)los modificados.- Envía las URL
qr.svgdevueltas a tu sistema de impresión de etiquetas.
Sin formulario web, sin copiar y pegar, sin desfase entre tus datos maestros y tus pasaportes.
Preguntas frecuentes
¿Necesito una herramienta de códigos QR aparte? No. Cada DPP devuelve un QR GS1 Digital Link en SVG/PNG/PDF/EPS. El QR es el punto de acceso al pasaporte.
¿Puedo actualizar un pasaporte después de imprimir la etiqueta?
Sí — esa es la idea central. El GTIN/número de serie son inmutables, así que la URI impresa sigue siendo válida; todos los campos de datos son actualizables vía PUT /dpp/{id}.
¿Cuántos pasaportes puedo crear a la vez?
Hasta 100 por solicitud POST /dpp/batch. Divide los catálogos más grandes; los límites de tasa se aplican por plan.
¿Qué categorías son compatibles?
battery y textile se entregan hoy con validación completa de la UE; general cubre otros tipos de producto. Battery y textile incluyen una comprobación de cumplimiento de la UE en vivo (ESPR / AGEC).
Fuentes
Empieza gratis y crea tu primer DPP mediante API: app.qr3.app/sign-up
