JSON-LD για Ψηφιακά Διαβατήρια Προϊόντων (και πού εντάσσεται το EPCIS 2.0)

Ένα Ψηφιακό Διαβατήριο Προϊόντος προορίζεται να διαβάζεται από ανθρώπους και από μηχανές: το σύστημα παραλαβής ενός ανακυκλωτή, ένα API τελωνείου, ένας crawler μιας αγοράς, το script ενός ελεγκτή βιωσιμότητας. Μια σελίδα HTML μόνο για ανθρώπους δεν αρκεί. Το διαβατήριο πρέπει να είναι αναγνώσιμο από μηχανές — ένα δομημένο payload που ένα πρόγραμμα μπορεί να αναλύσει, να συνδέσει και να επεξεργαστεί λογικά χωρίς scraping.

Αυτός ο οδηγός απευθύνεται σε προγραμματιστές που θέτουν το προφανές επόμενο ερώτημα: μόλις αποκτήσω ένα DPP, πώς το διαβάζει πραγματικά μια μηχανή; Η απάντηση για το qr3 είναι JSON-LD μέσω του δημόσιου resolver. Θα δείξουμε την πραγματική απόκριση, θα εξηγήσουμε πώς το ίδιο URL εξυπηρετεί ανθρώπους και μηχανές, και στη συνέχεια θα τοποθετήσουμε το EPCIS 2.0 — το συμπληρωματικό πρότυπο συμβάντων του GS1 — στο πλαίσιό του.

Τι σημαίνει η αναγνωσιμότητα από μηχανές για ένα DPP

Το «αναγνώσιμο από μηχανές» είναι κάτι περισσότερο από το «επιστρέφει JSON». Για ένα διαβατήριο προϊόντος σημαίνει τρία πράγματα:

Δομημένο — πεδία που ένας parser μπορεί να προσπελάσει (gtin, name, …), όχι κείμενο για scraping.
Με τύπους και συνδεδεμένο — όροι αγκυρωμένοι σε κοινά λεξιλόγια ώστε το Product να σημαίνει το ίδιο πράγμα για όλους. Αυτό είναι το Linked Data στο JSON-LD.
Σταθερό για ανάκτηση — ένα διαρκές URL ανά αντικείμενο που ένα script μπορεί να καλέσει με GET σε όλη τη διάρκεια ζωής του προϊόντος.

Το JSON-LD (JSON for Linking Data) προσφέρει και τα τρία. Είναι κανονικό JSON συν ένα @context που αντιστοιχίζει κάθε κλειδί σε έναν όρο ενός δημόσιου λεξιλογίου — εδώ το schema.org και το GS1 Web Vocabulary. Ένας crawler που ήδη κατανοεί το schema.org κατανοεί το διαβατήριο χωρίς καμία προσαρμοσμένη ενσωμάτωση.

Το DPP ως JSON-LD (πραγματικό curl + επαληθευμένη απόκριση)

Κάθε διαβατήριο qr3 επιλύεται σε ένα URL GS1 Digital Link: https://qr3.app/dpp/{gtin}/{serial}. Προσθέστε ?format=jsonld για να ζητήσετε την προβολή Linked-Data. Στο ζωντανό demo μπαταρίας:

curl -s "https://qr3.app/dpp/04019999999902/DEMO-BAT-01?format=jsonld"

επιστρέφει:

{
  "@context": ["https://schema.org", "https://gs1.org/voc/"],
  "@type": "Product",
  "gtin": "04019999999902",
  "name": "EcoMax 5000 (Demo)"
}

Τρία σημεία αξίζει να προσέξετε:

Το @context είναι ένας πίνακας δύο λεξιλογίων — το schema.org για τον γενικό ιστό και το gs1.org/voc/ για τους όρους προϊόντων του GS1. Τα κλειδιά επιλύονται έναντι και των δύο.
Το @type: "Product" λέει σε κάθε καταναλωτή Linked-Data ακριβώς τι είδους οντότητα είναι αυτή.
Οι τιμές (gtin, name) είναι πραγματικές και ζωντανές — αυτό είναι το πραγματικό payload, όχι ένα mock.

