Skaitmeninių produkto pasų automatizavimas su Webhooks

Dauguma komandų skaitmeninį produkto pasą laiko paprastu puslapiu: jį sukuriate, atsispausdinate QR ir pamirštate. Taip lieka nepanaudotas pats naudingiausias signalas. Kiekvieną kartą, kai kas nors nuskaito QR ant produkto, tai yra įvykis – realus žmogus, realioje šalyje, laikantis realų vienetą, realiu momentu. Sujunkite tuos įvykius su savo sistema ir pasas nustoja būti statiniu puslapiu, o tampa automatizavimo proceso priekine dalimi. Šiame vadove parodoma, kaip prenumeruoti qr.scanned, patikrinti kiekvieną naudingąją apkrovą ir paversti nuskaitymus bei atnaujinimus realiais darbo srautais naudojant qr3 SDK.

Kodėl DPP yra įvykių šaltinis, o ne statinis puslapis

Paso vertė nėra tas puslapis, kurį vartotojas pamato vieną kartą. Tai yra aplink jį vykstančių sąveikų srautas: nuskaitymai laukuose, duomenų pakeitimai iš jūsų ERP, gyvavimo ciklo perėjimai. Į kiekvieną jūsų sistemos gali reaguoti realiuoju laiku.

Webhooks apverčia įprastą apklausos modelį. Užuot pagal laikmatį klausus „ar kas nors įvyko?", qr3 paskambina jums tą pačią akimirką, kai tai įvyksta. Platformos skleidžiamų įvykių tipai apima qr.scanned, taip pat qr.created, qr.updated ir qr.deleted gyvavimo ciklo pakeitimams. Tas, kurį dauguma komandų nepakankamai išnaudoja, yra qr.scanned: jis suaktyvinamas, kai vartotojas, technikas ar muitinės pareigūnas iš tikrųjų nuskaito produktą realiomis sąlygomis.

qr.scanned naudingoji apkrova perduoda kontekstą, kurio jums reikia veikti, – įskaitant nuskaitymo šalį ir dpp/code id, kuris identifikuoja, kuris vienetas buvo nuskaitytas. To pakanka analitikai, papildymui ir atšaukimo logikai valdyti be žmogaus įsikišimo.

Prenumeravimas prie qr.scanned

Nukreipkite webhook galinį tašką į savo paslaugą ir apdorokite įvykį. qr3 SDK pateikia tikrinimo įrankį, todėl jums nereikia neapdorotų kūnų analizuoti rankomis:

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

Tvarkytuvas tyčia yra plonas: patikrinkite, šakokite pagal event.type, greitai patvirtinkite su 200. Sunkų darbą (analitikos įrašus, ERP iškvietimus) atlikite asinchroniškai, kad lėtas tolesnis komponentas niekada nestabdytų patvirtinimo.

Parašų tikrinimas (verifyWebhook, HMAC-SHA256) – darykite tai visada

Webhook galinis taškas yra viešas URL. Bet kas, kas jį suras, gali į jį siųsti POST. Jei pasitikite kūnu netikrindami, kas jį atsiuntė, užpuolikas gali suklastoti „nuskaitymus", suaktyvinti netikrus pakartotinius užsakymus arba paleisti klaidingas atšaukimo žymas. Visada patikrinkite parašą prieš veikdami pagal naudingąją apkrovą.

qr3 pasirašo kiekvieną webhook su HMAC-SHA256 virš užklausos kūno, naudodama jūsų galinio taško paslaptį. Parašas atkeliauja qr3-signature užklausos antraštėje. verifyWebhook(body, signature, secret) perskaičiuoja HMAC ir jį palygina; jei jis nesutampa, jis meta išimtį ir jūs atmetate užklausą:

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

Trys taisyklės, kurios palaiko tai sąžiningai:

• Tikrinkite pagal neapdorotus baitus. Pakartotinis JSON serializavimas gali pakeisti raktų tvarką ir tarpus, o tai sugadina HMAC. Užfiksuokite neapdorotą kūną (aukščiau, express.raw).
• Laikykite paslaptį paslaptyje. Ji gyvena jūsų aplinkoje, niekada ne kliento kode ar saugykloje.
• Atmeskite uždarytu būdu. Nėra galiojančio parašo → 401, jokio šalutinio poveikio. Niekada „vis tiek neapdorokite" esant nesutapimui.

