Pasanna Táirgí Digiteacha a Uathoibriú le Webhooks

Caitheann an chuid is mó d'fhoirne le Pas Táirge Digiteach mar leathanach: cruthaíonn tú é, priontálann tú an cód QR, agus déanann tú dearmad air. Fágann sin an comhartha is úsáidí ar an mbord. Gach uair a scanann duine an cód QR ar tháirge, is imeacht é sin — fíordhuine, i bhfíorthír, a bhfuil fíoraonad ina lámh, ag fíornóiméad. Sreangaigh na himeachtaí sin isteach i do chruach agus scoireann an pas de bheith ina leathanach statach agus éiríonn sé ina thosach ar phíblíne uathoibrithe. Taispeánann an treoir seo conas liostáil le qr.scanned, gach pálasta a fhíorú, agus scanadh agus nuashonruithe a chasadh ina sreafaí oibre dáiríre leis an SDK qr3.

Cén fáth gur foinse imeachtaí é DPP, seachas leathanach statach

Ní hé luach pas ná an leathanach a fheiceann tomhaltóir uair amháin. Is é an sruth idirghníomhaíochtaí timpeall air: scanadh sa réimse, athruithe sonraí ó do chóras ERP, aistrithe saolré. Is rud é gach ceann acu ar féidir le do chórais freagairt dó i bhfíor-am.

Iompaíonn webhooks an gnáthmhúnla vótála droim ar ais. In ionad fiafraí "ar tharla aon rud?" ar uaineadóir, glaonn qr3 ortsa an nóiméad a tharlaíonn sé. I measc na gcineálacha imeachtaí a astaíonn an t-ardán tá qr.scanned, móide qr.created, qr.updated agus qr.deleted le haghaidh athruithe saolré. Is é an ceann a thearcúsáideann an chuid is mó d'fhoirne ná qr.scanned: lasann sé nuair a scanann tomhaltóir, teicneoir nó oifigeach custaim táirge sa saol fíor.

Iompraíonn pálasta qr.scanned an comhthéacs atá uait chun gníomhú — lena n-áirítear an tír ina ndearnadh an scanadh agus an dpp/code id a aithníonn cén t-aonad a scanadh. Is leor sin chun anailísíocht, athlíonadh agus loighic aisghairme a thiomáint gan duine ar bith sa lúb.

Liostáil le qr.scanned

Dírigh críochphointe webhook ar do sheirbhís agus láimhseáil an t-imeacht. Cuireann an SDK qr3 fíoraitheoir ar fáil ionas nach gá duit comhlachtaí amha a pharsáil de láimh:

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

Tá an láimhseálaí tanaí d'aon ghnó: fíoraigh, brainseáil ar event.type, admhaigh go tapa le 200. Déan an obair throm (scríobh anailísíochta, glaonna ERP) go hasincronach ionas nach gcuireann críochphointe mall riamh bac ar an admháil.

Sínithe a fhíorú (verifyWebhook, HMAC-SHA256) — déan é seo i gcónaí

Is URL poiblí é críochphointe webhook. Is féidir le duine ar bith a aimsíonn é POST a dhéanamh chuige. Má chuireann tú muinín sa chomhlacht gan a sheiceáil cé a sheol é, is féidir le hionsaitheoir "scanadh" a bhrionnú, athorduithe bréagacha a spreagadh, nó brataí aisghairme bréige a lasadh. Fíoraigh an síniú i gcónaí sula ngníomhaíonn tú ar phálasta.

Síníonn qr3 gach webhook le HMAC-SHA256 thar chomhlacht na hiarrata, ag baint úsáide as rún do chríochphointe. Sroicheann an síniú sa cheanntásc iarrata qr3-signature. Athríomhann verifyWebhook(body, signature, secret) an HMAC agus déanann sé comparáid air; mura meaitseálann sé, caitheann sé eisceacht agus diúltaíonn tú don iarratas:

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í riail a choinníonn é seo macánta:

• Fíoraigh i gcoinne na mbeart amha. Is féidir le hath-shraitheánú JSON eochracha a athordú agus spás bán a athrú, rud a bhriseann an HMAC. Gabh an comhlacht amh (thuas, express.raw).
• Coinnigh an rún ina rún. Maireann sé i do thimpeallacht, ní bhíonn sé riamh i gcód cliaint ná i stóras.
• Teip dúnta. Gan síniú bailí → 401, gan fo-iarmhairtí. Ná "próiseáil ar aon nós" riamh ar mhímheaitseáil.