Αυτό ακριβώς είναι το ζητούμενο: το script ενός ανακυκλωτή δεν χρειάζεται έναν πελάτη ειδικό για το qr3. Κάνει ένα HTTP GET, αναλύει JSON-LD που ήδη κατανοεί, και διαβάζει το GTIN και το όνομα του προϊόντος απευθείας.

Ένα URL, δύο κοινά: διαπραγμάτευση περιεχομένου

Το ίδιο URL https://qr3.app/dpp/{gtin}/{serial} εξυπηρετεί ένα φιλικό προς τον άνθρωπο διαβατήριο HTML και την προβολή για μηχανές — ο διακομιστής αποφασίζει τι θα επιστρέψει με βάση το τι ζητάει ο καλών. Δύο τρόποι να το ζητήσετε:

Τι θέλετε	Παράμετρος query	Ή κεφαλίδα Accept
Σελίδα HTML για ανθρώπους	(προεπιλογή)	`Accept: text/html`
JSON-LD (Linked Data)	`?format=jsonld`	`Accept: application/ld+json`
Απλό JSON	`?format=json`	—
Linkset (σχετικοί πόροι)	`?format=linkset`	—
DCAT-AP (μεταδεδομένα συνόλου δεδομένων)	`?format=dcat-ap`	—

Έτσι, μια κάμερα τηλεφώνου που ανοίγει το QR καταλήγει στο αναγνώσιμο διαβατήριο HTML, ενώ ένα script ζητάει από το ταυτόσημο URL το application/ld+json και λαμβάνει δομημένα δεδομένα:

# Προβολή για μηχανές μέσω διαπραγμάτευσης κεφαλίδας — ίδιο URL, χωρίς query string
curl -s -H "Accept: application/ld+json" \
  "https://qr3.app/dpp/04019999999902/DEMO-BAT-01"

Ένα αναγνωριστικό, ένα URL, πολλές αναπαραστάσεις. Το GTIN/serial παραμένει σταθερό· η προβολή προσαρμόζεται στον καλούντα. Αυτό ακριβώς είναι που κάνει ένα DPP ταυτόχρονα διαρκές και διαλειτουργικό.

Πού εντάσσεται το EPCIS 2.0 (συμβάντα έναντι διαβατηρίου)

Ένα συνηθισμένο επόμενο ερώτημα: τι γίνεται με το EPCIS — δεν είναι αυτό το πρότυπο του GS1 για αυτό; Σημαντική διάκριση:

Ένα DPP είναι η στατική περιγραφή ενός μεμονωμένου προϊόντος — η ταυτότητά του, τα υλικά, το αποτύπωμα άνθρακα, η ανακυκλωσιμότητά του. Απαντά στο ερώτημα «τι είναι αυτό το πράγμα;» Το παραπάνω JSON-LD είναι αυτό το στιγμιότυπο.
Το EPCIS 2.0 είναι το πρότυπο του GS1 για συμβάντα εφοδιαστικής αλυσίδας — τα δεδομένα ορατότητας για το τι συνέβη, πού, πότε και γιατί: ένα αντικείμενο τέθηκε σε λειτουργία, απεστάλη, παρελήφθη, ανακυκλώθηκε. Απαντά στο ερώτημα «τι συνέβη σε αυτό το πράγμα, και πού βρίσκεται;»

Είναι συμπληρωματικά, όχι ανταγωνιστικά. Το διαβατήριο σάς λέει ότι το προϊόν είναι μια μπαταρία 5,2 kWh με 35% ανακυκλωμένο περιεχόμενο· ένα ίχνος συμβάντων EPCIS θα σας έλεγε ότι κατασκευάστηκε στο Αμβούργο σε μια συγκεκριμένη ημερομηνία, διακινήθηκε μέσω ενός κέντρου διανομής και έφτασε σε έναν ανακυκλωτή. Το ίδιο το EPCIS 2.0 είναι φιλικό προς JSON/JSON-LD, οπότε τα δύο μοιράζονται την ίδια θεώρηση Linked-Data και τα ίδια αναγνωριστικά GS1 (GTIN + serial) ως κλειδί σύνδεσης.

