JSON-LD pentru Pașapoartele Digitale ale Produselor (și unde se încadrează EPCIS 2.0)

Un Pașaport Digital al Produsului este menit să fie citit de oameni și de mașini: sistemul de recepție al unui reciclator, un API vamal, un crawler de marketplace, scriptul unui auditor de sustenabilitate. O pagină HTML destinată exclusiv oamenilor nu este suficientă. Pașaportul trebuie să fie lizibil de către mașini — un payload structurat pe care un program îl poate analiza, lega și interpreta fără scraping.

Acest ghid se adresează dezvoltatorilor care își pun întrebarea evidentă care urmează: odată ce am un DPP, cum îl citește efectiv o mașină? Răspunsul pentru qr3 este JSON-LD prin resolverul public. Vom arăta răspunsul real, vom explica modul în care aceeași adresă URL servește oamenilor și mașinilor, iar apoi vom plasa în context EPCIS 2.0 — standardul complementar de evenimente GS1.

Ce înseamnă lizibilitatea de către mașini pentru un DPP

Lizibil de către mașini înseamnă mai mult decât „returnează JSON". Pentru un pașaport de produs înseamnă trei lucruri:

Structurat — câmpuri pe care un parser le poate adresa (gtin, name, …), nu text de extras prin scraping.
Tipizat și legat — termeni ancorați la vocabulare comune, astfel încât Product să însemne același lucru pentru toată lumea. Aceasta este componenta Linked Data din JSON-LD.
Stabil la accesare — o singură adresă URL durabilă per articol, pe care un script o poate accesa cu GET pe toată durata de viață a produsului.

JSON-LD (JSON for Linking Data) oferă toate cele trei. Este JSON obișnuit plus un @context care mapează fiecare cheie la un termen dintr-un vocabular public — aici schema.org și Vocabularul Web GS1. Un crawler care înțelege deja schema.org înțelege pașaportul fără nicio integrare personalizată.

DPP-ul ca JSON-LD (curl real + răspuns verificat)

Fiecare pașaport qr3 se rezolvă la o adresă URL GS1 Digital Link: https://qr3.app/dpp/{gtin}/{serial}. Adaugă ?format=jsonld pentru a solicita vizualizarea Linked-Data. Pentru demo-ul live cu bateria:

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

returnează:

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

Trei aspecte de remarcat:

@context este un array de două vocabulare — schema.org pentru web-ul general și gs1.org/voc/ pentru termenii de produs GS1. Cheile se rezolvă în raport cu ambele.
@type: "Product" îi spune oricărui consumator de Linked-Data exact ce fel de entitate este aceasta.
Valorile (gtin, name) sunt reale și live — acesta este payload-ul efectiv, nu un mock.

Acesta este exact scopul: scriptul unui reciclator nu are nevoie de un client specific qr3. Face un GET HTTP, analizează JSON-LD-ul pe care îl înțelege deja și citește direct GTIN-ul și numele produsului.

O singură adresă URL, două audiențe: negocierea conținutului

Aceeași adresă URL https://qr3.app/dpp/{gtin}/{serial} servește un pașaport HTML prietenos pentru oameni și vizualizarea pentru mașini — serverul decide ce să returneze în funcție de ceea ce solicită apelantul. Două moduri de a solicita:

Ce dorești	Parametru de interogare	Sau antet Accept
Pagină HTML pentru oameni	(implicit)	`Accept: text/html`
JSON-LD (Linked Data)	`?format=jsonld`	`Accept: application/ld+json`
JSON simplu	`?format=json`	—
Linkset (resurse asociate)	`?format=linkset`	—
DCAT-AP (metadate de set de date)	`?format=dcat-ap`	—

Astfel, camera unui telefon care deschide codul QR ajunge pe pașaportul HTML lizibil, în timp ce un script solicită aceeași adresă URL identică pentru application/ld+json și primește date structurate:

# Vizualizare pentru mașini prin negocierea antetului — aceeași adresă URL, fără șir de interogare
curl -s -H "Accept: application/ld+json" \
  "https://qr3.app/dpp/04019999999902/DEMO-BAT-01"

