5 min biex taqra Tutorials dpp json-ld epcis gs1-digital-link interoperability

JSON-LD għall-Passaporti Diġitali tal-Prodott (u fejn jidħol EPCIS 2.0)

DPP huwa utli għall-magni biss jekk ikun jinqara mill-magni. Din il-gwida turi l-JSON-LD reali li passaport qr3 jesponi permezz tar-resolver live, kif URL wieħed iservi kemm lill-bnedmin u kemm lill-magni permezz tal-content negotiation, u fejn jidħol l-istandard komplementari ta' avvenimenti EPCIS 2.0.

minn QR3 Redaktion

JSON-LD għall-Passaporti Diġitali tal-Prodott (u fejn jidħol EPCIS 2.0)

Passaport Diġitali tal-Prodott huwa maħsub biex jinqara mill-bnedmin u mill-magni: is-sistema ta' dħul ta' rriċiklatur, API doganali, crawler ta' marketplace, l-iskript ta' awditur tas-sostenibbiltà. Paġna HTML għall-bnedmin biss mhux biżżejjed. Il-passaport irid ikun jinqara mill-magni — payload strutturat li programm jista' janalizza, jorbot u jirraġuna fuqu mingħajr scraping.

Din il-gwida hija għall-iżviluppaturi li jistaqsu d-domanda ovvja li jmiss: ladarba jkolli DPP, kif tabilħaqq magna taqrah? It-tweġiba għal qr3 hija JSON-LD fuq ir-resolver pubbliku. Se nuru r-rispons reali, nispjegaw kif l-istess URL iservi lill-bnedmin u lill-magni, u mbagħad inqiegħdu EPCIS 2.0 — l-istandard komplementari ta' avvenimenti GS1 — fil-kuntest tiegħu.

Xi tfisser il-leġġibbiltà mill-magni għal DPP

Li jinqara mill-magni huwa aktar minn "jirritorna JSON". Għal passaport ta' prodott ifisser tliet affarijiet:

  • Strutturat — kampijiet li parser jista' jindirizza (gtin, name, …), mhux proża li trid issir scraping.
  • Bit-tip u marbut — termini ankrati ma' vokabularji kondiviżi sabiex Product ifisser l-istess ħaġa għal kulħadd. Dak huwa l-Linked Data f'JSON-LD.
  • Stabbli biex jinġieb — URL durabbli wieħed għal kull oġġett li skript jista' jagħmillu GET għal ħajtu kollha tal-prodott.

JSON-LD (JSON for Linking Data) iwassal it-tlieta. Huwa JSON ordinarju flimkien ma' @context li jimmappja kull key ma' terminu f'vokabularju pubbliku — hawnhekk schema.org u l-GS1 Web Vocabulary. Crawler li diġà jifhem schema.org jifhem il-passaport b'ebda integrazzjoni personalizzata.

Id-DPP bħala JSON-LD (curl reali + rispons verifikat)

Kull passaport qr3 jirriżolvi f'URL ta' GS1 Digital Link: https://qr3.app/dpp/{gtin}/{serial}. Żid ?format=jsonld biex titlob il-vista Linked-Data. Kontra d-demo live tal-batterija:

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

jirritorna:

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

Tliet affarijiet li wieħed jinnota:

  • @context huwa array ta' żewġ vokabularji — schema.org għall-web ġenerali u gs1.org/voc/ għat-termini tal-prodotti ta' GS1. Il-keys jirriżolvu kontra t-tnejn.
  • @type: "Product" jgħid lil kwalunkwe konsumatur ta' Linked-Data eżattament x'tip ta' entità hija din.
  • Il-valuri (gtin, name) huma reali u live — dan huwa l-payload attwali, mhux mock.

Dak hu l-punt kollu: l-iskript ta' rriċiklatur ma jeħtieġx client speċifiku għal qr3. Jagħmel HTTP GET, janalizza JSON-LD li diġà jifhem, u jaqra l-GTIN u l-isem tal-prodott direttament.

URL wieħed, żewġ udjenzi: content negotiation

L-istess URL https://qr3.app/dpp/{gtin}/{serial} iservi passaport HTML faċli għall-bnedmin u l-vista tal-magna — is-server jiddeċiedi x'jirritorna abbażi ta' x'jitlob min iċempel. Żewġ modi kif titlob:

Trid Query param Jew Accept header
Paġna HTML għall-bnedmin (default) Accept: text/html
JSON-LD (Linked Data) ?format=jsonld Accept: application/ld+json
JSON sempliċi ?format=json —
Linkset (riżorsi relatati) ?format=linkset —
DCAT-AP (metadata tad-dataset) ?format=dcat-ap —

Għalhekk kamera tat-telefon li tiftaħ il-QR tasal fuq il-passaport HTML li jinqara, filwaqt li skript jitlob l-istess URL għal application/ld+json u jikseb data strutturata:

