Digitaalisten tuotepassien automatisointi webhookien avulla

Useimmat tiimit kohtelevat digitaalista tuotepassia sivuna: luot sen, tulostat QR-koodin ja unohdat sen. Näin hyödyllisin signaali jää käyttämättä. Joka kerta, kun joku skannaa tuotteen QR-koodin, kyseessä on tapahtuma — todellinen ihminen, todellisessa maassa, pitelemässä todellista yksikköä, todellisella hetkellä. Kytke nämä tapahtumat osaksi järjestelmäpinoasi, niin passi lakkaa olemasta staattinen sivu ja muuttuu automaatioputken käyttöliittymäksi. Tässä oppaassa näytetään, kuinka tilataan qr.scanned, varmennetaan jokainen hyötykuorma ja muutetaan skannaukset ja päivitykset oikeiksi työnkuluiksi qr3-SDK:n avulla.

Miksi DPP on tapahtumalähde, ei staattinen sivu

Passin arvo ei ole sivu, jonka kuluttaja näkee kerran. Se on sitä ympäröivä vuorovaikutusten virta: skannaukset kentällä, tietomuutokset ERP-järjestelmästäsi, elinkaaren siirtymät. Jokainen näistä on jotain, johon järjestelmäsi voivat reagoida reaaliajassa.

Webhookit kääntävät tavanomaisen kyselymallin päälaelleen. Sen sijaan, että kysyisit "onko mitään tapahtunut?" ajastimen avulla, qr3 kutsuu sinua sillä hetkellä, kun jotain tapahtuu. Alustan lähettämiin tapahtumatyyppeihin kuuluvat qr.scanned sekä qr.created, qr.updated ja qr.deleted elinkaaren muutoksia varten. Tapahtuma, jota useimmat tiimit hyödyntävät liian vähän, on qr.scanned: se laukeaa, kun kuluttaja, asentaja tai tullivirkailija todella skannaa tuotteen kentällä.

qr.scanned-hyötykuorma kuljettaa toiminnan kannalta tarvitsemasi kontekstin — mukaan lukien skannauksen maan ja dpp/code id -tunnisteen, joka kertoo, mikä yksikkö skannattiin. Se riittää ohjaamaan analytiikkaa, täydennystä ja takaisinvetologiikkaa ilman ihmistä silmukassa.

qr.scanned-tapahtuman tilaaminen

Osoita webhook-päätepiste palveluusi ja käsittele tapahtuma. qr3-SDK toimittaa varmentajan, joten sinun ei tarvitse jäsentää raakahyötykuormia käsin:

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

Käsittelijä on tarkoituksella ohut: varmenna, haaraudu event.type-arvon mukaan ja kuittaa nopeasti 200-koodilla. Tee raskas työ (analytiikkakirjoitukset, ERP-kutsut) asynkronisesti, jotta hidas alavirran palvelu ei koskaan estä kuittausta.

Allekirjoitusten varmentaminen (verifyWebhook, HMAC-SHA256) — tee tämä aina

Webhook-päätepiste on julkinen URL. Kuka tahansa, joka sen löytää, voi lähettää siihen POST-pyynnön. Jos luotat hyötykuormaan tarkistamatta, kuka sen lähetti, hyökkääjä voi väärentää "skannauksia", laukaista valheellisia uudelleentilauksia tai sytyttää vääriä takaisinvetomerkintöjä. Varmenna allekirjoitus aina ennen kuin toimit hyötykuorman perusteella.

qr3 allekirjoittaa jokaisen webhookin HMAC-SHA256:lla pyynnön rungon yli käyttäen päätepisteesi salaisuutta. Allekirjoitus saapuu qr3-signature-pyyntöotsikossa. verifyWebhook(body, signature, secret) laskee HMAC:n uudelleen ja vertaa sitä; jos se ei täsmää, se heittää poikkeuksen ja hylkäät pyynnön:

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

Kolme sääntöä, jotka pitävät tämän rehellisenä:

• Varmenna raakatavuja vastaan. JSON:n uudelleenserialisointi voi järjestää avaimet uudelleen ja muuttaa välilyöntejä, mikä rikkoo HMAC:n. Kaappaa raakaruoko (yllä, express.raw).
• Pidä salaisuus salassa. Se sijaitsee ympäristössäsi, ei koskaan asiakaskoodissa tai repositoriossa.
• Epäonnistu suljettuna. Ei kelvollista allekirjoitusta → 401, ei sivuvaikutuksia. Älä koskaan "käsittele silti", jos täsmäys epäonnistuu.

