Avtomatizacija digitalnih potnih listov izdelkov s spletnimi kljukami (webhooki)

Večina ekip obravnava digitalni potni list izdelka (DPP) kot stran: ustvarite ga, natisnete kodo QR in pozabite nanj. Pri tem ostane najkoristnejši signal neizkoriščen. Vsakič, ko nekdo skenira kodo QR na izdelku, je to dogodek — resnična oseba, v resnični državi, ki drži resnično enoto, v resničnem trenutku. Te dogodke povežite s svojim tehnološkim sklopom in potni list preneha biti statična stran ter postane vmesnik (front end) cevovoda za avtomatizacijo. Ta vodnik prikazuje, kako se naročiti na qr.scanned, preveriti vsako vsebino (payload) ter skeniranja in posodobitve spremeniti v resnične poteke dela s SDK-jem qr3.

Zakaj je DPP vir dogodkov in ne statična stran

Vrednost potnega lista ni stran, ki jo potrošnik enkrat vidi. Je tok interakcij okoli njega: skeniranja na terenu, spremembe podatkov iz vašega sistema ERP, prehodi v življenjskem ciklu. Vsak od njih je nekaj, na kar se lahko vaši sistemi odzovejo v realnem času.

Webhooki obrnejo običajni model poizvedovanja (polling). Namesto da bi v časovnih intervalih spraševali "se je kaj zgodilo?", qr3 pokliče vas v trenutku, ko se zgodi. Vrste dogodkov, ki jih platforma oddaja, vključujejo qr.scanned, poleg tega pa še qr.created, qr.updated in qr.deleted za spremembe v življenjskem ciklu. Tisti, ki ga večina ekip premalo izkorišča, je qr.scanned: sproži se, ko potrošnik, tehnik ali carinik dejansko skenira izdelek na terenu.

Vsebina (payload) qr.scanned nosi kontekst, ki ga potrebujete za ukrepanje — vključno z državo skeniranja in id-jem dpp/code, ki določa, katera enota je bila skenirana. To zadošča za poganjanje analitike, dopolnjevanja zalog in logike odpoklica brez človeka v zanki.

Naročanje na qr.scanned

Usmerite končno točko webhooka na svojo storitev in obravnavajte dogodek. SDK qr3 vsebuje preveritelja, tako da vam ni treba ročno razčlenjevati surovih teles zahtevkov:

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

Obravnavalnik (handler) je namenoma vitek: preverite, vejite glede na event.type in hitro potrdite s 200. Težko delo (zapisi v analitiko, klici v ERP) opravite asinhrono, tako da počasen nadaljnji sistem nikoli ne blokira potrditve.

Preverjanje podpisov (verifyWebhook, HMAC-SHA256) — to počnite vedno

Končna točka webhooka je javni URL. Vsakdo, ki jo najde, lahko nanjo pošlje zahtevek POST. Če telesu zahtevka zaupate brez preverjanja, kdo ga je poslal, lahko napadalec ponaredi "skeniranja", sproži lažna ponovna naročila ali sproži lažna opozorila o odpoklicu. Preden ukrepate na podlagi vsebine (payload), vedno preverite podpis.

qr3 vsak webhook podpiše s HMAC-SHA256 nad telesom zahtevka, pri čemer uporabi skrivnost vaše končne točke. Podpis prispe v glavi zahtevka qr3-signature. verifyWebhook(body, signature, secret) ponovno izračuna HMAC in ga primerja; če se ne ujema, vrže izjemo, vi pa zahtevek zavrnete:

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 pravila, ki to ohranjajo pošteno:

• Preverjajte glede na surove bajte. Ponovna serializacija JSON lahko spremeni vrstni red ključev in presledke, kar pokvari HMAC. Zajemite surovo telo (zgoraj, express.raw).
• Ohranite skrivnost skrivno. Živi v vašem okolju, nikoli v odjemalski kodi ali repozitoriju.
• Zaprite ob napaki (fail closed). Brez veljavnega podpisa → 401, brez stranskih učinkov. Nikoli "vseeno obdelaj" ob neujemanju.

