A maioria dos artigos sobre o Passaporte Digital de Produto (DPP) da UE explica o que um passaporte tem de conter. Muito menos mostram como criar um — e quase nenhum mostra como fazê-lo para um catálogo de 500 ou 50 000 SKUs sem clicar num formulário 50 000 vezes.
Este guia é a versão para programadores. Cada passo abaixo é uma chamada real e funcional contra a API do qr3.app (https://qr3.app/v1). Se gere dados de produtos num ERP, num PIM ou numa base de dados, pode ligar a geração de DPP diretamente ao seu pipeline existente.
Porque é que uma API importa para os DPP
Um Passaporte Digital de Produto não é um documento pontual. Ao abrigo do Regulamento Conceção Ecológica para Produtos Sustentáveis (ESPR, UE 2024/1781) e do Regulamento das Baterias da UE 2023/1542, cada unidade regulada precisa de um passaporte que se mantenha atualizado ao longo de toda a sua vida útil. Para um fabricante, isso significa:
- Escala — de centenas a dezenas de milhares de produtos, cada um com o seu próprio GTIN/número de série.
- Atualidade — os dados (pegada de carbono, conteúdo reciclado, informações de reparação) mudam e têm de ser atualizados, não recriados.
- Integração — a fonte da verdade é o seu ERP/PIM, não um formulário web.
Isso é um problema de API. Uma ferramenta web manual leva-o aos primeiros dez passaportes; uma API leva-o a todos eles.
1. Autenticação
Cada pedido usa um token bearer (crie uma chave de API no painel de controlo). O URL base é https://qr3.app/v1.
curl https://qr3.app/v1/dpp \
-H "Authorization: Bearer $QR3_API_KEY"
Ou com o SDK oficial:
import { QR3 } from "@qr3/sdk";
const client = new QR3({ apiKey: process.env.QR3_API_KEY! });
2. Criar um passaporte de bateria
Um DPP é criado com POST /dpp. Os campos de nível superior são os mesmos para cada categoria; os dados específicos da categoria vão para 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"]
}
}'
A mesma chamada com o 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
A resposta inclui uma página de destino virada para o consumidor (localizada em 25 línguas da UE) e um código QR GS1 Digital Link pronto para impressão de etiquetas — não é necessário um passo de QR separado.
3. Validar antes de criar
Quer detetar campos em falta ou inválidos antes de persistir? POST /dpp/validate executa as regras exatas de validação da UE sem criar nada. Ideal como verificação de pré-commit em 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. Criar um catálogo inteiro em lote
Para um catálogo de produtos, envie até 100 passaportes por pedido para POST /dpp/batch. Percorra a exportação do seu ERP num ciclo e tem toda a sua gama em 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,
},
}));
// Chunk into batches of 100
const result = await client.dpp.batch({ items: items.slice(0, 100) });
5. Obter o código QR para impressão de etiquetas
Cada passaporte expõe o seu QR GS1 Digital Link em quatro formatos de impressão. Obtenha-os através do objeto do passaporte ou diretamente:
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 estão todos disponíveis — SVG/EPS para a sua impressora de etiquetas, PNG para a web.
6. Manter os dados atualizados (sem quebrar o QR)
O GTIN/número de série/lote são imutáveis após a criação — isso mantém o URI GS1 impresso estável para sempre. Tudo o resto pode ser atualizado com 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,
},
});
O QR no produto físico nunca muda; os dados por trás dele mudam. É esse precisamente o objetivo de um passaporte dinâmico.
7. Submeter ao registo da UE
Quando o registo central de DPP da UE for aplicável ao seu produto, submeta um passaporte com uma única chamada (plano Business e superiores):
const reg = await client.dpp.registerForEuRegistry(passport.id);
console.log(reg.data.eu_registry_status); // "pending"
console.log(reg.data.registry_request_id);
8. Reagir a leituras com webhooks
As leituras de DPP são eventos. Subscreva qr.scanned e pode transmiti-las para as suas análises, despoletar reabastecimentos ou sinalizar um recall — em tempo real. Os payloads são assinados (HMAC-SHA256); verifique sempre a assinatura.
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);
});
Juntando tudo: geração de DPP em CI
O estado final que a maioria dos fabricantes pretende: os dados dos produtos residem no ERP/PIM e uma tarefa agendada mantém os passaportes sincronizados.
- Exporte os produtos alterados do seu ERP.
client.dpp.validate(...)cada um — faça a build falhar em caso de erros de validação.client.dpp.batch(...)para novos produtos;client.dpp.update(...)para os alterados.- Envie os URLs
qr.svgdevolvidos para o seu sistema de impressão de etiquetas.
Sem formulário web, sem copy-paste, sem divergência entre os seus dados-mestre e os seus passaportes.
FAQ
Preciso de uma ferramenta de código QR separada? Não. Cada DPP devolve um QR GS1 Digital Link em SVG/PNG/PDF/EPS. O QR é o ponto de acesso ao passaporte.
Posso atualizar um passaporte depois de a etiqueta estar impressa?
Sim — essa é a ideia central. O GTIN/número de série são imutáveis, por isso o URI impresso permanece válido; todos os campos de dados são atualizáveis via PUT /dpp/{id}.
Quantos passaportes posso criar de uma só vez?
Até 100 por pedido POST /dpp/batch. Divida catálogos maiores em blocos; aplicam-se limites de taxa por plano.
Que categorias são suportadas?
battery e textile já incluem hoje a validação completa da UE; general abrange outros tipos de produtos. Bateria e têxtil incluem uma verificação de conformidade da UE ao vivo (ESPR / AGEC).
Fontes
Comece gratuitamente e crie o seu primeiro DPP via API: app.qr3.app/sign-up
