Automatyzacja Cyfrowych Paszportów Produktów za pomocą Webhooków

Większość zespołów traktuje Cyfrowy Paszport Produktu jak stronę: tworzysz go, drukujesz kod QR i zapominasz o nim. To pozostawia najbardziej użyteczny sygnał niewykorzystany. Za każdym razem, gdy ktoś skanuje kod QR na produkcie, jest to zdarzenie — prawdziwa osoba, w prawdziwym kraju, trzymająca prawdziwy egzemplarz, w prawdziwym momencie. Podłącz te zdarzenia do swojego stosu technologicznego, a paszport przestaje być statyczną stroną i staje się front-endem potoku automatyzacji. Ten przewodnik pokazuje, jak subskrybować qr.scanned, weryfikować każdy payload oraz przekształcać skany i aktualizacje w realne przepływy pracy za pomocą SDK qr3.

Dlaczego DPP jest źródłem zdarzeń, a nie statyczną stroną

Wartość paszportu nie tkwi w stronie, którą konsument widzi raz. Tkwi w strumieniu interakcji wokół niego: skanach w terenie, zmianach danych z systemu ERP, przejściach cyklu życia. Każda z nich jest czymś, na co Twoje systemy mogą reagować w czasie rzeczywistym.

Webhooki odwracają zwykły model odpytywania (polling). Zamiast pytać „czy coś się wydarzyło?" w odstępach czasowych, qr3 dzwoni do Ciebie w momencie, gdy to się dzieje. Typy zdarzeń emitowane przez platformę obejmują qr.scanned, a także qr.created, qr.updated i qr.deleted dla zmian cyklu życia. Tym, którego większość zespołów nie wykorzystuje wystarczająco, jest qr.scanned: uruchamia się, gdy konsument, technik lub celnik faktycznie skanuje produkt w terenie.

Payload qr.scanned niesie kontekst potrzebny do działania — w tym kraj zeskanowania oraz identyfikator dpp/code, który określa, który egzemplarz został zeskanowany. To wystarczy, aby napędzać analitykę, uzupełnianie zapasów i logikę wycofania bez udziału człowieka.

Subskrybowanie qr.scanned

Wskaż punkt końcowy webhooka na swoją usługę i obsłuż zdarzenie. SDK qr3 dostarcza weryfikator, więc nie musisz ręcznie parsować surowych treści (raw bodies):

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 jest celowo cienki: weryfikuj, rozgałęziaj według event.type, potwierdzaj szybko za pomocą 200. Wykonuj ciężką pracę (zapisy analityczne, wywołania ERP) asynchronicznie, aby powolny komponent w dole łańcucha nigdy nie blokował potwierdzenia.

Weryfikacja sygnatur (verifyWebhook, HMAC-SHA256) — rób to zawsze

Punkt końcowy webhooka to publiczny adres URL. Każdy, kto go znajdzie, może na niego wysłać żądanie POST. Jeśli ufasz treści bez sprawdzenia, kto ją wysłał, atakujący może sfałszować „skany", wywołać fałszywe ponowne zamówienia lub uruchomić fałszywe flagi wycofania. Zawsze weryfikuj sygnaturę, zanim podejmiesz działanie na podstawie payloadu.

qr3 podpisuje każdy webhook za pomocą HMAC-SHA256 na treści żądania, używając Twojego sekretu punktu końcowego. Sygnatura przybywa w nagłówku żądania qr3-signature. verifyWebhook(body, signature, secret) ponownie oblicza HMAC i porównuje go; jeśli się nie zgadza, zgłasza wyjątek, a Ty odrzucasz żądanie:

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

Trzy zasady, które utrzymują to w uczciwości:

• Weryfikuj wobec surowych bajtów. Ponowna serializacja JSON może zmienić kolejność kluczy i białe znaki, co psuje HMAC. Przechwyć surową treść (powyżej, express.raw).
• Trzymaj sekret w tajemnicy. Żyje w Twoim środowisku, nigdy w kodzie klienckim ani w repozytorium.
• Domyślnie zamykaj (fail closed). Brak ważnej sygnatury → 401, żadnych efektów ubocznych. Nigdy nie „przetwarzaj mimo wszystko" przy niezgodności.