Πεδίο εφαρμογής του qr3 (ακρίβεια): το qr3 εκθέτει το DPP ως JSON-LD — αυτό ακριβώς δείχνει αυτή η ανάρτηση. Το qr3 δεν παρέχει καταγραφή συμβάντων EPCIS ούτε endpoints EPCIS. Αντιμετωπίστε εδώ το EPCIS 2.0 ως το εννοιολογικό, συμπληρωματικό πρότυπο που θα υιοθετούσατε παράλληλα με ένα DPP για πλήρη ιχνηλασιμότητα εφοδιαστικής αλυσίδας, όχι ως λειτουργία του qr3.

Έτσι το νοητικό μοντέλο είναι: το DPP (qr3, JSON-LD) είναι το φύλλο ταυτότητας του προϊόντος· το EPCIS 2.0 (ξεχωριστό σύστημα) είναι το ημερολόγιο διαδρομής του. Ίδια αναγνωριστικά, δύο ερωτήματα που απαντώνται.

Δημιουργία ενός DPP που εκθέτει JSON-LD

Δεν κάνετε τίποτα ιδιαίτερο για να «ενεργοποιήσετε» το JSON-LD — δημιουργήστε το διαβατήριο και ο resolver εξυπηρετεί αυτόματα κάθε αναπαράσταση:

import { QR3 } from "@qr3/sdk";

const client = new QR3({ apiKey: process.env.QR3_API_KEY! });

const passport = await client.dpp.create({
  gtin: "04019999999902",
  serial: "SN-00012345",
  product_name: "PowerCell 5 kWh LFP",
  manufacturer: "ExampleTech GmbH",
  origin_country: "DE",
  category: "battery",
  market_countries: ["DE", "FR", "AT"],
  status: "live",
  battery_data: {
    capacity_kwh: 5,
    carbon_footprint_kg: 62,
    recycled_content_pct: 12,
    recyclability_pct: 95,
  },
});

// Το διαβατήριο επιλύεται πλέον στο https://qr3.app/dpp/04019999999902/SN-00012345
// Οι άνθρωποι λαμβάνουν HTML· οι μηχανές προσθέτουν ?format=jsonld (ή στέλνουν Accept: application/ld+json).
console.log(passport.qr.svg); // Το QR κωδικοποιεί το GS1 Digital Link προς τον resolver

Μόλις δημιουργηθεί, το URL του αντικειμένου απαντά αμέσως και στα δύο κοινά — χωρίς επιπλέον βήμα δημοσίευσης για την προβολή των μηχανών.

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

Γιατί JSON-LD και όχι απλό JSON; Το απλό JSON είναι δομημένο αλλά όχι αυτοπεριγραφικό: ο καταναλωτής πρέπει να μάθει τα ονόματα των πεδίων σας. Το JSON-LD προσθέτει το @context, αντιστοιχίζοντας κάθε κλειδί σε όρους schema.org / GS1, ώστε κάθε καταναλωτής Linked-Data να το κατανοεί χωρίς προσαρμοσμένη ενσωμάτωση. Αν χρειάζεστε μόνο μια γρήγορη ανάγνωση, το ?format=json παραμένει διαθέσιμο.

Υλοποιεί το qr3 το EPCIS 2.0; Όχι. Το qr3 εκθέτει το DPP ως JSON-LD. Το EPCIS 2.0 είναι το ξεχωριστό, συμπληρωματικό πρότυπο του GS1 για συμβάντα εφοδιαστικής αλυσίδας· θα το εκτελούσατε παράλληλα, συνδεδεμένο μέσω του κοινού GTIN + serial.

Πώς λαμβάνω την προβολή για μηχανές; Προσθέστε ?format=jsonld στο URL του resolver, ή στείλτε Accept: application/ld+json. Και τα δύο επιστρέφουν το ίδιο payload Linked-Data.

Είναι το @context σταθερό; Καθηλώνει το schema.org συν το GS1 Web Vocabulary (gs1.org/voc/) — και τα δύο δημόσια, εκδοσιολογημένα λεξιλόγια, ώστε οι καταναλωτές να μπορούν να βασίζονται στις σημασίες των όρων.

Πηγές

Ξεκινήστε δωρεάν και δημιουργήστε ένα DPP που εκθέτει JSON-LD: app.qr3.app/sign-up