Useimmat EU:n digitaalista tuotepassia (DPP) käsittelevät artikkelit selittävät, mitä passin on sisällettävä. Paljon harvemmat näyttävät, miten sellainen luodaan — ja lähes mikään ei näytä, miten se tehdään 500 tai 50 000 tuotekoodin (SKU) luettelolle ilman, että lomaketta täytetään 50 000 kertaa klikkaamalla.
Tämä opas on kehittäjän versio. Jokainen alla oleva vaihe on todellinen, toimiva kutsu qr3.app-API:a vastaan (https://qr3.app/v1). Jos hallinnoit tuotetietoja ERP-järjestelmässä, PIM-järjestelmässä tai tietokannassa, voit kytkeä DPP-luonnin suoraan olemassa olevaan putkeesi.
Miksi API on tärkeä DPP:lle
Digitaalinen tuotepassi ei ole kertaluonteinen asiakirja. Kestävien tuotteiden ekologista suunnittelua koskevan asetuksen (ESPR, EU 2024/1781) ja EU:n akkuasetuksen 2023/1542 nojalla jokainen säännelty yksikkö tarvitsee passin, joka pysyy ajan tasalla koko elinkaarensa ajan. Valmistajalle se tarkoittaa:
- Skaala — sadoista kymmeniin tuhansiin tuotteisiin, joista jokaisella on oma GTIN/sarjanumero.
- Tuoreus — tiedot (hiilijalanjälki, kierrätetyn materiaalin osuus, korjaustiedot) muuttuvat ja ne on päivitettävä, ei luotava uudelleen.
- Integraatio — totuuden lähde on ERP/PIM-järjestelmäsi, ei verkkolomake.
Se on API-ongelma. Manuaalinen verkkotyökalu vie sinut kymmeneen ensimmäiseen passiin; API hankkii ne kaikki.
1. Todennus
Jokainen pyyntö käyttää bearer-tunnusta (luo API-avain hallintapaneelissa). Perus-URL on https://qr3.app/v1.
curl https://qr3.app/v1/dpp \
-H "Authorization: Bearer $QR3_API_KEY"
Tai virallisen SDK:n kanssa:
import { QR3 } from "@qr3/sdk";
const client = new QR3({ apiKey: process.env.QR3_API_KEY! });
2. Luo akkupassi
DPP luodaan komennolla POST /dpp. Ylimmän tason kentät ovat samat jokaiselle kategorialle; kategoriakohtaiset tiedot sijoitetaan kenttiin battery_data, textile_data tai 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"]
}
}'
Sama kutsu SDK:n kanssa:
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
Vastaus sisältää kuluttajalle suunnatun aloitussivun (lokalisoituna 25 EU-kielelle) ja GS1 Digital Link -QR-koodin, joka on valmis etikettien tulostukseen — erillistä QR-vaihetta ei tarvita.
3. Validoi ennen luontia
Haluatko napata puuttuvat tai virheelliset kentät ennen tallennusta? POST /dpp/validate suorittaa täsmälleen samat EU:n validointisäännöt luomatta mitään. Ihanteellinen pre-commit-tarkistuksena CI:ssä.
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. Luo koko luettelo eränä
Tuoteluetteloa varten voit lähettää enintään 100 passia per pyyntö osoitteeseen POST /dpp/batch. Käy läpi ERP-vientisi silmukassa, ja koko valikoimasi on valmiina minuuteissa.
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. Hae QR-koodi etikettien tulostukseen
Jokainen passi tarjoaa GS1 Digital Link -QR-koodinsa neljässä tulostusmuodossa. Hae ne passiobjektin kautta tai suoraan:
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 ja qr.eps ovat kaikki saatavilla — SVG/EPS etikettitulostimellesi, PNG verkkoon.
6. Pidä tiedot ajan tasalla (rikkomatta QR-koodia)
GTIN/sarjanumero/erä ovat muuttumattomia luonnin jälkeen — se pitää tulostetun GS1-URI:n pysyvänä ikuisesti. Kaikki muu voidaan päivittää komennolla 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,
},
});
Fyysisessä tuotteessa oleva QR-koodi ei koskaan muutu; sen takana olevat tiedot muuttuvat. Juuri se on dynaamisen passin koko idea.
7. Lähetä EU-rekisteriin
Kun EU:n keskitetty DPP-rekisteri koskee tuotettasi, lähetä passi yhdellä kutsulla (Business-tilaus ja siitä ylöspäin):
const reg = await client.dpp.registerForEuRegistry(passport.id);
console.log(reg.data.eu_registry_status); // "pending"
console.log(reg.data.registry_request_id);
8. Reagoi skannauksiin webhookeilla
DPP-skannaukset ovat tapahtumia. Tilaa qr.scanned, niin voit virrata ne analytiikkaasi, käynnistää uudelleentilauksia tai merkitä takaisinvedon — reaaliajassa. Hyötykuormat on allekirjoitettu (HMAC-SHA256); varmenna aina allekirjoitus.
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);
});
Kaikki yhteen: DPP-luonti CI:ssä
Lopputila, jonka useimmat valmistajat haluavat: tuotetiedot sijaitsevat ERP/PIM-järjestelmässä, ja ajastettu tehtävä pitää passit synkronoituina.
- Vie muuttuneet tuotteet ERP-järjestelmästäsi.
client.dpp.validate(...)jokaiselle — kaada buildi validointivirheisiin.client.dpp.batch(...)uusille tuotteille;client.dpp.update(...)muuttuneille.- Työnnä palautetut
qr.svg-URL-osoitteet etikettitulostusjärjestelmääsi.
Ei verkkolomaketta, ei kopioi-liitä-työtä, ei eroavaisuuksia perustietojesi ja passiesi välillä.
UKK
Tarvitsenko erillisen QR-koodityökalun? En. Jokainen DPP palauttaa GS1 Digital Link -QR-koodin muodoissa SVG/PNG/PDF/EPS. QR on passin käyttöpiste.
Voinko päivittää passia sen jälkeen, kun etiketti on tulostettu?
Kyllä — se on ydinajatus. GTIN/sarjanumero ovat muuttumattomia, joten tulostettu URI pysyy voimassa; kaikki tietokentät ovat päivitettävissä komennolla PUT /dpp/{id}.
Kuinka monta passia voin luoda kerralla?
Enintään 100 per POST /dpp/batch -pyyntö. Pilko suuremmat luettelot osiin; rajoitukset koskevat pyyntömäärää tilauskohtaisesti.
Mitä kategorioita tuetaan?
battery ja textile toimitetaan täydellä EU-validoinnilla jo tänään; general kattaa muut tuotetyypit. Akku ja tekstiili sisältävät reaaliaikaisen EU:n vaatimustenmukaisuustarkistuksen (ESPR / AGEC).
Lähteet
Aloita ilmaiseksi ja luo ensimmäinen DPP:si API:n kautta: app.qr3.app/sign-up