Un singur identificator, o singură adresă URL, multiple reprezentări. GTIN-ul/serialul rămâne stabil; vizualizarea se adaptează apelantului. Exact acest lucru face un DPP simultan durabil și interoperabil.

Unde se încadrează EPCIS 2.0 (evenimente vs. pașaport)

O întrebare frecventă care urmează: dar EPCIS — nu acela este standardul GS1 pentru asta? O distincție importantă:

Un DPP este descrierea statică a unui articol de produs — identitatea sa, materialele, amprenta de carbon, reciclabilitatea. El răspunde la întrebarea „ce este acest obiect?" JSON-LD-ul de mai sus este acest instantaneu.
EPCIS 2.0 este standardul GS1 pentru evenimentele din lanțul de aprovizionare — datele de vizibilitate despre ce s-a întâmplat, unde, când și de ce: un articol a fost pus în circulație, expediat, recepționat, reciclat. El răspunde la întrebarea „ce s-a întâmplat cu acest obiect și unde se află?"

Acestea sunt complementare, nu concurente. Pașaportul îți spune că produsul este o baterie de 5,2 kWh cu 35% conținut reciclat; un istoric de evenimente EPCIS ți-ar spune că a fost fabricat la Hamburg la o anumită dată, expediat printr-un centru de distribuție și ajuns la un reciclator. EPCIS 2.0 este el însuși compatibil cu JSON/JSON-LD, astfel încât cele două împărtășesc aceeași viziune Linked-Data și aceiași identificatori GS1 (GTIN + serial) drept cheie de îmbinare.

Domeniul de aplicare qr3 (cu precizie): qr3 emite DPP-ul ca JSON-LD — exact ceea ce demonstrează acest articol. qr3 nu oferă captarea evenimentelor EPCIS și nici endpointuri EPCIS. Tratează EPCIS 2.0 aici drept standardul conceptual, complementar pe care l-ai adopta alături de un DPP pentru o trasabilitate completă a lanțului de aprovizionare, nu drept o funcționalitate qr3.

Așadar, modelul mental este: DPP-ul (qr3, JSON-LD) este fișa de identitate a produsului; EPCIS 2.0 (sistem separat) este jurnalul său de călătorie. Aceiași identificatori, două întrebări la care se răspunde.

Generarea unui DPP care expune JSON-LD

Nu trebuie să faci nimic special pentru a „activa" JSON-LD — creează pașaportul, iar resolverul servește automat fiecare reprezentare:

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

// The passport now resolves at https://qr3.app/dpp/04019999999902/SN-00012345
// Humans get HTML; machines append ?format=jsonld (or send Accept: application/ld+json).
console.log(passport.qr.svg); // QR encodes the GS1 Digital Link to the resolver

Odată creat, adresa URL a articolului răspunde imediat ambelor audiențe — fără un pas suplimentar de publicare pentru vizualizarea destinată mașinilor.

Întrebări frecvente

De ce JSON-LD și nu JSON simplu? JSON-ul simplu este structurat, dar nu autodescriptiv: consumatorul trebuie să învețe numele câmpurilor tale. JSON-LD adaugă @context, mapând fiecare cheie la termeni schema.org / GS1, astfel încât orice consumator de Linked-Data îl înțelege fără o integrare personalizată. Dacă ai nevoie doar de o citire rapidă, ?format=json rămâne disponibil.

Implementează qr3 EPCIS 2.0? Nu. qr3 emite DPP-ul ca JSON-LD. EPCIS 2.0 este standardul GS1 separat, complementar, pentru evenimentele din lanțul de aprovizionare; l-ai rula alături, îmbinat prin GTIN-ul + serialul comune.

Cum obțin vizualizarea pentru mașini? Adaugă ?format=jsonld la adresa URL a resolverului sau trimite Accept: application/ld+json. Ambele returnează același payload Linked-Data.

Este @context stabil? El fixează schema.org plus Vocabularul Web GS1 (gs1.org/voc/) — ambele vocabulare publice, versionate, astfel încât consumatorii se pot baza pe semnificațiile termenilor.

Surse

Începe gratuit și creează un DPP care expune JSON-LD: app.qr3.app/sign-up