Digitālo produktu pasu automatizācija ar Webhook

Lielākā daļa komandu uztver digitālā produkta pasi kā lapu: jūs to izveidojat, izdrukājat QR kodu un aizmirstat par to. Tādējādi visnoderīgākais signāls paliek neizmantots. Katru reizi, kad kāds noskenē QR kodu uz produkta, tas ir notikums — reāls cilvēks reālā valstī, kas tur rokā reālu vienību reālā brīdī. Savietojiet šos notikumus ar savu tehnoloģiju steku, un pase pārstāj būt statiska lapa un kļūst par automatizācijas konveijera priekšpusi. Šī rokasgrāmata parāda, kā abonēt qr.scanned, pārbaudīt katru payload un pārvērst skenējumus un atjauninājumus reālos darbplūsmās ar qr3 SDK.

Kāpēc DPP ir notikumu avots, nevis statiska lapa

Pases vērtība nav lapa, ko patērētājs redz vienu reizi. Tā ir mijiedarbību plūsma ap to: skenējumi uz vietas, datu izmaiņas no jūsu ERP, dzīves cikla pārejas. Katra no tām ir kaut kas, uz ko jūsu sistēmas var reaģēt reāllaikā.

Webhook apgriež ierasto aptaujāšanas modeli. Tā vietā, lai pēc taimera jautātu "vai kas nav noticis?", qr3 izsauc jūs tajā pašā brīdī, kad tas notiek. Platformas izstarotie notikumu veidi ietver qr.scanned, kā arī qr.created, qr.updated un qr.deleted dzīves cikla izmaiņām. Tas, ko lielākā daļa komandu izmanto par maz, ir qr.scanned: tas nostrādā, kad patērētājs, tehniķis vai muitas darbinieks faktiski noskenē produktu reālajā vidē.

qr.scanned payload satur kontekstu, kas jums nepieciešams, lai rīkotos — tostarp skenējuma valsti un dpp/code id, kas identificē, kura vienība tika noskenēta. Ar to pietiek, lai vadītu analītiku, papildināšanu un atsaukšanas loģiku bez cilvēka iesaistes.

Abonēšana uz qr.scanned

Norādiet webhook galapunktu uz savu pakalpojumu un apstrādājiet notikumu. qr3 SDK piegādā pārbaudītāju, lai jums nebūtu manuāli jāparsē neapstrādāti pieprasījuma ķermeņi:

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

Apstrādātājs ir apzināti plāns: pārbaudiet, sazarojieties pēc event.type, ātri apstipriniet ar 200. Veiciet smago darbu (analītikas ierakstus, ERP izsaukumus) asinhroni, lai lēns lejupstraumes komponents nekad nebloķētu apstiprinājumu.

Parakstu pārbaude (verifyWebhook, HMAC-SHA256) — dariet to vienmēr

Webhook galapunkts ir publisks URL. Ikviens, kas to atrod, var uz to nosūtīt POST pieprasījumu. Ja jūs uzticaties ķermenim, nepārbaudot, kas to nosūtīja, uzbrucējs var viltot "skenējumus", izraisīt nepatiesus atkārtotus pasūtījumus vai aktivizēt nepatiesas atsaukšanas atzīmes. Vienmēr pārbaudiet parakstu, pirms rīkojaties ar payload.

qr3 paraksta katru Webhook ar HMAC-SHA256 pār pieprasījuma ķermeni, izmantojot jūsu galapunkta noslēpumu. Paraksts ierodas qr3-signature pieprasījuma galvenē. verifyWebhook(body, signature, secret) no jauna aprēķina HMAC un to salīdzina; ja tas nesakrīt, tas izmet kļūdu, un jūs noraidāt pieprasījumu:

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

Trīs noteikumi, kas to uztur godīgu:

• Pārbaudiet pret neapstrādātajiem baitiem. JSON atkārtota serializācija var pārkārtot atslēgas un mainīt atstarpes, kas izjauc HMAC. Notveriet neapstrādāto ķermeni (augšā, express.raw).
• Turiet noslēpumu noslēpumā. Tas atrodas jūsu vidē, nekad klienta kodā vai repozitorijā.
• Atteikums ar noslēgtu stāvokli. Nav derīga paraksta → 401, bez blakusefektiem. Nekad "apstrādājiet tik un tā", ja ir neatbilstība.

