Večina člankov o EU digitalnem potnem listu izdelka (DPP) pojasnjuje, kaj mora potni list vsebovati. Veliko manj jih pokaže, kako ga ustvariti — in skoraj nobeden ne pokaže, kako to storiti za katalog s 500 ali 50.000 SKU-ji, ne da bi 50.000-krat klikali skozi obrazec.
Ta vodič je različica za razvijalce. Vsak korak spodaj je resničen, delujoč klic proti API-ju qr3.app (https://qr3.app/v1). Če podatke o izdelkih upravljate v ERP-ju, PIM-u ali podatkovni bazi, lahko generiranje DPP vključite neposredno v svoj obstoječi cevovod.
Zakaj je API pomemben za DPP-je
Digitalni potni list izdelka ni enkraten dokument. V okviru Uredbe o okoljsko primerni zasnovi trajnostnih izdelkov (ESPR, EU 2024/1781) in EU uredbe o baterijah 2023/1542 vsaka regulirana enota potrebuje potni list, ki ostane aktualen skozi vso svojo življenjsko dobo. Za proizvajalca to pomeni:
- Obseg — od stotin do desettisočev izdelkov, vsak s svojim GTIN/serijsko številko.
- Aktualnost — podatki (ogljični odtis, delež recikliranega materiala, informacije o popravilih) se spreminjajo in jih je treba posodabljati, ne pa ustvarjati znova.
- Integracija — vir resnice je vaš ERP/PIM, ne spletni obrazec.
To je problem za API. Ročno spletno orodje vam priskrbi prvih deset potnih listov; API jih priskrbi vse.
1. Avtentikacija
Vsaka zahteva uporablja žeton bearer (API-ključ ustvarite v nadzorni plošči). Osnovni URL je https://qr3.app/v1.
curl https://qr3.app/v1/dpp \
-H "Authorization: Bearer $QR3_API_KEY"
Ali z uradnim SDK-jem:
import { QR3 } from "@qr3/sdk";
const client = new QR3({ apiKey: process.env.QR3_API_KEY! });
2. Ustvarjanje potnega lista za baterijo
DPP ustvarite z POST /dpp. Polja na najvišji ravni so enaka za vsako kategorijo; podatki, specifični za kategorijo, gredo v battery_data, textile_data ali 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"]
}
}'
Isti klic s SDK-jem:
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
Odgovor vključuje pristajalno stran za potrošnike (lokalizirano v 25 jezikov EU) in GS1 Digital Link QR-kodo, pripravljeno za tiskanje na nalepke — ločen korak za QR ni potreben.
3. Validacija pred ustvarjanjem
Želite ujeti manjkajoča ali neveljavna polja, preden jih shranite? POST /dpp/validate izvede natanko ista pravila validacije EU, ne da bi karkoli ustvaril. Idealno kot pred-commit preverjanje v 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. Paketno ustvarjanje celotnega kataloga
Za katalog izdelkov pošljite do 100 potnih listov na zahtevo na POST /dpp/batch. Pojdite v zanki čez izvoz iz ERP-ja in v nekaj minutah imate celoten asortiman.
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. Pridobivanje QR-kode za tiskanje nalepk
Vsak potni list izpostavi svojo GS1 Digital Link QR-kodo v štirih formatih za tisk. Pridobite jih prek objekta potnega lista ali neposredno:
curl https://qr3.app/v1/dpp/dpp_xxxxxxxx/qr.svg \
-H "Authorization: Bearer $QR3_API_KEY" -o label.svg
Na voljo so qr.svg, qr.png, qr.pdf in qr.eps — SVG/EPS za vaš tiskalnik nalepk, PNG za splet.
6. Ohranjanje aktualnosti podatkov (brez kvarjenja QR-kode)
GTIN/serijska številka/serija (lot) so po ustvarjanju nespremenljivi — to ohranja natisnjeni GS1 URI za vedno stabilen. Vse drugo je mogoče posodobiti z 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,
},
});
QR-koda na fizičnem izdelku se nikoli ne spremeni; podatki za njo pa se. V tem je celotno bistvo dinamičnega potnega lista.
7. Oddaja v register EU
Ko je za vaš izdelek v obsegu centralni register DPP EU, oddajte potni list z enim klicem (od paketa Business naprej):
const reg = await client.dpp.registerForEuRegistry(passport.id);
console.log(reg.data.eu_registry_status); // "pending"
console.log(reg.data.registry_request_id);
8. Odzivanje na skeniranja z webhooki
Skeniranja DPP so dogodki. Naročite se na qr.scanned in jih lahko v realnem času pretakate v svojo analitiko, sprožite ponovna naročila ali označite odpoklic. Vsebine (payloads) so podpisane (HMAC-SHA256); vedno preverite podpis.
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);
});
Vse skupaj: generiranje DPP v CI
Končno stanje, ki ga želi večina proizvajalcev: podatki o izdelkih živijo v ERP-ju/PIM-u, načrtovano opravilo pa ohranja potne liste sinhronizirane.
- Izvozite spremenjene izdelke iz svojega ERP-ja.
client.dpp.validate(...)za vsakega — gradnja naj ne uspe ob napakah validacije.client.dpp.batch(...)za nove izdelke;client.dpp.update(...)za spremenjene.- Vrnjene URL-je
qr.svgpotisnite v svoj sistem za tiskanje nalepk.
Brez spletnega obrazca, brez kopiranja in lepljenja, brez razhajanj med vašimi matičnimi podatki in potnimi listi.
Pogosta vprašanja
Ali potrebujem ločeno orodje za QR-kode? Ne. Vsak DPP vrne GS1 Digital Link QR-kodo v SVG/PNG/PDF/EPS. QR-koda je dostopna točka do potnega lista.
Ali lahko posodobim potni list, potem ko je nalepka že natisnjena?
Da — to je osrednja zamisel. GTIN/serijska številka sta nespremenljiva, tako da natisnjeni URI ostane veljaven; vsa podatkovna polja je mogoče posodobiti prek PUT /dpp/{id}.
Koliko potnih listov lahko ustvarim naenkrat?
Do 100 na zahtevo POST /dpp/batch. Večje kataloge razdelite na dele; omejitve hitrosti veljajo glede na paket.
Katere kategorije so podprte?
battery in textile danes vključujeta polno EU-validacijo; general pokriva druge vrste izdelkov. Baterija in tekstil vključujeta sprotno preverjanje skladnosti z EU (ESPR / AGEC).
Viri
Začnite brezplačno in ustvarite svoj prvi DPP prek API-ja: app.qr3.app/sign-up