Vzorci: analitika / ponovno naročilo / odpoklic

Ko dogodku zaupate, peščica vzorcev pokrije večino tistega, kar ekipe želijo:

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: združujte skeniranja po državi in enoti, da vidite resnično vključenost — kateri trgi dejansko skenirajo in katere artikle (SKU) je največ interakcij po nakupu.
• Ponovno naročilo / dopolnjevanje zalog: sunek skeniranj v neki regiji lahko napaja signale povpraševanja ali sproži poteke dela za obnovo zalog v vašem sistemu ERP.
• Odpoklic / varnost: če je enota v odpoklicu, je skeniranje priložnost, da dosežete tistega, ki jo drži — opozorite svojo ekipo ali prikažite obvestilo na samem potnem listu.

Nič od tega ne potrebuje poizvedovanja ali nočne paketne obdelave. Zgodi se v trenutku, ko je izdelek skeniran.

Vzdrževanje aktualnosti podatkov prek client.dpp.update

Odzivanje na skeniranja je polovica zanke; druga polovica je vzdrževanje samega potnega lista točnega. Predpisi, kot sta ESPR (EU 2024/1781) in Uredba o baterijah (EU 2023/1542), pričakujejo, da bodo podatki potnega lista odražali resničnost skozi življenjsko dobo izdelka — ponovno izračunan ogljični odtis, posodobljena navodila za popravilo, doseženi cilji glede reciklirane vsebine.

Te posodobitve poganjajte iz sistema zapisov (system of record). Ko se vrednost spremeni v vašem sistemu ERP, jo potisnite v potni list:

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

Ker koda QR kodira stabilen URL razreševalnika (https://qr3.app/dpp/{gtin}/{serial}, za JSON-LD dodajte ?format=jsonld), za spremembo podatkov nikoli ne ponatisnete etikete. Identiteta ostaja nespremenjena; vsebina za njo ostaja aktualna. To združite z qr.updated in lahko razpošljete obvestilo vsakič, ko se potni list spremeni — s čimer sklenete zanko med vašim sistemom ERP, potnim listom in vsemi, ki spremljajo navzdol po toku.

Tabela dogodkov: dogodek → kaj avtomatizirati

Začnite z qr.scanned za vključenost in terenske signale; dodajte dogodke življenjskega cikla, ko boste potne liste sinhronizirali v svoje širše sisteme.

Pogosta vprašanja

Ali moram preveriti podpis, če je URL moje končne točke skrivnost? Da. URL ni skrivnost — uhaja v dnevnike, posrednike (proxy) in zgodovino brskalnika. Preverjanje HMAC z verifyWebhook je edino, kar dokaže, da je vsebina (payload) dejansko prišla od qr3.

Kaj se zgodi, če moja končna točka ne deluje, ko se sproži dogodek? Hitro potrdite s 200, ko ste preverili, počasno delo pa opravite asinhrono, tako da prehodne težave navzdol po toku nikoli ne zaustavijo odziva. Ohranite svojo lastno idempotentnost na id-ju dpp/code, tako da ponovno dostavljena dostava ni dvojno šteta.

Ali lahko prek client.dpp.update posodobim GTIN ali serijsko številko? Ne — GTIN in serijska številka sta nespremenljiva; sta stabilna identiteta izdelka. Posodobljiva so samo podatkovna polja. Prav ta nespremenljivost je tisto, kar omogoča, da natisnjena koda QR ostane veljavna za vedno.

Viri

• EU ESPR — Uredba (EU) 2024/1781
• Uredba EU o baterijah 2023/1542
• HMAC — RFC 2104

Začnite brezplačno in povežite svoj prvi webhook za DPP: app.qr3.app/sign-up