Awtomatizzazzjoni tal-Passaporti Diġitali tal-Prodotti bil-Webhooks

Ħafna timijiet jittrattaw Passaport Diġitali tal-Prodott bħala paġna: toħolqu, tistampa l-QR, u tinsih. Dan iħalli l-aktar sinjal utli barra. Kull darba li xi ħadd jiskennja l-QR fuq prodott, dik hija avveniment — persuna reali, f'pajjiż reali, li żżomm unità reali, f'mument reali. Wassal dawk l-avvenimenti fl-istack tiegħek u l-passaport jieqaf ikun paġna statika u jsir il-front end ta' pipeline ta' awtomatizzazzjoni. Din il-gwida turi kif tabbona għal qr.scanned, tivverifika kull payload, u tibdel l-iskans u l-aġġornamenti f'workflows reali bl-SDK ta' qr3.

Għaliex DPP huwa sors ta' avvenimenti, mhux paġna statika

Il-valur ta' passaport mhuwiex il-paġna li l-konsumatur jara darba. Huwa l-fluss ta' interazzjonijiet madwaru: skans fil-kamp, tibdil fid-data mill-ERP tiegħek, tranżizzjonijiet fiċ-ċiklu tal-ħajja. Kull wieħed huwa xi ħaġa li s-sistemi tiegħek jistgħu jirreaġixxu għaliha f'ħin reali.

Il-Webhooks jaqilbu l-mudell tas-soltu tal-polling. Minflok tistaqsi "ġara xi ħaġa?" fuq timer, qr3 isejjaħ lilek fil-mument li jiġri. It-tipi ta' avveniment li temetti l-pjattaforma jinkludu qr.scanned, flimkien ma' qr.created, qr.updated u qr.deleted għat-tibdil fiċ-ċiklu tal-ħajja. Dak li l-aktar timijiet jużaw inqas huwa qr.scanned: jisparat meta konsumatur, tekniku, jew uffiċjal tad-dwana fil-fatt jiskennja prodott fil-kamp.

Payload ta' qr.scanned iġorr il-kuntest li teħtieġ biex taġixxi — inkluż il-pajjiż tal-iskan u l-id tad-dpp/code li jidentifika liema unità ġiet skennjata. Dak huwa biżżejjed biex imexxi l-analitika, l-ifornir mill-ġdid, u l-loġika tal-irtirar mingħajr bniedem fiċ-ċiklu.

Abbonament għal qr.scanned

Indika endpoint ta' webhook lejn is-servizz tiegħek u ttratta l-avveniment. L-SDK ta' qr3 jiġi b'verifier biex ma jkollokx tanalizza r-raw bodies bl-idejn:

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