Patrúin: anailísíocht / athordú / aisghairm

Nuair a chuireann tú muinín san imeacht, clúdaíonn dornán patrún an chuid is mó den rud atá uait:

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

• Anailísíocht: comhiomlánaigh scanadh de réir tíre agus aonaid chun rannpháirtíocht fíorshaoil a fheiceáil — cé na margaí a scanann i ndáiríre, agus cé na SKUanna a fheiceann an idirghníomhaíocht iardhíola is mó.
• Athordú / athlíonadh: is féidir le maidhm scanadh i réigiún comharthaí éilimh a chothú nó sreafaí oibre athstoic a spreagadh i do chóras ERP.
• Aisghairm / sábháilteacht: má tá aonad faoi aisghairm, is deis é scanadh chun teagmháil a dhéanamh le pé duine atá á choinneáil — cuir do fhoireann ar an airdeall, nó nocht fógra ar an bpas féin.

Ní theastaíonn vótáil ná baisc oíche ó aon cheann díobh seo. Tarlaíonn siad an túisce a scanaítear an táirge.

Sonraí a choinneáil cothrom le dáta trí client.dpp.update

Is leath den lúb é freagairt do scanadh; is é an leath eile ná an pas féin a choinneáil cruinn. Tá súil ag rialacháin amhail ESPR (EU 2024/1781) agus an Rialachán Ceallraí (EU 2023/1542) go léireoidh sonraí an phas an réaltacht thar shaolré an táirge — lorg carbóin athríofa, treoracha deisithe nuashonraithe, spriocanna ábhair athchúrsáilte a baineadh amach.

Tiomáin na nuashonruithe sin ón gcóras taifid. Nuair a athraíonn luach i do chóras ERP, brúigh chuig an bpas é:

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

Toisc go n-ionchódaíonn an cód QR URL réiteora cobhsaí (https://qr3.app/dpp/{gtin}/{serial}, cuir ?format=jsonld leis le haghaidh JSON-LD), ní athphriontálann tú lipéad riamh chun sonraí a athrú. Fanann an aitheantas socair; fanann an t-ábhar taobh thiar de cothrom le dáta. Déan é seo a phéireáil le qr.updated agus is féidir leat fógra a leathadh amach aon uair a athraíonn pas — ag dúnadh na lúibe idir do chóras ERP, an pas, agus aon duine atá ag faire síos an tsrutha.

Tábla imeachtaí: imeacht → cad atá le huathoibriú

Tosaigh le qr.scanned le haghaidh rannpháirtíochta agus comharthaí réimse; cuir na himeachtaí saolré leis de réir mar a shioncronaíonn tú pasanna isteach i do chórais níos leithne.

Ceisteanna coitianta

An gá dom an síniú a fhíorú má tá URL mo chríochphointe rúnda? Ní mór. Ní rún é URL — sceitheann sé i logaí, i seachfhreastalaithe agus i stair an bhrabhsálaí. Is é fíorú HMAC le verifyWebhook an t-aon rud a chruthaíonn gur tháinig pálasta ó qr3 i ndáiríre.

Cad a tharlaíonn má bhíonn mo chríochphointe as feidhm nuair a lasann imeacht? Admhaigh go tapa le 200 a luaithe atá fíoraithe agat, agus déan obair mhall go hasincronach ionas nach gcuireann fadhbanna sealadacha síos an tsrutha bac riamh ar an bhfreagra. Coinnigh do neamhspleáchas féin ar dpp/code id ionas nach ndéantar seachadadh athráite a chomhaireamh faoi dhó.

An féidir liom GTIN nó sraithuimhir a nuashonrú trí client.dpp.update? Ní féidir — tá GTIN agus sraithuimhir do-athraithe; is iad aitheantas cobhsaí an táirge iad. Ní féidir ach na réimsí sonraí a nuashonrú. Is é an do-athraitheacht sin go díreach a ligeann don chód QR priontáilte fanacht bailí go deo.

Foinsí

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

Tosaigh saor in aisce agus sreangaigh do chéad webhook DPP: app.qr3.app/sign-up