Digitális termékútlevelek automatizálása webhookokkal

A legtöbb csapat egy digitális termékútlevelet egyszerű oldalként kezel: létrehozzák, kinyomtatják a QR-kódot, majd elfelejtik. Ezzel a leghasznosabb jelet hagyják az asztalon. Minden alkalommal, amikor valaki beolvassa a terméken lévő QR-kódot, az egy esemény – egy valódi ember, egy valódi országban, egy valódi darabot a kezében tartva, egy valódi pillanatban. Kösd be ezeket az eseményeket a technológiai stacked-be, és az útlevél megszűnik statikus oldal lenni, helyette egy automatizálási folyamat előterévé válik. Ez az útmutató megmutatja, hogyan iratkozz fel a qr.scanned eseményre, hogyan ellenőrizz minden payloadot, és hogyan alakítsd valódi munkafolyamatokká a beolvasásokat és frissítéseket a qr3 SDK segítségével.

Miért eseményforrás a DPP, és nem statikus oldal

Egy útlevél értéke nem az az oldal, amelyet a fogyasztó egyszer megnéz. Hanem a körülötte zajló interakciók folyama: a terepen történő beolvasások, az ERP-ből érkező adatváltozások, az életciklus-átmenetek. Mindegyikre valós időben reagálhatnak a rendszereid.

A webhookok megfordítják a szokásos lekérdezéses (polling) modellt. Ahelyett, hogy időzítve azt kérdeznéd, „történt-e valami?", a qr3 hív fel téged abban a pillanatban, amikor valami történik. A platform által kibocsátott eseménytípusok közé tartozik a qr.scanned, valamint a qr.created, qr.updated és qr.deleted az életciklus-változásokhoz. Az, amelyet a legtöbb csapat kihasználatlanul hagy, a qr.scanned: ez akkor sül el, amikor egy fogyasztó, technikus vagy vámtiszt ténylegesen beolvas egy terméket a valós világban.

Egy qr.scanned payload magában hordozza azt a kontextust, amelyre szükséged van a cselekvéshez – beleértve a beolvasás országát és a dpp/code id-t, amely azonosítja, melyik darabot olvasták be. Ez elegendő ahhoz, hogy emberi beavatkozás nélkül vezéreld az analitikát, az utánpótlást és a visszahívási logikát.

Feliratkozás a qr.scanned eseményre

Irányíts egy webhook-végpontot a szolgáltatásodra, és kezeld le az eseményt. A qr3 SDK egy ellenőrzőt (verifier) is tartalmaz, így nem kell kézzel feldolgoznod a nyers törzseket:

import express from "express";
import { verifyWebhook } from "@qr3/sdk";

const app = express();
const secret = process.env.QR3_WEBHOOK_SECRET!;

// Use the raw body so the signature matches the exact bytes qr3 signed.
app.post("/webhooks/qr3", express.raw({ type: "application/json" }), (req, res) => {
  const event = verifyWebhook(req.body, req.headers["qr3-signature"], secret);

  if (event.type === "qr.scanned") {
    // event payload includes fields like the scan country and the dpp/code id
    handleScan(event);
  }

  res.sendStatus(200);
});

A kezelő szándékosan vékony: ellenőrizz, ágazz el az event.type alapján, és nyugtázz gyorsan egy 200-zal. A nehéz munkát (analitikai írások, ERP-hívások) végezd aszinkron módon, hogy egy lassú downstream-rendszer soha ne blokkolja a nyugtázást.

Aláírások ellenőrzése (verifyWebhook, HMAC-SHA256) – ezt mindig tedd meg

Egy webhook-végpont nyilvános URL. Bárki, aki megtalálja, küldhet rá POST-ot. Ha úgy bízol meg a törzsben, hogy nem ellenőrzöd, ki küldte, egy támadó hamis „beolvasásokat" koholhat, megtévesztő utánrendeléseket indíthat, vagy téves visszahívási jelzéseket válthat ki. Mielőtt egy payload alapján cselekszel, mindig ellenőrizd az aláírást.

A qr3 minden webhookot HMAC-SHA256-tal ír alá a kéréstörzs felett, a végpontod titkos kulcsával. Az aláírás a qr3-signature kérésfejlécben érkezik. A verifyWebhook(body, signature, secret) újraszámolja a HMAC-et és összehasonlítja; ha nem egyezik, kivételt dob, te pedig elutasítod a kérést:

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

app.post("/webhooks/qr3", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = verifyWebhook(req.body, req.headers["qr3-signature"], secret);
    process(event);
    res.sendStatus(200);
  } catch {
    // signature mismatch → not from qr3 (or body was altered in transit)
    res.sendStatus(401);
  }
});

Három szabály, amely megőrzi mindezt becsületesnek:

• Ellenőrizz a nyers bájtok ellenében. A JSON újraszerializálása átrendezheti a kulcsokat és megváltoztathatja a szóközöket, ami tönkreteszi a HMAC-et. Kapd el a nyers törzset (fent: express.raw).
• Tartsd titokban a titkos kulcsot. A környezetedben él, soha nem kliensoldali kódban vagy egy repóban.
• Hiba esetén zárj le (fail closed). Nincs érvényes aláírás → 401, semmilyen mellékhatás nélkül. Eltérés esetén soha ne „dolgozd fel mégis".