# Machine view via header negotiation — same URL, no query string
curl -s -H "Accept: application/ld+json" \
  "https://qr3.app/dpp/04019999999902/DEMO-BAT-01"

Identifikatur wieħed, URL wieħed, ħafna rappreżentazzjonijiet. Il-GTIN/serial jibqa' stabbli; il-vista tadatta ruħha għal min iċempel. Dak hu eżattament dak li jagħmel DPP durabbli u interoperabbli fl-istess ħin.

Fejn jidħol EPCIS 2.0 (avvenimenti vs. passaport)

Segwitu komuni: u EPCIS — dan mhux l-istandard ta' GS1 għal dan? Distinzjoni importanti:

  • DPP huwa d-deskrizzjoni statika ta' oġġett wieħed tal-prodott — l-identità tiegħu, il-materjali, il-marka tal-karbonju, il-kapaċità ta' rriċiklaġġ. Iwieġeb "x'inhi din il-ħaġa?" Il-JSON-LD ta' hawn fuq hija dik il-fotografija.
  • EPCIS 2.0 huwa l-istandard ta' GS1 għall-avvenimenti tal-katina tal-provvista — id-data ta' viżibbiltà ta' x'ġara, fejn, meta u għaliex: oġġett ġie kkummissjonat, mibgħut, irċevut, irriċiklat. Iwieġeb "x'ġara lil din il-ħaġa, u fejn tinsab?"

Huma komplementari, mhux f'kompetizzjoni. Il-passaport jgħidlek li l-prodott huwa batterija ta' 5.2 kWh b'35% kontenut rriċiklat; tracka ta' avvenimenti EPCIS tgħidlek li ġiet manifatturata f'Hamburg f'data partikolari, mibgħuta minn DC, u waslet għand rriċiklatur. EPCIS 2.0 innifsu huwa favur JSON/JSON-LD, għalhekk it-tnejn jaqsmu l-istess perspettiva ta' Linked-Data u l-istess identifikaturi ta' GS1 (GTIN + serial) bħala l-key tat-tgħaqid.

Ambitu ta' qr3 (kun preċiż): qr3 joħroġ id-DPP bħala JSON-LD — dak hu dak li juri dan il-post. qr3 ma jipprovdix il-qbid ta' avvenimenti EPCIS jew endpoints EPCIS. Ittratta EPCIS 2.0 hawnhekk bħala l-istandard konċettwali u komplementari li tadotta flimkien ma' DPP għat-traċċabbiltà sħiħa tal-katina tal-provvista, mhux bħala karatteristika ta' qr3.

Għalhekk il-mudell mentali huwa: id-DPP (qr3, JSON-LD) huwa l-folja tal-identità tal-prodott; EPCIS 2.0 (sistema separata) huwa l-ġurnal tal-vjaġġ tiegħu. L-istess identifikaturi, żewġ domandi mwieġba.

Niġġeneraw DPP li jesponi JSON-LD

Ma tagħmel xejn speċjali biex "tippermetti" JSON-LD — oħloq il-passaport u r-resolver iservi kull rappreżentazzjoni awtomatikament:

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

Ladarba jinħoloq, l-URL tal-oġġett iwieġeb liż-żewġ udjenzi immedjatament — l-ebda pass żejjed ta' pubblikazzjoni għall-vista tal-magna.

FAQ

Għaliex JSON-LD u mhux JSON sempliċi? JSON sempliċi huwa strutturat iżda mhux jiddeskrivi lilu nnifsu: konsumatur irid jitgħallem l-ismijiet tal-kampijiet tiegħek. JSON-LD iżid @context, li jimmappja kull key ma' termini ta' schema.org / GS1, sabiex kwalunkwe konsumatur ta' Linked-Data jifhmu mingħajr integrazzjoni personalizzata. Jekk għandek bżonn biss qari mgħaġġel, ?format=json għadu disponibbli.

Jimplimenta qr3 l-EPCIS 2.0? Le. qr3 joħroġ id-DPP bħala JSON-LD. EPCIS 2.0 huwa l-istandard separat u komplementari ta' GS1 għall-avvenimenti tal-katina tal-provvista; tħaddmu flimkien, magħqud bil-GTIN + serial kondiviż.

Kif nikseb il-vista tal-magna? Żid ?format=jsonld mal-URL tar-resolver, jew ibgħat Accept: application/ld+json. It-tnejn jirritornaw l-istess payload ta' Linked-Data.

L-@context huwa stabbli? Jiffissa schema.org flimkien mal-GS1 Web Vocabulary (gs1.org/voc/) — it-tnejn vokabularji pubbliċi u verżjonati, sabiex il-konsumaturi jistgħu joqogħdu fuq it-tifsiriet tat-termini.

Sorsi

Ibda b'xejn u oħloq DPP li jesponi JSON-LD: app.qr3.app/sign-up

Posts relatati

← L-artikli kollha Iġġenera b'xejn