O Resolver GS1 Digital Link, explicado (com um exemplo ao vivo)

A maioria das explicações sobre códigos QR de Passaporte Digital de Produto fica-se pelo "leia o código, abra um site". Isso deixa de fora a parte interessante. O código QR de um produto conforme codifica um GS1 Digital Link, e o componente que o torna útil é o resolver — o serviço que transforma um identificador de produto em muitas respostas diferentes e sensíveis ao contexto.

Este artigo mostra o que o resolver faz de facto, com um passaporte ao vivo que pode chamar agora mesmo (sem registo, sem chave).

O que é, de facto, um GS1 Digital Link

Um GS1 Digital Link é um URL HTTPS normal que incorpora identificadores GS1 como segmentos de caminho, cada um etiquetado com um Application Identifier (AI):

https://id.gs1.org/01/04019999999902/21/DEMO-BAT-01
                   └─01─┘ └──GTIN───┘ └21┘ └─serial─┘

01 → GTIN (Global Trade Item Number) — que produto
21 → número de série — que unidade individual
10 → lote (alternativa ao número de série)

Por ser um URL simples, qualquer câmara de telemóvel o abre. Por ser estruturado, as máquinas conseguem interpretá-lo. Essa dupla natureza é o cerne de tudo.

O resolver: um URI, muitas respostas

Um código QR sem inteligência devolve uma única página fixa. Um resolver inspeciona o pedido e devolve a representação que se adequa a quem chama:

um consumidor com um navegador no telemóvel recebe uma página HTML legível por humanos;
o sistema de um reciclador pede JSON-LD e recebe dados estruturados legíveis por máquina;
uma autoridade pode pedir o linkset completo — cada ligação tipada que o produto expõe.

O mesmo URL, respostas diferentes, decididas pelo cabeçalho Accept (ou por uma substituição ?format=).

Um resolver ao vivo que pode chamar agora mesmo

A qr3.app aloja um passaporte de bateria de demonstração público. Abra-o num navegador:

https://qr3.app/dpp/04019999999902/DEMO-BAT-01

Verá a página de consumidor de EcoMax 5000 (Demo) da GreenPower GmbH. Agora peça ao mesmo URL JSON-LD legível por máquina:

curl "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)"
}

É o resolver a fazer o seu trabalho: um identificador, uma página para humanos e um documento JSON-LD construído sobre schema.org + o vocabulário web da GS1. Outras representações estão disponíveis da mesma forma — ?format=json (passaporte em bruto), ?format=linkset (todas as ligações tipadas), ?format=dcat-ap — ou através da negociação Accept padrão (Accept: application/ld+json).

Valide os identificadores antes de criar links

Um resolver é tão fiável quanto os identificadores que estão por detrás dele. Valide um GTIN antes de construir um Digital Link para ele:

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

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

const result = await client.gs1.validateGs1({
  identifier_type: "gtin",
  value: "04019999999902",
});

console.log(result.valid);   // true
console.log(result.detail);  // "Valid GTIN-14"

Registe os seus GTIN

Mantenha sob gestão os identificadores que utiliza, para que cada Digital Link possa ser rastreado até um produto conhecido:

const gtin = await client.gs1.createGs1Identifier({
  identifier_type: "gtin", // or "gln" | "company_prefix"
  value: "04019999999902",
  label: "EcoMax 5000",
});

Usar a qr3 como o seu resolver

Não tem de construir e operar um resolver por conta própria. Aponte o código QR do seu produto para o Digital Link, aloje o passaporte na qr3.app, e o resolver serve a representação certa por pedido. O GTIN/número de série no URL permanecem estáveis para sempre (para que as etiquetas impressas nunca deixem de funcionar), enquanto os dados por detrás deles continuam atualizáveis.

FAQ

O próprio código QR é diferente de um normal? Não — é um QR padrão (ou Data Matrix) que transporta um URL GS1 Digital Link. Qualquer câmara o abre; a inteligência está no resolver, não no símbolo.

Os consumidores e os recicladores recebem mesmo conteúdo diferente? Sim — isso é negociação de conteúdo. O navegador recebe HTML; um sistema que pede application/ld+json (ou ?format=jsonld) recebe dados estruturados a partir do mesmo URL.

Posso manter a minha própria página de produto e continuar conforme? Sim. O Digital Link pode expor várias ligações tipadas (um linkset) — a sua página de marketing, o passaporte oficial, uma ficha técnica de reciclagem — cada uma etiquetada com um tipo de ligação.

Fontes

Experimente o passaporte ao vivo acima e depois comece gratuitamente e resolva o seu próprio.