Šablonai: analitika / pakartotinis užsakymas / atšaukimas

Kai pasitikite įvykiu, keletas šablonų apima daugumą to, ko komandos nori:

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: sumuokite nuskaitymus pagal šalį ir vienetą, kad pamatytumėte realaus pasaulio įsitraukimą – kurios rinkos iš tikrųjų nuskaito ir kurie SKU sulaukia daugiausiai sąveikos po pardavimo.
• Pakartotinis užsakymas / papildymas: nuskaitymų pliūpsnis regione gali maitinti paklausos signalus arba suaktyvinti atsargų papildymo darbo srautus jūsų ERP.
• Atšaukimas / sauga: jei vienetas yra atšaukiamas, nuskaitymas yra proga pasiekti tą, kas jį laiko – įspėkite savo komandą arba pateikite pranešimą pačiame pase.

Nė vienam iš jų nereikia apklausos ar naktinio paketo. Jie įvyksta tą akimirką, kai produktas nuskaitomas.

Duomenų atnaujinimas naudojant client.dpp.update

Reagavimas į nuskaitymus yra pusė ciklo; kita pusė yra paties paso tikslumo palaikymas. Reglamentai, tokie kaip ESPR (ES 2024/1781) ir Baterijų reglamentas (ES 2023/1542), tikisi, kad paso duomenys atspindės tikrovę visą produkto gyvavimo laiką – perskaičiuotą anglies pėdsaką, atnaujintas remonto instrukcijas, pasiektus perdirbtų medžiagų kiekio tikslus.

Valdykite tuos atnaujinimus iš įrašų sistemos. Kai reikšmė pasikeičia jūsų ERP, perduokite ją į pasą:

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

Kadangi QR koduoja stabilų sprendiklio URL (https://qr3.app/dpp/{gtin}/{serial}, pridėkite ?format=jsonld, kad gautumėte JSON-LD), jums niekada nereikia iš naujo spausdinti etiketės, kad pakeistumėte duomenis. Tapatybė lieka fiksuota; už jos esantis turinys lieka aktualus. Sujunkite tai su qr.updated ir galėsite išsiųsti pranešimą kaskart, kai pasas pasikeičia – uždarydami ciklą tarp jūsų ERP, paso ir bet kurio, kas stebi tolesnėje grandinėje.

Įvykių lentelė: įvykis → ką automatizuoti

Pradėkite nuo qr.scanned, kad gautumėte įsitraukimo ir lauko signalus; pridėkite gyvavimo ciklo įvykius, kai sinchronizuojate pasus į savo platesnes sistemas.

DUK

Ar turiu tikrinti parašą, jei mano galinio taško URL yra slaptas? Taip. URL nėra paslaptis – jis nuteka žurnaluose, tarpiniuose serveriuose ir naršyklės istorijoje. HMAC tikrinimas su verifyWebhook yra vienintelis dalykas, įrodantis, kad naudingoji apkrova iš tikrųjų atkeliavo iš qr3.

Kas nutinka, jei mano galinis taškas neveikia, kai suaktyvinamas įvykis? Greitai patvirtinkite su 200, kai tik patikrinote, ir lėtą darbą atlikite asinchroniškai, kad laikinos tolesnių komponentų problemos niekada nestabdytų atsakymo. Palaikykite savo idempotentiškumą pagal dpp/code id, kad pakartotinai pateiktas pristatymas nebūtų suskaičiuotas du kartus.

Ar galiu atnaujinti GTIN arba serijos numerį per client.dpp.update? Ne – GTIN ir serijos numeris yra nekintami; jie yra stabili produkto tapatybė. Tik duomenų laukai yra atnaujinami. Būtent tas nekintamumas leidžia atspausdintam QR išlikti galiojančiu amžinai.

Šaltiniai

• ES ESPR — Reglamentas (ES) 2024/1781
• ES Baterijų reglamentas 2023/1542
• HMAC — RFC 2104

Pradėkite nemokamai ir sujunkite savo pirmąjį DPP webhook: app.qr3.app/sign-up