Il-handler huwa intenzjonalment irqiq: ivverifika, ferra' fuq event.type, irrikonoxxi malajr b'200. Agħmel ix-xogħol tqil (kitbiet ta' analitika, sejħiet lill-ERP) b'mod asinkronu biex downstream bil-mod qatt ma jimblokka r-rikonoxximent.

Verifika tal-firem (verifyWebhook, HMAC-SHA256) — dejjem agħmel dan

Endpoint ta' webhook huwa URL pubbliku. Kull min isibu jista' jagħmel POST lejh. Jekk tafda l-body mingħajr ma tiċċekkja min bagħtu, attakkant jista' jiffalsifika "skans", jiskatta ordnijiet mill-ġdid foloz, jew jispara flegi foloz ta' rtirar. Dejjem ivverifika l-firma qabel ma taġixxi fuq payload.

qr3 jiffirma kull webhook b'HMAC-SHA256 fuq il-body tat-talba, billi juża s-secret tal-endpoint tiegħek. Il-firma tasal fil-header tat-talba qr3-signature. verifyWebhook(body, signature, secret) jikkalkula mill-ġdid l-HMAC u jqabblu; jekk ma jaqbilx, jitfa' u inti tirrifjuta t-talba:

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

Tliet regoli li jżommu dan onest:

• Ivverifika kontra r-raw bytes. Is-serjalizzazzjoni mill-ġdid tal-JSON tista' tirranġa mill-ġdid iċ-ċwievet u tibdel il-whitespace, li jkisser l-HMAC. Aqbad ir-raw body (hawn fuq, express.raw).
• Żomm is-secret secret. Jgħix fl-ambjent tiegħek, qatt fil-kodiċi tal-klijent jew f'repo.
• Fail closed. L-ebda firma valida → 401, l-ebda effetti sekondarji. Qatt "ipproċessa xorta waħda" fuq nuqqas ta' qbil.

Mudelli: analitika / ordni mill-ġdid / irtirar

Ladarba tafda l-avveniment, ftit mudelli jkopru ħafna minn dak li jridu t-timijiet:

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: aggrega l-iskans skont il-pajjiż u l-unità biex tara l-involviment fid-dinja reali — liema swieq fil-fatt jiskennjaw, u liema SKUs jaraw l-aktar interazzjoni wara l-bejgħ.
• Ordni mill-ġdid / ifornir mill-ġdid: tisplożjoni ta' skans f'reġjun tista' tagħmel l-input għal sinjali ta' domanda jew tiskatta workflows ta' restokk fl-ERP tiegħek.
• Irtirar / sikurezza: jekk unità tinsab taħt irtirar, skan huwa opportunità biex tilħaq lil min qed iżommha — avża t-tim tiegħek, jew uri avviż fuq il-passaport innifsu.

L-ebda waħda minn dawn ma teħtieġ polling jew batch ta' bil-lejl. Jiġru fl-istant li l-prodott jiġi skennjat.

Żamma tad-data aġġornata permezz ta' client.dpp.update

Ir-reazzjoni għall-iskans hija nofs iċ-ċiklu; in-nofs l-ieħor huwa li żżomm il-passaport innifsu eżatt. Regolamenti bħall-ESPR (UE 2024/1781) u r-Regolament dwar il-Batteriji (UE 2023/1542) jistennew li d-data tal-passaport tirrifletti r-realtà matul il-ħajja tal-prodott — marka tal-karbonju kkalkulata mill-ġdid, istruzzjonijiet ta' tiswija aġġornati, miri ta' kontenut riċiklat milħuqa.

Mexxi dawk l-aġġornamenti mis-sistema tar-rekord. Meta valur jinbidel fl-ERP tiegħek, imbottah lejn il-passaport:

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

Minħabba li l-QR jikkodifika URL ta' resolver stabbli (https://qr3.app/dpp/{gtin}/{serial}, żid ?format=jsonld għal JSON-LD), qatt ma terġa' tistampa label biex tibdel id-data. L-identità tibqa' fissa; il-kontenut warajha jibqa' aġġornat. Ikkombina dan ma' qr.updated u tista' xxerred notifika kull meta passaport jinbidel — tagħlaq iċ-ċiklu bejn l-ERP tiegħek, il-passaport, u kull min qed josserva downstream.

Tabella ta' avvenimenti: avveniment → x'tawtomatizza

Ibda b'qr.scanned għall-involviment u s-sinjali tal-kamp; żid l-avvenimenti taċ-ċiklu tal-ħajja hekk kif tissinkronizza l-passaporti fis-sistemi usa' tiegħek.

FAQ

Irrid nivverifika l-firma jekk l-URL tal-endpoint tiegħi huwa sigriet? Iva. URL mhuwiex sigriet — joħroġ fil-logs, fil-proxies, u fl-istorja tal-browser. Il-verifika HMAC b'verifyWebhook hija l-unika ħaġa li tipprova li payload fil-fatt ġie minn qr3.

X'jiġri jekk l-endpoint tiegħi jkun 'l isfel meta jispara avveniment? Irrikonoxxi malajr b'200 ladarba tkun ivverifikajt, u agħmel ix-xogħol bil-mod b'mod asinkronu biex problemi temporanji downstream qatt ma jwaqqfu r-rispons. Żomm l-idempotenza tiegħek stess fuq id-dpp/code id biex twassil mibgħut mill-ġdid ma jingħaddx darbtejn.

Nista' naġġorna l-GTIN jew is-serial permezz ta' client.dpp.update? Le — GTIN u serial huma immutabbli; huma l-identità stabbli tal-prodott. Huma biss l-oqsma tad-data li jistgħu jiġu aġġornati. Dik l-immutabilità hija eżattament dak li jħalli l-QR stampat jibqa' validu għal dejjem.

Sorsi

• UE ESPR — Regolament (UE) 2024/1781
• Regolament tal-UE dwar il-Batteriji 2023/1542
• HMAC — RFC 2104

Ibda b'xejn u qabbad l-ewwel webhook tad-DPP tiegħek: app.qr3.app/sign-up