Mallit: analytiikka / uudelleentilaus / takaisinveto

Kun luotat tapahtumaan, kourallinen malleja kattaa suurimman osan siitä, mitä tiimit haluavat:

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

• Analytiikka: kokoa skannaukset maittain ja yksiköittäin nähdäksesi todellisen sitoutumisen — mitkä markkinat oikeasti skannaavat ja mitkä tuotenimikkeet saavat eniten myynnin jälkeistä vuorovaikutusta.
• Uudelleentilaus / täydennys: skannausten ryöppy alueella voi syöttää kysyntäsignaaleja tai laukaista täydennystyönkulkuja ERP-järjestelmässäsi.
• Takaisinveto / turvallisuus: jos yksikkö on takaisinvedossa, skannaus on tilaisuus tavoittaa se, joka sitä pitelee — hälytä tiimisi tai nosta ilmoitus esiin itse passissa.

Mikään näistä ei tarvitse kyselyä tai öistä eräajoa. Ne tapahtuvat sillä hetkellä, kun tuote skannataan.

Tietojen pitäminen ajan tasalla client.dpp.update-metodilla

Skannauksiin reagoiminen on puolet silmukasta; toinen puoli on itse passin pitäminen tarkkana. Sääntelyt, kuten ESPR (EU 2024/1781) ja akkuasetus (EU 2023/1542), edellyttävät, että passin tiedot heijastavat todellisuutta tuotteen elinkaaren ajan — uudelleenlaskettu hiilijalanjälki, päivitetyt korjausohjeet, saavutetut kierrätysmateriaalitavoitteet.

Ohjaa nämä päivitykset päärekisteristä. Kun arvo muuttuu ERP-järjestelmässäsi, työnnä se passiin:

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

Koska QR-koodi koodaa vakaan resolver-URL:n (https://qr3.app/dpp/{gtin}/{serial}, lisää ?format=jsonld JSON-LD:tä varten), sinun ei koskaan tarvitse tulostaa nimilappua uudelleen tietojen muuttamiseksi. Identiteetti pysyy kiinteänä; sen takana oleva sisältö pysyy ajan tasalla. Yhdistä tämä qr.updated-tapahtumaan, niin voit lähettää ilmoituksen aina, kun passi muuttuu — sulkien silmukan ERP-järjestelmäsi, passin ja kenen tahansa alavirrassa seuraavan välillä.

Tapahtumataulukko: tapahtuma → mitä automatisoida

Aloita qr.scanned-tapahtumasta sitoutumisen ja kenttäsignaalien osalta; lisää elinkaaritapahtumat sitä mukaa, kun synkronoit passeja laajempiin järjestelmiisi.

UKK

Pitääkö minun varmentaa allekirjoitus, jos päätepisteeni URL on salainen? Kyllä. URL ei ole salaisuus — se vuotaa lokeihin, välityspalvelimiin ja selaimen historiaan. HMAC-varmennus verifyWebhook-metodilla on ainoa asia, joka todistaa, että hyötykuorma todella tuli qr3:sta.

Mitä tapahtuu, jos päätepisteeni on alhaalla, kun tapahtuma laukeaa? Kuittaa nopeasti 200-koodilla heti varmennettuasi ja tee hidas työ asynkronisesti, jotta hetkelliset alavirran ongelmat eivät koskaan pysäytä vastausta. Pidä yllä omaa idempotenssia dpp/code id -tunnisteen perusteella, jotta uudelleen toimitettua viestiä ei lasketa kahdesti.

Voinko päivittää GTIN:n tai sarjanumeron client.dpp.update-metodilla? En — GTIN ja sarjanumero ovat muuttumattomia; ne ovat tuotteen vakaa identiteetti. Vain tietokentät ovat päivitettävissä. Juuri tämä muuttumattomuus pitää tulostetun QR-koodin pätevänä ikuisesti.

Lähteet

• EU ESPR — asetus (EU) 2024/1781
• EU:n akkuasetus 2023/1542
• HMAC — RFC 2104

Aloita ilmaiseksi ja kytke ensimmäinen DPP-webhookisi: app.qr3.app/sign-up