Wzorce: analityka / ponowne zamówienie / wycofanie

Gdy już ufasz zdarzeniu, garść wzorców pokrywa większość tego, czego chcą zespoły:

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

• Analityka: agreguj skany według kraju i egzemplarza, aby zobaczyć rzeczywiste zaangażowanie — które rynki faktycznie skanują i które SKU mają najwięcej interakcji posprzedażowych.
• Ponowne zamówienie / uzupełnianie: nagły wzrost skanów w regionie może zasilać sygnały popytu lub uruchamiać przepływy uzupełniania zapasów w Twoim systemie ERP.
• Wycofanie / bezpieczeństwo: jeśli egzemplarz jest objęty wycofaniem, skan to szansa, aby dotrzeć do tego, kto go trzyma — powiadom swój zespół lub wyświetl komunikat na samym paszporcie.

Żaden z tych przypadków nie wymaga odpytywania ani nocnego przetwarzania wsadowego. Dzieją się w momencie zeskanowania produktu.

Utrzymywanie aktualności danych za pomocą client.dpp.update

Reagowanie na skany to połowa pętli; druga połowa to utrzymywanie samego paszportu w dokładnym stanie. Regulacje takie jak ESPR (EU 2024/1781) i Rozporządzenie w sprawie baterii (EU 2023/1542) oczekują, że dane paszportu będą odzwierciedlać rzeczywistość przez cały cykl życia produktu — przeliczony ślad węglowy, zaktualizowane instrukcje naprawy, osiągnięte cele dotyczące zawartości materiałów z recyklingu.

Napędzaj te aktualizacje z systemu zapisów (system of record). Gdy wartość zmienia się w Twoim systemie ERP, prześlij ją do paszportu:

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

Ponieważ kod QR koduje stabilny adres URL resolvera (https://qr3.app/dpp/{gtin}/{serial}, dodaj ?format=jsonld dla JSON-LD), nigdy nie drukujesz ponownie etykiety, aby zmienić dane. Tożsamość pozostaje stała; treść za nią pozostaje aktualna. Połącz to z qr.updated, a możesz rozesłać powiadomienie za każdym razem, gdy paszport się zmienia — zamykając pętlę między Twoim systemem ERP, paszportem i każdym, kto obserwuje w dole łańcucha.

Tabela zdarzeń: zdarzenie → co zautomatyzować

Zacznij od qr.scanned dla zaangażowania i sygnałów terenowych; dodaj zdarzenia cyklu życia w miarę synchronizowania paszportów z szerszymi systemami.

FAQ

Czy muszę weryfikować sygnaturę, jeśli mój adres URL punktu końcowego jest tajny? Tak. Adres URL nie jest sekretem — wycieka w logach, serwerach proxy i historii przeglądarki. Weryfikacja HMAC za pomocą verifyWebhook to jedyna rzecz, która udowadnia, że payload faktycznie pochodzi z qr3.

Co się stanie, jeśli mój punkt końcowy będzie niedostępny, gdy uruchomi się zdarzenie? Potwierdź szybko za pomocą 200, gdy tylko zweryfikujesz, i wykonuj powolną pracę asynchronicznie, aby przejściowe problemy w dole łańcucha nigdy nie blokowały odpowiedzi. Utrzymuj własną idempotencję na identyfikatorze dpp/code, aby ponowiona dostawa nie była liczona podwójnie.

Czy mogę zaktualizować GTIN lub numer seryjny za pomocą client.dpp.update? Nie — GTIN i numer seryjny są niezmienne; stanowią stabilną tożsamość produktu. Aktualizowalne są tylko pola danych. Ta niezmienność to dokładnie to, co pozwala wydrukowanemu kodowi QR pozostać ważnym na zawsze.

Źródła

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

Zacznij za darmo i podłącz swój pierwszy webhook DPP: app.qr3.app/sign-up