Digitaalsete tootepasside automatiseerimine Webhookide abil

Enamik tiime käsitleb digitaalset tootepassi kui lehte: sa lood selle, prindid QR-koodi ja unustad selle. See jätab kõige kasulikuma signaali kasutamata. Iga kord, kui keegi skannib tootel oleva QR-koodi, on see sündmus — päris inimene, päris riigis, hoides käes päris ühikut, päris hetkel. Ühenda need sündmused oma süsteemiga ja passist ei ole enam staatiline leht, vaid automatiseerimise konveieri esiserv. See juhend näitab, kuidas tellida qr.scanned sündmusi, kontrollida iga payloadi ning muuta skannimised ja uuendused päris töövoogudeks qr3 SDK abil.

Miks on DPP sündmuste allikas, mitte staatiline leht

Passi väärtus ei ole leht, mida tarbija ühe korra näeb. Selleks on selle ümber toimuvate interaktsioonide voog: skannimised väljal, andmemuutused sinu ERP-st, elutsükli üleminekud. Iga neist on miski, millele sinu süsteemid saavad reaalajas reageerida.

Webhookid pööravad tavalise pollimismudeli pea peale. Selle asemel, et taimeri järgi küsida „kas midagi juhtus?", helistab qr3 sulle sel hetkel, kui midagi juhtub. Platvormi väljastatavate sündmuste tüüpide hulka kuuluvad qr.scanned, lisaks qr.created, qr.updated ja qr.deleted elutsükli muutuste jaoks. Kõige enam alakasutatud sündmus on qr.scanned: see käivitub, kui tarbija, tehnik või tolliametnik tegelikult toodet looduses skannib.

qr.scanned payload kannab konteksti, mida on vaja tegutsemiseks — sealhulgas skannimise riigi ja dpp/code id, mis tuvastab, milline ühik skanniti. Sellest piisab, et juhtida analüütikat, täiendamist ja tagasikutsumisloogikat ilma inimeseta ahelas.

qr.scanned tellimine

Suuna webhooki lõpp-punkt oma teenusele ja käsitle sündmust. qr3 SDK sisaldab verifitseerijat, nii et sa ei pea tooreid päringukehasid käsitsi parsima:

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

Käsitleja on tahtlikult õhuke: kontrolli, hargne event.type järgi, kinnita kiiresti 200-ga. Tee raske töö (analüütika kirjutamised, ERP-päringud) asünkroonselt, nii et aeglane allavoolu süsteem ei blokeeri kunagi kinnitust.

Allkirjade kontrollimine (verifyWebhook, HMAC-SHA256) — tee seda alati

Webhooki lõpp-punkt on avalik URL. Igaüks, kes selle leiab, saab sinna POST-päringu saata. Kui sa usaldad keha kontrollimata, kes selle saatis, võib ründaja võltsida „skannimisi", käivitada võltsitud taastellimusi või vallandada valesid tagasikutsumismärgiseid. Kontrolli allkirja alati, enne kui payloadi alusel tegutsed.

qr3 allkirjastab iga webhooki HMAC-SHA256 abil üle päringukeha, kasutades sinu lõpp-punkti saladust. Allkiri saabub qr3-signature päringupäises. verifyWebhook(body, signature, secret) arvutab HMAC-i uuesti ja võrdleb seda; kui see ei kattu, viskab see vea ja sina lükkad päringu tagasi:

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

Kolm reeglit, mis hoiavad selle ausana:

• Kontrolli tooreid baite. JSON-i uuesti serialiseerimine võib võtmeid ümber järjestada ja tühikuid muuta, mis lõhub HMAC-i. Püüa toores keha kinni (eespool, express.raw).
• Hoia saladus saladuses. See elab sinu keskkonnas, mitte kunagi kliendikoodis ega repositooriumis.
• Suletult ebaõnnestumine. Kehtetut allkirja pole → 401, mingeid kõrvalmõjusid. Ärge kunagi „töötlege ikkagi" mittevastavuse korral.

Mustrid: analüütika / taastellimus / tagasikutsumine

Kui sa sündmust usaldad, katab käputäis mustreid suurema osa sellest, mida tiimid soovivad:

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

• Analüütika: koonda skannimised riigi ja ühiku järgi, et näha tegelikku reaalmaailma kaasatust — millised turud tegelikult skannivad ja millistel SKU-del on kõige rohkem müügijärgset interaktsiooni.
• Taastellimus / täiendamine: skannimiste puhang piirkonnas võib toita nõudlussignaale või käivitada laoseisu täiendamise töövooge sinu ERP-s.
• Tagasikutsumine / ohutus: kui ühik on tagasikutsumise all, on skannimine võimalus jõuda selleni, kes seda käes hoiab — teavita oma tiimi või kuva teade passil endal.

Mitte ükski neist ei vaja pollimist ega öist partii-töötlust. Need toimuvad sel hetkel, kui toode skannitakse.

Andmete ajakohasena hoidmine client.dpp.update abil

Skannimistele reageerimine on pool ahelast; teine pool on passi enda täpsena hoidmine. Sellised määrused nagu ESPR (EL 2024/1781) ja akumäärus (EL 2023/1542) eeldavad, et passi andmed peegeldavad reaalsust kogu toote eluea jooksul — ümberarvutatud süsinikujalajälg, uuendatud parandusjuhised, saavutatud ringlussevõetud sisu eesmärgid.

Juhi neid uuendusi tõestusallikast. Kui väärtus sinu ERP-s muutub, suru see passi:

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

Kuna QR kodeerib stabiilse resolveri URL-i (https://qr3.app/dpp/{gtin}/{serial}, lisa ?format=jsonld JSON-LD jaoks), ei pea sa andmete muutmiseks kunagi silti uuesti printima. Identiteet jääb fikseerituks; selle taga olev sisu jääb ajakohaseks. Paari see qr.updated sündmusega ja saad teavituse laiali saata iga kord, kui pass muutub — sulgedes ahela sinu ERP-i, passi ja kõigi allavoolu jälgijate vahel.

Sündmuste tabel: sündmus → mida automatiseerida

Alusta qr.scanned sündmusest kaasatuse ja väljasignaalide jaoks; lisa elutsükli sündmused, kui sünkroonid passe oma laiematesse süsteemidesse.

KKK

Kas ma pean allkirja kontrollima, kui mu lõpp-punkti URL on salajane? Jah. URL ei ole saladus — see lekib logidesse, proksitesse ja brauseri ajalukku. HMAC-i kontrollimine verifyWebhook abil on ainus asi, mis tõestab, et payload tuli tegelikult qr3-st.

Mis juhtub, kui mu lõpp-punkt on maas, kui sündmus käivitub? Kinnita kiiresti 200-ga, kui oled kontrollinud, ja tee aeglane töö asünkroonselt, nii et mööduvad allavoolu probleemid ei peata kunagi vastust. Hoia oma idempotentsust dpp/code id järgi, et korduskättetoimetamist ei loendataks kaks korda.

Kas ma saan GTIN-i või seerianumbrit client.dpp.update abil uuendada? Ei — GTIN ja seerianumber on muutumatud; need on toote stabiilne identiteet. Uuendatavad on ainult andmeväljad. Just see muutumatus on see, mis laseb prinditud QR-koodil igavesti kehtida.

Allikad

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

Alusta tasuta ja ühenda oma esimene DPP webhook: app.qr3.app/sign-up