Автоматизиране на цифрови продуктови паспорти с Webhooks

Повечето екипи третират цифровия продуктов паспорт като страница: създавате го, отпечатвате QR кода и го забравяте. Това оставя най-полезния сигнал неизползван. Всеки път, когато някой сканира QR кода върху продукт, това е събитие — реален човек, в реална държава, държащ реален екземпляр, в реален момент. Свържете тези събития с вашия стек и паспортът престава да бъде статична страница и се превръща във front end на конвейер за автоматизация. Това ръководство показва как да се абонирате за qr.scanned, да проверявате всеки payload и да превръщате сканиранията и актуализациите в реални работни процеси с qr3 SDK.

Защо DPP е източник на събития, а не статична страница

Стойността на паспорта не е страницата, която потребителят вижда веднъж. Това е потокът от взаимодействия около него: сканирания на терен, промени в данните от вашата ERP система, преходи в жизнения цикъл. Всяко от тях е нещо, на което вашите системи могат да реагират в реално време.

Webhooks обръщат обичайния модел на запитване (polling). Вместо да питат „случило ли се е нещо?“ през определен интервал, qr3 се обажда на вас в момента, в който това се случи. Типовете събития, които платформата излъчва, включват qr.scanned, както и qr.created, qr.updated и qr.deleted за промени в жизнения цикъл. Този, който повечето екипи използват недостатъчно, е qr.scanned: той се задейства, когато потребител, техник или митнически служител действително сканира продукт на терен.

Един qr.scanned payload носи контекста, който ви е нужен, за да действате — включително държавата на сканирането и dpp/code id, който идентифицира кой екземпляр е сканиран. Това е достатъчно, за да задвижи анализи, попълване на запаси и логика за изтегляне без човешка намеса.

Абониране за qr.scanned

Насочете webhook endpoint към вашата услуга и обработете събитието. qr3 SDK предоставя verifier, така че да не парсвате необработени тела ръчно:

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

Хендлърът е умишлено опростен: проверете, разклонете по event.type, потвърдете бързо с 200. Вършете тежката работа (записи на анализи, извиквания към ERP) асинхронно, така че бавна downstream система никога да не блокира потвърждението.

Проверка на подписи (verifyWebhook, HMAC-SHA256) — правете това винаги

Webhook endpoint е публичен URL. Всеки, който го открие, може да изпрати POST към него. Ако се доверявате на тялото, без да проверявате кой го е изпратил, нападател може да фалшифицира „сканирания“, да задейства фиктивни повторни поръчки или да генерира фалшиви сигнали за изтегляне. Винаги проверявайте подписа, преди да действате върху payload.

qr3 подписва всеки webhook с HMAC-SHA256 върху тялото на заявката, използвайки тайния ключ на вашия endpoint. Подписът пристига в request header-а qr3-signature. verifyWebhook(body, signature, secret) преизчислява HMAC и го сравнява; ако не съвпада, той хвърля грешка и вие отхвърляте заявката:

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

Три правила, които поддържат това коректно:

• Проверявайте срещу необработените байтове. Повторното сериализиране на JSON може да пренареди ключове и да промени интервалите, което нарушава HMAC. Прихванете необработеното тяло (по-горе, express.raw).
• Пазете тайния ключ в тайна. Той се намира във вашата среда, никога в клиентски код или в repo.
• Fail closed (отказвайте по подразбиране). Няма валиден подпис → 401, без странични ефекти. Никога не „обработвайте въпреки това“ при несъвпадение.

Шаблони: анализи / повторна поръчка / изтегляне

След като се доверите на събитието, шепа шаблони покриват повечето от това, което екипите искат:

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

• Анализи: агрегирайте сканиранията по държава и екземпляр, за да видите реалната ангажираност — кои пазари действително сканират и кои SKU виждат най-много взаимодействие след продажбата.
• Повторна поръчка / попълване на запаси: внезапна вълна от сканирания в даден регион може да захранва сигнали за търсене или да задейства работни процеси за презареждане на запаси във вашата ERP система.
• Изтегляне / безопасност: ако даден екземпляр подлежи на изтегляне, сканирането е възможност да достигнете до този, който го държи — известете екипа си или покажете съобщение върху самия паспорт.

Нито едно от тези не се нуждае от polling или нощен batch. Те се случват в мига, в който продуктът бъде сканиран.

Поддържане на данните актуални чрез client.dpp.update

Реагирането на сканирания е половината от цикъла; другата половина е поддържането на самия паспорт точен. Регулации като ESPR (EU 2024/1781) и Регламента за батериите (EU 2023/1542) очакват данните в паспорта да отразяват реалността през целия живот на продукта — преизчислен въглероден отпечатък, актуализирани инструкции за ремонт, постигнати цели за рециклирано съдържание.

Задвижвайте тези актуализации от системата на запис (system of record). Когато дадена стойност се промени във вашата ERP система, изпратете я към паспорта:

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

Тъй като QR кодът кодира стабилен resolver URL (https://qr3.app/dpp/{gtin}/{serial}, добавете ?format=jsonld за JSON-LD), никога не преотпечатвате етикет, за да промените данни. Идентичността остава фиксирана; съдържанието зад нея остава актуално. Съчетайте това с qr.updated и можете да разпратите известие всеки път, когато паспортът се промени — затваряйки цикъла между вашата ERP система, паспорта и всеки, който следи downstream.

Таблица на събитията: събитие → какво да автоматизирате

Започнете с qr.scanned за ангажираност и сигнали от терен; добавете събитията от жизнения цикъл, докато синхронизирате паспортите с по-широките си системи.

Често задавани въпроси

Трябва ли да проверявам подписа, ако URL адресът на моя endpoint е таен? Да. URL адресът не е тайна — той изтича в логове, прокси сървъри и история на браузъра. HMAC проверката с verifyWebhook е единственото нещо, което доказва, че даден payload действително е дошъл от qr3.

Какво се случва, ако моят endpoint не работи, когато се задейства събитие? Потвърдете бързо с 200, след като сте проверили, и вършете бавната работа асинхронно, така че временни проблеми с downstream системите никога да не блокират отговора. Поддържайте собствена идемпотентност по dpp/code id, така че повторно доставяне да не бъде преброено два пъти.

Мога ли да актуализирам GTIN или сериен номер чрез client.dpp.update? Не — GTIN и серийният номер са непроменими; те са стабилната идентичност на продукта. Само полетата с данни могат да се актуализират. Точно тази непроменимост е това, което позволява на отпечатания QR код да остане валиден завинаги.

Източници

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

Започнете безплатно и свържете първия си DPP webhook: app.qr3.app/sign-up