Αυτοματοποίηση Ψηφιακών Διαβατηρίων Προϊόντος με Webhooks

Οι περισσότερες ομάδες αντιμετωπίζουν ένα Ψηφιακό Διαβατήριο Προϊόντος ως μια σελίδα: το δημιουργείτε, εκτυπώνετε τον κωδικό QR και το ξεχνάτε. Έτσι όμως αφήνετε αναξιοποίητο το πιο χρήσιμο σήμα. Κάθε φορά που κάποιος σαρώνει τον κωδικό QR σε ένα προϊόν, αυτό είναι ένα συμβάν — ένας πραγματικός άνθρωπος, σε μια πραγματική χώρα, που κρατά μια πραγματική μονάδα, σε μια πραγματική στιγμή. Συνδέστε αυτά τα συμβάντα με το stack σας και το διαβατήριο παύει να είναι μια στατική σελίδα και γίνεται το front end ενός pipeline αυτοματοποίησης. Αυτός ο οδηγός δείχνει πώς να εγγραφείτε στο qr.scanned, να επαληθεύσετε κάθε payload και να μετατρέψετε σαρώσεις και ενημερώσεις σε πραγματικές ροές εργασίας με το qr3 SDK.

Γιατί ένα DPP είναι πηγή συμβάντων, όχι στατική σελίδα

Η αξία ενός διαβατηρίου δεν είναι η σελίδα που βλέπει ένας καταναλωτής μία φορά. Είναι η ροή των αλληλεπιδράσεων γύρω από αυτό: σαρώσεις στο πεδίο, αλλαγές δεδομένων από το ERP σας, μεταβάσεις στον κύκλο ζωής. Καθένα από αυτά είναι κάτι στο οποίο τα συστήματά σας μπορούν να αντιδράσουν σε πραγματικό χρόνο.

Τα Webhooks αντιστρέφουν το συνηθισμένο μοντέλο polling. Αντί να ρωτάτε «έχει συμβεί κάτι;» σε ένα χρονόμετρο, το qr3 καλεί εσάς τη στιγμή που συμβαίνει. Οι τύποι συμβάντων που εκπέμπει η πλατφόρμα περιλαμβάνουν το qr.scanned, καθώς και τα qr.created, qr.updated και qr.deleted για αλλαγές στον κύκλο ζωής. Αυτό που οι περισσότερες ομάδες υποχρησιμοποιούν είναι το qr.scanned: ενεργοποιείται όταν ένας καταναλωτής, τεχνικός ή τελωνειακός υπάλληλος σαρώνει πραγματικά ένα προϊόν στο πεδίο.

Ένα payload qr.scanned φέρει το πλαίσιο που χρειάζεστε για να δράσετε — συμπεριλαμβανομένης της χώρας της σάρωσης και του dpp/code id που προσδιορίζει ποια μονάδα σαρώθηκε. Αυτό αρκεί για να καθοδηγήσει analytics, αναπλήρωση αποθεμάτων και λογική ανάκλησης χωρίς ανθρώπινη παρέμβαση.

Εγγραφή στο qr.scanned

Στρέψτε ένα endpoint webhook προς την υπηρεσία σας και χειριστείτε το συμβάν. Το qr3 SDK περιλαμβάνει έναν verifier ώστε να μην αναλύετε ακατέργαστα 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 είναι σκόπιμα λιτός: επαληθεύστε, διακλαδώστε με βάση το event.type, επιβεβαιώστε γρήγορα με ένα 200. Κάντε τη βαριά δουλειά (εγγραφές analytics, κλήσεις ERP) ασύγχρονα, ώστε ένα αργό downstream να μην μπλοκάρει ποτέ την επιβεβαίωση.

Επαλήθευση υπογραφών (verifyWebhook, HMAC-SHA256) — κάντε το πάντα

Ένα endpoint webhook είναι μια δημόσια διεύθυνση URL. Όποιος το βρει μπορεί να κάνει POST σε αυτό. Αν εμπιστεύεστε το body χωρίς να ελέγξετε ποιος το έστειλε, ένας επιτιθέμενος μπορεί να πλαστογραφήσει «σαρώσεις», να ενεργοποιήσει ψεύτικες επαναπαραγγελίες ή να πυροδοτήσει εσφαλμένες σημάνσεις ανάκλησης. Επαληθεύετε πάντα την υπογραφή προτού δράσετε με βάση ένα payload.

Το qr3 υπογράφει κάθε webhook με HMAC-SHA256 πάνω στο body του αιτήματος, χρησιμοποιώντας το μυστικό του endpoint σας. Η υπογραφή φτάνει στην κεφαλίδα αιτήματος qr3-signature. Το verifyWebhook(body, signature, secret) υπολογίζει εκ νέου το HMAC και το συγκρίνει· αν δεν ταιριάζει, ρίχνει εξαίρεση και απορρίπτετε το αίτημα:

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

Τρεις κανόνες που διατηρούν αυτό το πράγμα έντιμο:

• Επαληθεύετε ως προς τα ακατέργαστα bytes. Η εκ νέου σειριοποίηση JSON μπορεί να αναδιατάξει τα κλειδιά και να αλλάξει τα κενά, πράγμα που σπάει το HMAC. Καταγράψτε το ακατέργαστο body (παραπάνω, express.raw).
• Κρατήστε το μυστικό μυστικό. Ζει στο περιβάλλον σας, ποτέ σε κώδικα πελάτη ή σε ένα repo.
• Αποτυγχάνετε κλειστά (fail closed). Καμία έγκυρη υπογραφή → 401, καμία παρενέργεια. Ποτέ μην «επεξεργάζεστε ούτως ή άλλως» σε περίπτωση αναντιστοιχίας.

