--- title: "Gerar Passaportes Digitais de Produto da UE via API — qr3.app Blog" description: "A maioria dos guias sobre DPP diz-lhe o que um passaporte tem de conter. Este mostra como criar Passaportes Digitais de Produto em conformidade com a UE de forma programática — com curl, o SDK do qr3, criação em lote, validação, códigos QR GS1 e webhooks." canonical: "https://qr3.app/pt/blog/dpp-api-generate-passports/" lang: "pt" robots: "index,follow,max-image-preview:large,max-snippet:-1" --- # Gerar Passaportes Digitais de Produto da UE via API — qr3.app Blog > A maioria dos guias sobre DPP diz-lhe o que um passaporte tem de conter. Este mostra como criar Passaportes Digitais de Produto em conformidade com a UE de forma programática — com curl, o SDK do qr3, criação em lote, validação, códigos QR GS1 e webhooks. Canonical: [← Blog](/pt/blog/) [Tutoriais](/pt/blog/category/tutorials/) 30 de maio de 2026 4 min de leitura [Tutoriais](/pt/blog/category/tutorials/) [dpp](/pt/blog/tag/dpp/)[api](/pt/blog/tag/api/)[gs1-digital-link](/pt/blog/tag/gs1-digital-link/)[developers](/pt/blog/tag/developers/)[eu-2024-1781](/pt/blog/tag/eu-2024-1781/) # Gerar Passaportes Digitais de Produto da UE via API A maioria dos guias sobre DPP diz-lhe o que um passaporte tem de conter. Este mostra como criar Passaportes Digitais de Produto em conformidade com a UE de forma programática — com curl, o SDK do qr3, criação em lote, validação, códigos QR GS1 e webhooks. por **QR3 Redaktion** ![Gerar Passaportes Digitais de Produto da UE via API](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/dpp-api-generate-passports/hero.png) 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)](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R1781) e do [Regulamento das Baterias da UE 2023/1542](https://eur-lex.europa.eu/eli/reg/2023/1542/oj), 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); ``` > **Estado atual:** A UE ainda não publicou a API do seu registo central de DPP. Até lá, esta chamada é um caminho de teste — o estado permanece `pending` e nenhuma autoridade recebe o passaporte. Assim que a API estiver ativa, a mesma chamada passará a ser o registo real. ## 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 { 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); }); ``` ## 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. 1. Exporte os produtos alterados do seu ERP. 2. `client.dpp.validate(...)` cada um — faça a build falhar em caso de erros de validação. 3. `client.dpp.batch(...)` para novos produtos; `client.dpp.update(...)` para os alterados. 4. Envie os URLs `qr.svg` devolvidos 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; o limite é de 60 pedidos por minuto por chave de API, em todos os planos. **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 - [ESPR — Regulamento (UE) 2024/1781](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R1781) - [Regulamento das Baterias da UE 2023/1542](https://eur-lex.europa.eu/eli/reg/2023/1542/oj) - [GS1 Digital Link](https://www.gs1.org/standards/gs1-digital-link) **Comece gratuitamente** e crie o seu primeiro DPP via API: [app.qr3.app/sign-up](https://app.qr3.app/sign-up) ## Artigos relacionados - [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/gs1-resolver-test-suite-dpp-links/hero.png) Tutoriais Suíte de testes do Resolver GS1: verificar a robustez dos DPP-Links antes do go-live A suíte de testes GS1 estável permite verificar o Resolver 1.2. Teste redirecionamentos, conjuntos de links, CORS, idiomas e casos de erro antes do go-live.](/pt/blog/gs1-resolver-test-suite-dpp-links/) - [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/dpp-battery-passport-2027-20260715/hero.png) Notícias do setor BatteryPass-Ready lança ambiente de testes para o Passaporte Digital de Baterias O consórcio BatteryPass-Ready lançou, em 24 de junho de 2026, um ambiente público de testes para o Passaporte Digital de Baterias, tendo em vista a obrigação da UE a partir de fevereiro de 2027.](/pt/blog/dpp-battery-passport-2027-20260715/) - [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/sector-20260713/hero.png) Notícias do setor Passaporte Digital de Baterias 2027: o que os fabricantes precisam saber agora Webinars, ferramentas de código aberto e novas normas: o passaporte de baterias da UE ganha impulso. Uma visão geral da situação em julho de 2026 e das questões em aberto até fevereiro de 2027.](/pt/blog/sector-20260713/) - [![](https://qr3-blog-agent.meistern.workers.dev/cdn/blog/sector-20260711/hero.png) Notícias do setor Passaporte Digital de Baterias 2026: ambientes de teste, normas e questões em aberto Em que ponto está a indústria com o Passaporte Digital de Baterias? Uma visão geral dos ambientes de teste, das normas CEN/CENELEC, das ferramentas de código aberto e das decisões regulatórias em 202.](/pt/blog/sector-20260711/) [← Todos os artigos](/pt/blog/) [Começar gratuitamente](https://app.qr3.app/sign-up)