JSON-LD para Passaportes Digitais de Produto (e onde o EPCIS 2.0 se encaixa)

Um Passaporte Digital de Produto destina-se a ser lido por pessoas e por máquinas: o sistema de receção de um reciclador, uma API alfandegária, um crawler de um marketplace, o script de um auditor de sustentabilidade. Uma página HTML apenas para humanos não é suficiente. O passaporte tem de ser legível por máquina — uma carga útil estruturada que um programa consiga analisar, ligar e sobre a qual consiga raciocinar sem recorrer a scraping.

Este guia destina-se a programadores que fazem a pergunta óbvia seguinte: depois de ter um DPP, como é que uma máquina o lê de facto? A resposta para o qr3 é JSON-LD através do resolver público. Vamos mostrar a resposta real, explicar como o mesmo URL serve humanos e máquinas, e depois situar o EPCIS 2.0 — o padrão complementar de eventos da GS1 — no seu contexto.

O que significa legibilidade por máquina para um DPP

Legível por máquina é mais do que "devolver JSON". Para um passaporte de produto, significa três coisas:

Estruturado — campos que um parser consegue endereçar (gtin, name, …), não prosa para fazer scraping.
Tipado e ligado — termos ancorados a vocabulários partilhados, de modo a que Product signifique o mesmo para toda a gente. Isso é o Linked Data no JSON-LD.
Estável para obter — um URL durável por item ao qual um script possa fazer GET durante toda a vida do produto.

O JSON-LD (JSON for Linking Data) entrega os três. É JSON comum mais um @context que mapeia cada chave para um termo num vocabulário público — aqui schema.org e o GS1 Web Vocabulary. Um crawler que já entende schema.org entende o passaporte com zero integração personalizada.

O DPP como JSON-LD (curl real + resposta verificada)

Todos os passaportes qr3 resolvem-se num URL GS1 Digital Link: https://qr3.app/dpp/{gtin}/{serial}. Adicione ?format=jsonld para pedir a vista Linked Data. Contra a demo de bateria ao vivo:

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

devolve:

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

Três coisas a reter:

@context é um array de dois vocabulários — schema.org para a web geral e gs1.org/voc/ para os termos de produto da GS1. As chaves resolvem-se contra ambos.
@type: "Product" diz a qualquer consumidor de Linked Data exatamente que tipo de entidade isto é.
Os valores (gtin, name) são reais e estão ao vivo — esta é a carga útil efetiva, não um mock.

É esse precisamente o objetivo: o script de um reciclador não precisa de um cliente específico do qr3. Faz um GET HTTP, analisa o JSON-LD que já entende, e lê o GTIN e o nome do produto diretamente.

Um URL, dois públicos: negociação de conteúdo

O mesmo URL https://qr3.app/dpp/{gtin}/{serial} serve um passaporte HTML acessível a humanos e a vista para máquinas — o servidor decide o que devolver com base no que o chamador pede. Duas formas de pedir:

O que quer	Parâmetro de query	Ou cabeçalho Accept
Página HTML para humanos	(predefinição)	`Accept: text/html`
JSON-LD (Linked Data)	`?format=jsonld`	`Accept: application/ld+json`
JSON simples	`?format=json`	—
Linkset (recursos relacionados)	`?format=linkset`	—
DCAT-AP (metadados do conjunto de dados)	`?format=dcat-ap`	—

Assim, a câmara de um telemóvel que abre o QR aterra no passaporte HTML legível, enquanto um script pede ao URL idêntico o tipo application/ld+json e obtém dados estruturados:

# Vista para máquinas via negociação por cabeçalho — mesmo URL, sem query string
curl -s -H "Accept: application/ld+json" \
  "https://qr3.app/dpp/04019999999902/DEMO-BAT-01"

Um identificador, um URL, muitas representações. O GTIN/serial mantém-se estável; a vista adapta-se ao chamador. É exatamente isso que torna um DPP durável e interoperável ao mesmo tempo.

Onde o EPCIS 2.0 se encaixa (eventos vs. passaporte)

Uma questão comum a seguir: e o EPCIS — não é esse o padrão da GS1 para isto? Distinção importante:

Um DPP é a descrição estática de um item de produto — a sua identidade, materiais, pegada de carbono, reciclabilidade. Responde a "o que é esta coisa?" O JSON-LD acima é esse instantâneo.
O EPCIS 2.0 é o padrão da GS1 para eventos da cadeia de abastecimento — os dados de visibilidade sobre o que aconteceu, onde, quando e porquê: um item foi comissionado, expedido, recebido, reciclado. Responde a "o que aconteceu a esta coisa, e onde está?"

São complementares, não concorrentes. O passaporte diz-lhe que o produto é uma bateria de 5,2 kWh com 35% de conteúdo reciclado; um rasto de eventos EPCIS dir-lhe-ia que foi fabricada em Hamburgo numa determinada data, expedida através de um centro de distribuição e chegou a um reciclador. O próprio EPCIS 2.0 é compatível com JSON/JSON-LD, pelo que ambos partilham a mesma visão de mundo de Linked Data e os mesmos identificadores GS1 (GTIN + serial) como chave de junção.

Âmbito do qr3 (seja preciso): o qr3 produz o DPP como JSON-LD — é isso que este artigo demonstra. O qr3 não fornece captura de eventos EPCIS nem endpoints EPCIS. Trate aqui o EPCIS 2.0 como o padrão conceptual e complementar que adotaria juntamente com um DPP para uma rastreabilidade completa da cadeia de abastecimento, e não como uma funcionalidade do qr3.

Assim, o modelo mental é: o DPP (qr3, JSON-LD) é a ficha de identidade do produto; o EPCIS 2.0 (sistema separado) é o seu registo de viagem. Os mesmos identificadores, duas perguntas respondidas.

Gerar um DPP que expõe JSON-LD

Não precisa de fazer nada de especial para "ativar" o JSON-LD — crie o passaporte e o resolver serve automaticamente todas as representações:

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

// O passaporte resolve-se agora em https://qr3.app/dpp/04019999999902/SN-00012345
// Humanos obtêm HTML; máquinas acrescentam ?format=jsonld (ou enviam Accept: application/ld+json).
console.log(passport.qr.svg); // O QR codifica o GS1 Digital Link para o resolver

Uma vez criado, o URL do item responde imediatamente a ambos os públicos — sem passo de publicação adicional para a vista de máquina.

FAQ

Porquê JSON-LD e não JSON simples? O JSON simples é estruturado mas não autodescritivo: um consumidor tem de aprender os nomes dos seus campos. O JSON-LD acrescenta @context, mapeando cada chave para termos schema.org / GS1, de modo a que qualquer consumidor de Linked Data o entenda sem uma integração personalizada. Se só precisar de uma leitura rápida, ?format=json continua disponível.

O qr3 implementa o EPCIS 2.0? Não. O qr3 produz o DPP como JSON-LD. O EPCIS 2.0 é o padrão da GS1 separado e complementar para eventos da cadeia de abastecimento; executá-lo-ia em paralelo, unido pelo GTIN + serial partilhados.

Como é que obtenho a vista para máquinas? Acrescente ?format=jsonld ao URL do resolver, ou envie Accept: application/ld+json. Ambos devolvem a mesma carga útil de Linked Data.

O @context é estável? Fixa o schema.org mais o GS1 Web Vocabulary (gs1.org/voc/) — ambos vocabulários públicos e versionados, pelo que os consumidores podem confiar nos significados dos termos.

Fontes

Comece gratuitamente e crie um DPP que expõe JSON-LD: app.qr3.app/sign-up