Automatizacija digitalnih putovnica proizvoda pomoću Webhookova

Većina timova tretira digitalnu putovnicu proizvoda kao stranicu: kreirate je, ispišete QR i zaboravite na nju. Time se najkorisniji signal ostavlja neiskorištenim. Svaki put kad netko skenira QR na proizvodu, to je događaj — stvarna osoba, u stvarnoj zemlji, koja drži stvarnu jedinicu, u stvarnom trenutku. Povežite te događaje sa svojim stogom i putovnica prestaje biti statična stranica te postaje sučelje automatizacijskog procesa. Ovaj vodič pokazuje kako se pretplatiti na qr.scanned, provjeriti svaki payload te pretvoriti skeniranja i ažuriranja u stvarne radne tijekove pomoću qr3 SDK-a.

Zašto je DPP izvor događaja, a ne statična stranica

Vrijednost putovnice nije stranica koju potrošač jednom vidi. To je tok interakcija oko nje: skeniranja na terenu, promjene podataka iz vašeg ERP-a, prijelazi životnog ciklusa. Svaki od njih je nešto na što vaši sustavi mogu reagirati u stvarnom vremenu.

Webhookovi preokreću uobičajeni model anketiranja. Umjesto da na pravilnim razmacima pitate „je li se nešto dogodilo?", qr3 zove vas u trenutku kad se to dogodi. Tipovi događaja koje platforma emitira uključuju qr.scanned, uz qr.created, qr.updated i qr.deleted za promjene životnog ciklusa. Onaj koji većina timova nedovoljno koristi je qr.scanned: aktivira se kad potrošač, tehničar ili carinik stvarno skenira proizvod u stvarnom svijetu.

qr.scanned payload nosi kontekst koji vam je potreban za djelovanje — uključujući zemlju skeniranja i dpp/code id koji identificira koja je jedinica skenirana. To je dovoljno za pokretanje analitike, popunjavanja zaliha i logike opoziva bez čovjeka u petlji.

Pretplata na qr.scanned

Usmjerite webhook krajnju točku na svoju uslugu i obradite događaj. qr3 SDK isporučuje verifikator pa ne morate ručno parsirati sirova tijela:

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

Rukovatelj je namjerno tanak: provjerite, granajte na event.type, brzo potvrdite s 200. Težak posao (zapisi analitike, ERP pozivi) obavljajte asinkrono kako spori downstream nikad ne bi blokirao potvrdu.

Provjera potpisa (verifyWebhook, HMAC-SHA256) — uvijek to radite

Webhook krajnja točka je javni URL. Svatko tko ga pronađe može na njega slati POST zahtjeve. Ako vjerujete tijelu bez provjere tko ga je poslao, napadač može krivotvoriti „skeniranja", pokrenuti lažne ponovne narudžbe ili aktivirati lažne oznake opoziva. Uvijek provjerite potpis prije nego što djelujete na temelju payloada.

qr3 potpisuje svaki webhook pomoću HMAC-SHA256 nad tijelom zahtjeva, koristeći tajni ključ vaše krajnje točke. Potpis stiže u zaglavlju zahtjeva qr3-signature. verifyWebhook(body, signature, secret) ponovno izračunava HMAC i uspoređuje ga; ako se ne podudara, baca iznimku i vi odbijate zahtjev:

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

Tri pravila koja ovo drže poštenim:

• Provjeravajte nad sirovim bajtovima. Ponovna serijalizacija JSON-a može preurediti ključeve i promijeniti razmake, što kvari HMAC. Uhvatite sirovo tijelo (gore, express.raw).
• Čuvajte tajnu kao tajnu. Ona živi u vašem okruženju, nikad u klijentskom kodu ili repozitoriju.
• Zatvarajte u slučaju greške. Nema valjanog potpisa → 401, bez nuspojava. Nikad nemojte „svejedno obraditi" pri nepodudaranju.

Obrasci: analitika / ponovna narudžba / opoziv

Kad jednom vjerujete događaju, šačica obrazaca pokriva većinu onoga što timovi žele:

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: agregirajte skeniranja po zemlji i jedinici kako biste vidjeli stvarnu angažiranost — koja tržišta zaista skeniraju i koji SKU-ovi imaju najviše interakcije nakon prodaje.
• Ponovna narudžba / popunjavanje zaliha: nagli porast skeniranja u nekoj regiji može hraniti signale potražnje ili pokrenuti radne tijekove obnove zaliha u vašem ERP-u.
• Opoziv / sigurnost: ako je jedinica pod opozivom, skeniranje je prilika da dosegnete onoga tko je drži — upozorite svoj tim ili prikažite obavijest na samoj putovnici.

Ništa od ovoga ne treba anketiranje ili noćnu serijsku obradu. To se događa u trenutku kad je proizvod skeniran.

Održavanje podataka ažurnima putem client.dpp.update

Reagiranje na skeniranja je polovica petlje; druga polovica je održavanje same putovnice točnom. Propisi poput ESPR-a (EU 2024/1781) i Uredbe o baterijama (EU 2023/1542) očekuju da podaci putovnice odražavaju stvarnost tijekom životnog vijeka proizvoda — ponovno izračunati ugljični otisak, ažurirane upute za popravak, dostignuti ciljevi recikliranog sadržaja.

Pokrenite ta ažuriranja iz sustava evidencije. Kad se vrijednost promijeni u vašem ERP-u, gurnite je u putovnicu:

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

Budući da QR kodira stabilni URL razrješivača (https://qr3.app/dpp/{gtin}/{serial}, dodajte ?format=jsonld za JSON-LD), nikad ne morate ponovno ispisivati naljepnicu da biste promijenili podatke. Identitet ostaje fiksan; sadržaj iza njega ostaje aktualan. Uparite ovo s qr.updated i možete proslijediti obavijest kad god se putovnica promijeni — zatvarajući petlju između vašeg ERP-a, putovnice i svakoga tko prati nizvodno.

Tablica događaja: događaj → što automatizirati

Počnite s qr.scanned za angažiranost i signale s terena; dodajte događaje životnog ciklusa kako sinkronizirate putovnice u svoje šire sustave.

Često postavljana pitanja

Moram li provjeravati potpis ako je URL moje krajnje točke tajan? Da. URL nije tajna — curi u zapisnicima, proxyjima i povijesti preglednika. HMAC provjera pomoću verifyWebhook jedino je što dokazuje da je payload zaista stigao od qr3.

Što se događa ako je moja krajnja točka nedostupna kad se događaj aktivira? Brzo potvrdite s 200 nakon što ste provjerili, a spor posao obavljajte asinkrono kako prolazni nizvodni problemi nikad ne bi zaustavili odgovor. Održavajte vlastitu idempotentnost na dpp/code id kako ponovno isporučena dostava ne bi bila dvostruko brojana.

Mogu li ažurirati GTIN ili serijski broj putem client.dpp.update? Ne — GTIN i serijski broj su nepromjenjivi; oni su stabilni identitet proizvoda. Samo se podatkovna polja mogu ažurirati. Upravo ta nepromjenjivost omogućuje da ispisani QR ostane valjan zauvijek.

Izvori

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

Započnite besplatno i povežite svoj prvi DPP webhook: app.qr3.app/sign-up