Mintázatok: analitika / utánrendelés / visszahívás

Ha egyszer megbízol az eseményben, néhány mintázat lefedi a legtöbbet, amire a csapatoknak szüksége van:

function handleScan(event: { type: string; data: { country?: string; dpp_id?: string } }) {
  // 1) Analytics — where and how often are products scanned?
  metrics.increment("dpp.scan", { country: event.data.country });

  // 2) Re-order — a scan can signal consumption or field activity
  if (event.data.country) maybeReplenish(event.data.dpp_id, event.data.country);

  // 3) Recall flag — scans of a flagged unit alert your team
  if (isRecalled(event.data.dpp_id)) alertRecall(event.data.dpp_id, event.data.country);
}

• Analitika: összesítsd a beolvasásokat ország és darab szerint, hogy lásd a valós elköteleződést – mely piacok olvasnak be ténylegesen, és mely SKU-k esetében van a legtöbb értékesítés utáni interakció.
• Utánrendelés / utánpótlás: egy adott régióban tapasztalt beolvasási hullám keresleti jelzéseket táplálhat, vagy újrakészletezési munkafolyamatokat indíthat el az ERP-rendszeredben.
• Visszahívás / biztonság: ha egy darab visszahívás alatt áll, egy beolvasás lehetőség arra, hogy elérd azt, aki éppen birtokolja – riaszd a csapatodat, vagy jeleníts meg egy értesítést magán az útlevélen.

Ezek egyikéhez sem kell lekérdezés vagy éjszakai kötegelt feldolgozás. Abban a pillanatban megtörténnek, amint beolvassák a terméket.

Az adatok naprakészen tartása a client.dpp.update segítségével

A beolvasásokra való reagálás a hurok egyik fele; a másik fele maga az útlevél pontosan tartása. Az olyan szabályozások, mint az ESPR (EU 2024/1781) és az akkumulátor-rendelet (EU 2023/1542), elvárják, hogy az útlevél adatai a termék teljes élettartama során tükrözzék a valóságot – újraszámolt szénlábnyom, frissített javítási utasítások, elért újrahasznosított-tartalom célértékek.

Vezéreld ezeket a frissítéseket a nyilvántartási rendszerből. Amikor egy érték megváltozik az ERP-edben, told ki az útlevélbe:

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

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

// GTIN and serial are immutable; data fields are updatable.
await client.dpp.update(dppId, {
  battery_data: { carbon_footprint_kg: 58, recycled_content_pct: 16 },
});

Mivel a QR-kód egy stabil resolver URL-t kódol (https://qr3.app/dpp/{gtin}/{serial}, JSON-LD-hez add hozzá a ?format=jsonld paramétert), soha nem kell újranyomtatnod egy címkét az adatok módosításához. Az identitás rögzített marad; a mögötte lévő tartalom naprakész. Párosítsd ezt a qr.updated eseménnyel, és szétküldhetsz egy értesítést minden alkalommal, amikor egy útlevél megváltozik – lezárva a hurkot az ERP-d, az útlevél és bárki között, aki downstream figyeli.

Egy eseménytáblázat: esemény → mit automatizálj

Kezdd a qr.scanned eseménnyel az elköteleződéshez és a terepi jelzésekhez; az életciklus-eseményeket akkor add hozzá, amikor az útleveleket beszinkronizálod a tágabb rendszereidbe.

GYIK

Ellenőriznem kell az aláírást, ha a végpontom URL-je titkos? Igen. Egy URL nem titok – kiszivárog a logokból, a proxykból és a böngészési előzményekből. A verifyWebhook-kal végzett HMAC-ellenőrzés az egyetlen, ami bizonyítja, hogy egy payload valóban a qr3-tól érkezett.

Mi történik, ha a végpontom nem elérhető, amikor egy esemény elsül? Nyugtázz gyorsan egy 200-zal, miután ellenőrizted, és a lassú munkát végezd aszinkron módon, hogy az átmeneti downstream-problémák soha ne akasszák meg a választ. Tartsd fenn a saját idempotenciádat a dpp/code id alapján, hogy egy újraküldött kézbesítést ne számolj duplán.

Frissíthetem a GTIN-t vagy a sorozatszámot a client.dpp.update segítségével? Nem – a GTIN és a sorozatszám megváltoztathatatlan; ezek a termék stabil identitása. Csak az adatmezők frissíthetők. Pontosan ez a megváltoztathatatlanság teszi lehetővé, hogy a kinyomtatott QR-kód örökre érvényes maradjon.

Források

• EU ESPR — Regulation (EU) 2024/1781
• EU Battery Regulation 2023/1542
• HMAC — RFC 2104

Kezdd el ingyen, és kösd be az első DPP-webhookodat: app.qr3.app/sign-up