ELi digitaalsete tootepasside loomine API kaudu

Enamik artikleid ELi digitaalse tootepassi (DPP) kohta selgitab, mida pass peab sisaldama. Palju vähem näitab, kuidas seda luua — ja peaaegu mitte ükski ei näita, kuidas teha seda 500 või 50 000 SKU kataloogi jaoks, ilma et peaks 50 000 korda läbi vormi klikkima.

See juhend on arendaja versioon. Iga alljärgnev samm on reaalne töötav päring qr3.app API vastu (https://qr3.app/v1). Kui haldad tooteandmeid ERP-s, PIM-is või andmebaasis, saad DPP loomise ühendada otse oma olemasolevasse torujuhtmesse.

Miks on API DPP-de jaoks oluline

Digitaalne tootepass ei ole ühekordne dokument. Säästvate toodete ökodisaini määruse (ESPR, EU 2024/1781) ja ELi akumääruse 2023/1542 alusel vajab iga reguleeritud üksus passi, mis püsib ajakohasena kogu oma eluea jooksul. Tootja jaoks tähendab see:

Mastaap — sadu kuni kümneid tuhandeid tooteid, igaüks oma GTIN-i/seerianumbriga.
Värskus — andmed (süsiniku jalajälg, ringlussevõetud materjali osakaal, remondiinfo) muutuvad ning neid tuleb uuendada, mitte uuesti luua.
Integratsioon — tõeallikas on sinu ERP/PIM, mitte veebivorm.

See on API probleem. Käsitsi veebitööriist annab sulle esimesed kümme passi; API annab need kõik.

1. Autentimine

Iga päring kasutab bearer-tokenit (loo API võti juhtpaneelis). Baas-URL on https://qr3.app/v1.

curl https://qr3.app/v1/dpp \
  -H "Authorization: Bearer $QR3_API_KEY"

Või ametliku SDK-ga:

import { QR3 } from "@qr3/sdk";

const client = new QR3({ apiKey: process.env.QR3_API_KEY! });

2. Akupassi loomine

DPP luuakse käsuga POST /dpp. Ülataseme väljad on iga kategooria puhul samad; kategooriapõhised andmed lähevad battery_data, textile_data või general_data sisse.

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 päring SDK-ga:

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

Vastus sisaldab tarbijale suunatud sihtlehte (lokaliseeritud 25 ELi keelde) ja sildiprintimiseks valmis GS1 Digital Link QR-koodi — eraldi QR-sammu ei ole vaja.

3. Valideeri enne loomist

Soovid püüda puuduvad või kehtetud väljad enne salvestamist? POST /dpp/validate käivitab täpselt samad ELi valideerimisreeglid, ilma midagi loomata. Ideaalne eelkontroll CI-s.

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. Loo partiina terve kataloog

Tootekataloogi jaoks saada kuni 100 passi päringu kohta aadressile POST /dpp/batch. Itereeri oma ERP-ekspordi üle ja saad kogu oma valiku minutitega.

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. QR-koodi hankimine sildiprintimiseks

Iga pass avab oma GS1 Digital Link QR-koodi neljas prindiformaadis. Tõmba need passi objekti kaudu või otse:

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 on kõik saadaval — SVG/EPS sinu sildiprinterile, PNG veebi jaoks.

6. Hoia andmed ajakohasena (QR-koodi rikkumata)

GTIN/seerianumber/partii on pärast loomist muutumatud — see hoiab prinditud GS1 URI igavesti stabiilsena. Kõike muud saab uuendada käsuga 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-kood füüsilisel tootel ei muutu kunagi; selle taga olevad andmed muutuvad. Just selles on dünaamilise passi mõte.

7. Esita ELi registrisse

Kui ELi keskne DPP-register on sinu toote jaoks asjakohane, esita pass ühe päringuga (Business-plaan ja kõrgem):

const reg = await client.dpp.registerForEuRegistry(passport.id);
console.log(reg.data.eu_registry_status);          // "pending"
console.log(reg.data.registry_request_id);

8. Reageeri skannimistele webhook'idega

DPP skannimised on sündmused. Telli qr.scanned ja saad neid voogesitada oma analüütikasse, käivitada tellimusi või märgistada tagasikutsumise — reaalajas. Andmekoormused on allkirjastatud (HMAC-SHA256); kontrolli alati allkirja.

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);
});

Kõik kokku: DPP genereerimine CI-s

Lõppseisund, mida enamik tootjaid soovib: tooteandmed asuvad ERP-s/PIM-is ning ajastatud töö hoiab passid sünkroonis.

Ekspordi muutunud tooted oma ERP-st.
client.dpp.validate(...) igaühe jaoks — laske valideerimisvigade korral ehitus ebaõnnestuda.
client.dpp.batch(...) uute toodete jaoks; client.dpp.update(...) muutunute jaoks.
Lükka tagastatud qr.svg URL-id oma sildiprintimise süsteemi.

Ei mingit veebivormi, ei mingit kopeeri-kleebi, ei mingit erinevust sinu põhiandmete ja passide vahel.

KKK

Kas mul on vaja eraldi QR-koodi tööriista? Ei. Iga DPP tagastab GS1 Digital Link QR-koodi formaadis SVG/PNG/PDF/EPS. QR-kood ongi passile juurdepääsupunkt.

Kas ma saan passi uuendada pärast sildi printimist? Jah — see on põhiidee. GTIN/seerianumber on muutumatud, nii et prinditud URI jääb kehtima; kõiki andmevälju saab uuendada käsuga PUT /dpp/{id}.

Mitu passi saan korraga luua? Kuni 100 ühe POST /dpp/batch päringu kohta. Tükelda suuremad kataloogid; päringusagedusele kehtivad piirangud plaani kaupa.

Milliseid kategooriaid toetatakse? battery ja textile on täna saadaval täieliku ELi valideerimisega; general katab muud tootetüübid. Aku ja tekstiil sisaldavad reaalajas ELi vastavuskontrolli (ESPR / AGEC).

Allikad

Alusta tasuta ja loo oma esimene DPP API kaudu: app.qr3.app/sign-up