Šabloni: analītika / atkārtots pasūtījums / atsaukšana

Tiklīdz jūs uzticaties notikumam, daži šabloni aptver lielāko daļu no tā, ko komandas vēlas:

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: apkopojiet skenējumus pēc valsts un vienības, lai redzētu reālo iesaisti — kuri tirgi faktiski skenē un kuri SKU piedzīvo visvairāk mijiedarbības pēc pārdošanas.
• Atkārtots pasūtījums / papildināšana: skenējumu uzplūdums kādā reģionā var barot pieprasījuma signālus vai aktivizēt krājumu papildināšanas darbplūsmas jūsu ERP.
• Atsaukšana / drošība: ja vienība ir pakļauta atsaukšanai, skenējums ir iespēja sasniegt to, kura rokās tā atrodas — brīdiniet savu komandu vai parādiet paziņojumu pašā pasē.

Nevienam no tiem nav nepieciešama aptaujāšana vai nakts pakešapstrāde. Tie notiek tajā pašā mirklī, kad produkts tiek noskenēts.

Datu aktualitātes uzturēšana ar client.dpp.update

Reaģēšana uz skenējumiem ir puse no cikla; otra puse ir pašas pases uzturēšana precīza. Tādi noteikumi kā ESPR (ES 2024/1781) un Bateriju regula (ES 2023/1542) sagaida, ka pases dati atspoguļo realitāti visā produkta dzīves laikā — pārrēķinātu oglekļa pēdu, atjauninātas remonta instrukcijas, sasniegtus pārstrādātā satura mērķrādītājus.

Vadiet šos atjauninājumus no ieraksta sistēmas. Kad vērtība mainās jūsu ERP, nosūtiet to uz pasi:

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

Tā kā QR kods kodē stabilu atrisinātāja URL (https://qr3.app/dpp/{gtin}/{serial}, pievienojiet ?format=jsonld, lai iegūtu JSON-LD), jums nekad nav atkārtoti jādrukā etiķete, lai mainītu datus. Identitāte paliek nemainīga; saturs aiz tās paliek aktuāls. Apvienojiet to ar qr.updated, un jūs varat izplatīt paziņojumu ikreiz, kad pase mainās — noslēdzot ciklu starp jūsu ERP, pasi un ikvienu, kas vēro lejupstraumē.

Notikumu tabula: notikums → ko automatizēt

Sāciet ar qr.scanned, lai iegūtu iesaistes un lauka signālus; pievienojiet dzīves cikla notikumus, kad sinhronizējat pases savās plašākajās sistēmās.

BUJ

Vai man ir jāpārbauda paraksts, ja mans galapunkta URL ir slepens? Jā. URL nav noslēpums — tas noplūst žurnālos, starpniekserveros un pārlūkprogrammas vēsturē. HMAC pārbaude ar verifyWebhook ir vienīgais, kas pierāda, ka payload patiešām nāca no qr3.

Kas notiek, ja mans galapunkts ir nepieejams, kad nostrādā notikums? Ātri apstipriniet ar 200, tiklīdz esat veicis pārbaudi, un veiciet lēno darbu asinhroni, lai īslaicīgas lejupstraumes problēmas nekad neaizkavētu atbildi. Uzturiet savu idempotenci pēc dpp/code id, lai atkārtoti piegādāta ziņa netiktu skaitīta divreiz.

Vai es varu atjaunināt GTIN vai sērijas numuru, izmantojot client.dpp.update? Nē — GTIN un sērijas numurs ir nemainīgi; tie ir produkta stabilā identitāte. Atjaunināmi ir tikai datu lauki. Tieši šī nemainīgums ir tas, kas ļauj izdrukātajam QR kodam palikt derīgam mūžīgi.

Avoti

• EU ESPR — Regula (ES) 2024/1781
• ES Bateriju regula 2023/1542
• HMAC — RFC 2104

Sāciet bez maksas un savienojiet savu pirmo DPP webhook: app.qr3.app/sign-up