Automatizace digitálních produktových pasů pomocí webhooků

Většina týmů zachází s digitálním produktovým pasem jako se stránkou: vytvoříte ho, vytisknete QR kód a zapomenete na něj. Tím ale necháváte ležet ten nejužitečnější signál. Pokaždé, když někdo naskenuje QR kód na produktu, je to událost — skutečná osoba, ve skutečné zemi, držící skutečný kus, ve skutečném okamžiku. Propojte tyto události se svým stackem a pas přestane být statickou stránkou a stane se vstupní branou automatizační pipeline. Tento průvodce ukazuje, jak se přihlásit k odběru qr.scanned, ověřit každý payload a proměnit skenování a aktualizace ve skutečné workflow s qr3 SDK.

Proč je DPP zdrojem událostí, a ne statickou stránkou

Hodnota pasu není ta stránka, kterou spotřebitel jednou uvidí. Je to proud interakcí kolem něj: skenování v terénu, změny dat z vašeho ERP, přechody v životním cyklu. Každá z nich je něco, na co mohou vaše systémy reagovat v reálném čase.

Webhooky obracejí obvyklý model dotazování (polling). Místo toho, abyste se v pravidelných intervalech ptali „stalo se něco?“, zavolá qr3 vám v okamžiku, kdy se to stane. Mezi typy událostí, které platforma vysílá, patří qr.scanned, dále qr.created, qr.updated a qr.deleted pro změny v životním cyklu. Tou, kterou většina týmů nevyužívá naplno, je qr.scanned: spustí se, když spotřebitel, technik nebo celní úředník skutečně naskenuje produkt v terénu.

Payload qr.scanned nese kontext, který potřebujete k jednání — včetně země skenování a dpp/code id, které identifikuje, jaký kus byl naskenován. To stačí k tomu, abyste řídili analytiku, doplňování zásob a logiku stažení z trhu bez zásahu člověka.

Přihlášení k odběru qr.scanned

Nasměrujte webhookový endpoint na svou službu a zpracujte událost. Součástí qr3 SDK je verifikátor, takže nemusíte parsovat surová těla zpráv ručně:

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

Handler je záměrně útlý: ověřit, větvit podle event.type, rychle potvrdit pomocí 200. Náročnou práci (zápisy do analytiky, volání ERP) dělejte asynchronně, aby pomalý navazující systém nikdy neblokoval potvrzení.

Ověřování podpisů (verifyWebhook, HMAC-SHA256) — dělejte to vždy

Webhookový endpoint je veřejná URL. Kdokoli, kdo ji najde, na ni může poslat POST. Pokud tělu důvěřujete, aniž byste kontrolovali, kdo ho odeslal, může útočník zfalšovat „skenování“, spustit falešné doobjednávky nebo vyvolat falešné příznaky stažení z trhu. Před tím, než na payload zareagujete, vždy ověřte podpis.

qr3 podepisuje každý webhook pomocí HMAC-SHA256 nad tělem požadavku s použitím tajného klíče vašeho endpointu. Podpis přichází v hlavičce požadavku qr3-signature. verifyWebhook(body, signature, secret) znovu vypočítá HMAC a porovná ho; pokud neodpovídá, vyhodí výjimku a vy požadavek odmítnete:

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

Tři pravidla, která to udržují poctivé:

• Ověřujte proti surovým bajtům. Opětovná serializace JSON může změnit pořadí klíčů a bílé znaky, což rozbije HMAC. Zachyťte surové tělo (výše, express.raw).
• Udržujte tajný klíč v tajnosti. Žije ve vašem prostředí, nikdy ne v klientském kódu ani v repozitáři.
• Selhávejte uzavřeně (fail closed). Žádný platný podpis → 401, žádné vedlejší účinky. Při neshodě nikdy „přesto nezpracovávejte“.

Vzory: analytika / doobjednávka / stažení z trhu

Jakmile události důvěřujete, pokryje hrstka vzorů většinu toho, co týmy chtějí:

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

• Analytika: agregujte skenování podle země a kusu, abyste viděli reálné zapojení — které trhy skutečně skenují a které SKU zaznamenávají nejvíce poprodejních interakcí.
• Doobjednávka / doplňování zásob: nárůst skenování v určitém regionu může napájet signály poptávky nebo spouštět workflow pro doplnění zásob ve vašem ERP.
• Stažení z trhu / bezpečnost: pokud je kus předmětem stažení z trhu, skenování je příležitostí oslovit toho, kdo ho drží — upozorněte svůj tým nebo zobrazte oznámení přímo v pasu.

Nic z toho nepotřebuje polling ani noční dávkové zpracování. Děje se to v okamžiku, kdy je produkt naskenován.

Udržování aktuálnosti dat pomocí client.dpp.update

Reagování na skenování je polovina smyčky; tou druhou polovinou je udržování přesnosti samotného pasu. Předpisy jako ESPR (EU 2024/1781) a nařízení o bateriích (EU 2023/1542) očekávají, že data pasu budou po celou dobu životnosti produktu odrážet realitu — přepočítanou uhlíkovou stopu, aktualizované návody k opravě, dosažené cíle podílu recyklovaného obsahu.

Tyto aktualizace řiďte ze systému evidence. Když se hodnota ve vašem ERP změní, pošlete ji do pasu:

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

Protože QR kód kóduje stabilní resolver URL (https://qr3.app/dpp/{gtin}/{serial}, pro JSON-LD přidejte ?format=jsonld), nikdy nebudete kvůli změně dat znovu tisknout štítek. Identita zůstává pevná; obsah za ní zůstává aktuální. Spárujte to s qr.updated a můžete rozeslat oznámení pokaždé, když se pas změní — uzavřete tak smyčku mezi vaším ERP, pasem a kýmkoli, kdo navazujícím způsobem sleduje dění.

Tabulka událostí: událost → co automatizovat

Začněte s qr.scanned pro zapojení a signály z terénu; události životního cyklu přidejte, jakmile budete pasy synchronizovat do svých širších systémů.

FAQ

Musím ověřovat podpis, pokud je URL mého endpointu tajná? Ano. URL není tajemství — uniká v logách, proxy serverech a historii prohlížeče. Ověření HMAC pomocí verifyWebhook je jediná věc, která dokazuje, že payload skutečně pochází z qr3.

Co se stane, když je můj endpoint nedostupný v okamžiku, kdy se spustí událost? Jakmile máte ověřeno, rychle potvrďte pomocí 200 a pomalou práci dělejte asynchronně, aby přechodné problémy navazujících systémů nikdy nezdržely odpověď. Udržujte si vlastní idempotenci na dpp/code id, aby se opakované doručení nezapočítalo dvakrát.

Mohu pomocí client.dpp.update aktualizovat GTIN nebo sériové číslo? Ne — GTIN a sériové číslo jsou neměnné; jsou to stabilní identita produktu. Aktualizovat lze pouze datová pole. Právě tato neměnnost je to, co umožňuje, aby vytištěný QR kód zůstal navždy platný.

Zdroje

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

Začněte zdarma a zapojte svůj první DPP webhook: app.qr3.app/sign-up