Μοτίβα: analytics / επαναπαραγγελία / ανάκληση

Μόλις εμπιστευτείτε το συμβάν, μια χούφτα μοτίβα καλύπτουν τα περισσότερα από αυτά που θέλουν οι ομάδες:

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

• Analytics: συγκεντρώστε τις σαρώσεις ανά χώρα και μονάδα για να δείτε την πραγματική εμπλοκή — ποιες αγορές πραγματικά σαρώνουν και ποια SKU παρουσιάζουν την περισσότερη αλληλεπίδραση μετά την πώληση.
• Επαναπαραγγελία / αναπλήρωση: μια έκρηξη σαρώσεων σε μια περιοχή μπορεί να τροφοδοτήσει σήματα ζήτησης ή να ενεργοποιήσει ροές εργασίας αναπλήρωσης αποθεμάτων στο ERP σας.
• Ανάκληση / ασφάλεια: αν μια μονάδα τελεί υπό ανάκληση, μια σάρωση είναι μια ευκαιρία να προσεγγίσετε όποιον την κρατά — ειδοποιήστε την ομάδα σας ή εμφανίστε μια ειδοποίηση στο ίδιο το διαβατήριο.

Κανένα από αυτά δεν χρειάζεται polling ή νυχτερινό batch. Συμβαίνουν τη στιγμή ακριβώς που σαρώνεται το προϊόν.

Διατήρηση ενημερωμένων δεδομένων μέσω client.dpp.update

Η αντίδραση στις σαρώσεις είναι το μισό του βρόχου· το άλλο μισό είναι η διατήρηση του ίδιου του διαβατηρίου ακριβούς. Κανονισμοί όπως ο ESPR (EU 2024/1781) και ο Κανονισμός για τις Μπαταρίες (EU 2023/1542) αναμένουν τα δεδομένα του διαβατηρίου να αντικατοπτρίζουν την πραγματικότητα καθ' όλη τη διάρκεια ζωής του προϊόντος — επανυπολογισμένο αποτύπωμα άνθρακα, ενημερωμένες οδηγίες επισκευής, επιτευχθέντες στόχους ανακυκλωμένου περιεχομένου.

Καθοδηγήστε αυτές τις ενημερώσεις από το σύστημα καταγραφής. Όταν μια τιμή αλλάζει στο ERP σας, ωθήστε την στο διαβατήριο:

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

Επειδή ο κωδικός QR κωδικοποιεί μια σταθερή διεύθυνση URL resolver (https://qr3.app/dpp/{gtin}/{serial}, προσθέστε ?format=jsonld για JSON-LD), δεν εκτυπώνετε ποτέ ξανά μια ετικέτα για να αλλάξετε δεδομένα. Η ταυτότητα παραμένει σταθερή· το περιεχόμενο πίσω από αυτήν παραμένει ενημερωμένο. Συνδυάστε το με το qr.updated και μπορείτε να διαχέετε μια ειδοποίηση κάθε φορά που αλλάζει ένα διαβατήριο — κλείνοντας τον βρόχο μεταξύ του ERP σας, του διαβατηρίου και οποιουδήποτε παρακολουθεί downstream.

Ένας πίνακας συμβάντων: συμβάν → τι να αυτοματοποιήσετε

Ξεκινήστε με το qr.scanned για εμπλοκή και σήματα πεδίου· προσθέστε τα συμβάντα κύκλου ζωής καθώς συγχρονίζετε τα διαβατήρια στα ευρύτερα συστήματά σας.

Συχνές ερωτήσεις

Πρέπει να επαληθεύσω την υπογραφή αν η διεύθυνση URL του endpoint μου είναι μυστική; Ναι. Μια διεύθυνση URL δεν είναι μυστικό — διαρρέει σε logs, proxies και ιστορικό προγράμματος περιήγησης. Η επαλήθευση HMAC με το verifyWebhook είναι το μόνο πράγμα που αποδεικνύει ότι ένα payload προήλθε πραγματικά από το qr3.

Τι συμβαίνει αν το endpoint μου είναι εκτός λειτουργίας όταν ενεργοποιηθεί ένα συμβάν; Επιβεβαιώστε γρήγορα με 200 μόλις επαληθεύσετε, και κάντε την αργή δουλειά ασύγχρονα, ώστε παροδικά προβλήματα downstream να μην καθυστερούν ποτέ την απόκριση. Διατηρήστε τη δική σας idempotency στο dpp/code id, ώστε μια επαναλαμβανόμενη παράδοση να μην μετράται διπλά.

Μπορώ να ενημερώσω το GTIN ή το serial μέσω client.dpp.update; Όχι — το GTIN και το serial είναι αμετάβλητα· αποτελούν τη σταθερή ταυτότητα του προϊόντος. Μόνο τα πεδία δεδομένων μπορούν να ενημερωθούν. Αυτή ακριβώς η αμεταβλητότητα είναι που επιτρέπει στον εκτυπωμένο κωδικό QR να παραμένει έγκυρος για πάντα.

Πηγές

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

Ξεκινήστε δωρεάν και συνδέστε το πρώτο σας DPP webhook: app.qr3.app/sign-up