Automatizácia digitálnych produktových pasov pomocou webhookov

Väčšina tímov vníma digitálny produktový pas ako stránku: vytvoríte ho, vytlačíte QR kód a zabudnete naň. Tým necháte ten najužitočnejší signál nevyužitý. Zakaždým, keď niekto naskenuje QR kód na produkte, ide o udalosť — skutočný človek, v skutočnej krajine, držiaci skutočný kus, v skutočnom okamihu. Prepojte tieto udalosti so svojím technologickým stackom a pas prestane byť statickou stránkou a stane sa front-endom automatizačnej pipeline. Táto príručka ukazuje, ako sa prihlásiť na odber qr.scanned, overiť každý payload a premeniť naskenovania a aktualizácie na reálne pracovné postupy pomocou qr3 SDK.

Prečo je DPP zdrojom udalostí, nie statickou stránkou

Hodnota pasu nespočíva v stránke, ktorú spotrebiteľ uvidí raz. Spočíva v prúde interakcií okolo neho: naskenovania v teréne, zmeny údajov z vášho ERP, prechody v životnom cykle. Každá z nich je niečo, na čo môžu vaše systémy reagovať v reálnom čase.

Webhooky obracajú obvyklý model dotazovania (polling). Namiesto opakovaného otázky „stalo sa niečo?“ na časovači vám qr3 zavolá sám v okamihu, keď sa tak stane. Typy udalostí, ktoré platforma vysiela, zahŕňajú qr.scanned, plus qr.created, qr.updated a qr.deleted pre zmeny v životnom cykle. Tá, ktorú väčšina tímov nevyužíva naplno, je qr.scanned: spustí sa, keď spotrebiteľ, technik alebo colný úradník skutočne naskenuje produkt v teréne.

Payload qr.scanned nesie kontext, ktorý potrebujete na konanie — vrátane krajiny naskenovania a dpp/code id, ktoré identifikuje, ktorý kus bol naskenovaný. To stačí na riadenie analytiky, doplňovania zásob a logiky stiahnutia z trhu bez zásahu človeka.

Prihlásenie na odber qr.scanned

Nasmerujte webhookový endpoint na vašu službu a spracujte udalosť. qr3 SDK obsahuje verifikátor, takže nemusíte ručne parsovať surové telá:

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

Handler je zámerne útly: overte, vetvite podľa event.type, rýchlo potvrďte pomocou 200. Ťažkú prácu (zápisy do analytiky, volania ERP) vykonávajte asynchrónne, aby pomalý downstream nikdy neblokoval potvrdenie.

Overovanie podpisov (verifyWebhook, HMAC-SHA256) — robte to vždy

Webhookový endpoint je verejná URL. Ktokoľvek, kto ju nájde, môže na ňu posielať POST. Ak dôverujete telu bez overenia, kto ho poslal, útočník môže sfalšovať „naskenovania“, spustiť falošné doobjednávky alebo vyvolať falošné príznaky stiahnutia z trhu. Vždy overte podpis skôr, ako budete na payload reagovať.

qr3 podpisuje každý webhook pomocou HMAC-SHA256 nad telom požiadavky, s použitím tajného kľúča vášho endpointu. Podpis prichádza v hlavičke požiadavky qr3-signature. verifyWebhook(body, signature, secret) prepočíta HMAC a porovná ho; ak sa nezhoduje, vyhodí výnimku a vy požiadavku odmietnete:

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

Tri pravidlá, ktoré to udržia poctivé:

• Overujte voči surovým bajtom. Opätovná serializácia JSON môže zmeniť poradie kľúčov a biele znaky, čo naruší HMAC. Zachyťte surové telo (vyššie, express.raw).
• Tajný kľúč udržujte v tajnosti. Žije vo vašom prostredí, nikdy nie v klientskom kóde ani v repozitári.
• Zlyhajte uzavreto (fail closed). Žiadny platný podpis → 401, žiadne vedľajšie účinky. Pri nezhode nikdy „spracovať aj tak“.

Vzory: analytika / doobjednávka / stiahnutie z trhu

Keď udalosti dôverujete, hrstka vzorov pokryje väčšinu toho, čo tímy chcú:

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

• Analytika: agregujte naskenovania podľa krajiny a kusu, aby ste videli reálnu angažovanosť — ktoré trhy skutočne skenujú a ktoré SKU zaznamenávajú najviac popredajných interakcií.
• Doobjednávka / doplnenie zásob: nával naskenovaní v regióne môže napájať dopytové signály alebo spúšťať pracovné postupy doplnenia zásob vo vašom ERP.
• Stiahnutie z trhu / bezpečnosť: ak je kus predmetom stiahnutia z trhu, naskenovanie je príležitosťou osloviť toho, kto ho práve drží — upozornite svoj tím alebo zobrazte oznámenie priamo v pase.

Žiadne z týchto riešení nepotrebuje polling ani nočnú dávku. Dejú sa v okamihu, keď je produkt naskenovaný.

Udržiavanie údajov aktuálnych cez client.dpp.update

Reagovanie na naskenovania je polovica slučky; druhou polovicou je udržiavanie samotného pasu presným. Predpisy ako ESPR (EU 2024/1781) a nariadenie o batériách (EU 2023/1542) očakávajú, že údaje pasu budú odrážať realitu počas životnosti produktu — prepočítaná uhlíková stopa, aktualizované pokyny na opravu, dosiahnuté ciele recyklovaného obsahu.

Tieto aktualizácie riaďte zo systému evidencie (system of record). Keď sa hodnota zmení vo vašom ERP, pošlite ju do pasu:

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

Keďže QR kód kóduje stabilnú resolver URL (https://qr3.app/dpp/{gtin}/{serial}, pridajte ?format=jsonld pre JSON-LD), nikdy nemusíte znovu tlačiť štítok, aby ste zmenili údaje. Identita zostáva pevná; obsah za ňou zostáva aktuálny. Spárujte to s qr.updated a môžete rozosielať notifikáciu zakaždým, keď sa pas zmení — uzatvárate slučku medzi vaším ERP, pasom a kýmkoľvek, kto sleduje downstream.

Tabuľka udalostí: udalosť → čo automatizovať

Začnite s qr.scanned pre angažovanosť a signály z terénu; pridávajte udalosti životného cyklu, keď synchronizujete pasy do svojich širších systémov.

FAQ

Musím overovať podpis, ak je URL môjho endpointu tajná? Áno. URL nie je tajomstvo — uniká v logoch, proxy serveroch a histórii prehliadača. Overenie HMAC pomocou verifyWebhook je jediná vec, ktorá dokazuje, že payload skutočne pochádza z qr3.

Čo sa stane, ak je môj endpoint nedostupný, keď sa spustí udalosť? Po overení rýchlo potvrďte pomocou 200 a pomalú prácu vykonávajte asynchrónne, aby dočasné problémy v downstreame nikdy nepozdržali odpoveď. Udržiavajte vlastnú idempotenciu na dpp/code id, aby sa opakované doručenie nezapočítalo dvakrát.

Môžem aktualizovať GTIN alebo sériové číslo cez client.dpp.update? Nie — GTIN a sériové číslo sú nemenné; sú stabilnou identitou produktu. Aktualizovať možno iba dátové polia. Práve táto nemennosť umožňuje, aby vytlačený QR kód zostal navždy platný.

Zdroje

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

Začnite zadarmo a prepojte svoj prvý DPP webhook: app.qr3.app/sign-up