Suíte de testes do Resolver GS1: verificar a robustez dos DPP-Links antes do go-live

Um código QR que abre uma página no navegador ainda não comprova a robustez de um Resolver. Para um Resolver de links digitais GS1, conta o comportamento HTTP completo: quais identificadores são aceitos? Qual é o destino padrão? O serviço fornece um conjunto de links legível por máquina? Os acessos do navegador funcionam entre domínios diferentes? E as solicitações inválidas ou indisponíveis retornam o erro correto?

Desde 16 de janeiro de 2026, está disponível o GS1-Conformant Resolver Standard 1.2.0. A suíte pública de testes GS1 correspondente é considerada estável; seu código foi atualizado pela última vez em 29 de junho de 2026. Isso permite transformar uma norma abstrata em um teste concreto de aceitação. Este artigo mostra o que deve ser verificado antes do go-live, quais são os limites da suíte de testes e quais evidências devem constar de uma aprovação técnica.

Um escaneamento bem-sucedido é apenas o começo

Um GS1 Digital Link contém um identificador GS1 em uma URI HTTPS. O Resolver associa esse identificador a um ou mais recursos, como uma página de produto, um manual, uma ficha técnica ou uma interface de programação. Nosso artigo introdutório explica o Resolver de links digitais GS1 com um exemplo ao vivo. Para aprovar uma implantação em produção, porém, um redirecionamento padrão bem-sucedido não é suficiente.

O Resolver Standard 1.2.0 exige, entre outros aspectos, HTTPS, suporte a GET, HEAD e OPTIONS, Cross-Origin Resource Sharing (CORS), um link padrão identificável e uma saída de conjunto de links. Para linkType=linkset ou o cabeçalho Accept application/linkset+json, o Resolver não deve redirecionar. Em vez disso, deve retornar os links tipados disponíveis como uma representação independente.

Essa separação é importante: o caminho acessado pelo navegador pode funcionar enquanto o acesso por máquinas, o idioma, os tipos de link ou os casos de erro apresentam falhas. Justamente essas divergências permanecem invisíveis em um simples teste de escaneamento.

O plano de aceitação em sete etapas

1. Definir URIs de teste representativas

Não comece com um único produto de exemplo. Monte uma pequena coleção de testes versionada:

pelo menos um identificador válido para cada chave primária GS1 compatível;
um caso de GTIN sem qualificador;
casos com lote ou número de série, desde que essa granularidade seja compatível;
um identificador sintaticamente inválido;
um identificador válido, mas desconhecido;
um identificador conhecido sem o tipo de link solicitado.

O padrão permite que um Resolver seja compatível apenas com um subconjunto das chaves primárias GS1. Para cada chave primária compatível, porém, seus qualificadores e atributos de dados devem ser processados integralmente. Por isso, o conjunto de testes deve corresponder à capacidade efetivamente declarada, e não a uma afirmação de marketing genérica.

2. Verificar o redirecionamento padrão e os métodos

Teste primeiro a chamada normal sem cabeçalhos especiais. Espera-se um link padrão determinístico. Depois, siga com HEAD e OPTIONS: HEAD não pode usar uma lógica de roteamento diferente de GET, e OPTIONS deve tornar os métodos oferecidos compreensíveis.

Um teste manual mínimo é assim:

curl -sS -D - -o /dev/null \
  "https://id.gs1.org/01/09506000134352"

curl -sS -I \
  "https://id.gs1.org/01/09506000134352"

Documente o código de status, Location, os cabeçalhos de cache e o número de redirecionamentos. Um loop de redirecionamento, um destino aleatório ou um caminho diferente conforme o método é um erro de aprovação, mesmo que um smartphone eventualmente mostre uma página.

3. Solicitar um conjunto de links em vez de uma página web

A verificação mais importante para máquinas é o conjunto de links:

curl -sS \
  -H "Accept: application/linkset+json" \
  "https://id.gs1.org/01/09506000134352"

A RFC 9264 define application/linkset+json como uma representação JSON independente de um conjunto de links web tipados. A GS1 torna o contrato mais rigoroso: a saída deve ser validada pelo esquema normativo de conjunto de links da versão 1.2.0. Portanto, não verifique apenas se é retornado JSON, mas também o tipo de mídia, o esquema, as URIs de destino absolutas, o Anchor e as relações de link.

Particularmente traiçoeiros são os conjuntos de links formalmente válidos, mas tecnicamente incorretos: por exemplo, um manual sob o tipo de link de uma página de informações do produto ou um destino relacionado a uma série no nível de GTIN. Por isso, a validação do esquema e os fixtures técnicos devem ser usados em conjunto.

4. Controlar a descrição do Resolver

Um Resolver em conformidade disponibiliza em /.well-known/gs1resolver uma descrição legível por máquina. Ela informa, entre outros dados, a raiz do Resolver e as chaves primárias compatíveis. O arquivo deve ser validado pelo esquema GS1 para Resolver Description Files.

Esse teste evita uma inconsistência frequente: o serviço pode fazer mais ou menos do que afirma sua própria descrição. Portanto, inclua na aceitação tanto a validação do esquema quanto uma comparação com casos de teste reais.

5. Testar CORS e Content Negotiation

CORS não é um recurso de conveniência. O padrão o exige para que aplicações baseadas em navegador possam acessar o Resolver entre domínios. Teste pelo menos uma origem de navegador permitida e o caminho de preflight. Verifique também se Accept: application/linkset+json e linkType=linkset fornecem resultados consistentes.

Inclua um teste negativo para um tipo de mídia não compatível. Um serviço que sempre envia HTML, independentemente do cabeçalho Accept, é acessível para pessoas, mas não é legível por máquinas de forma confiável.

6. Abranger idioma, contexto e granularidade

O padrão prevê Accept-Language e o parâmetro de consulta context como meios de diferenciar vários links adequados. Nem todo Resolver precisa oferecer todas as variantes. Quando idioma ou contexto são compatíveis, porém, as regras de seleção devem ser reproduzíveis.

Por isso, teste um idioma disponível, um idioma inexistente e uma ordem de fallback definida. Para GTIN, lote e número de série, aplica-se o mesmo princípio: um identificador mais específico pode considerar links relevantes de níveis superiores sem perder a associação técnica. Registre a quantidade esperada de links como fixture; testes de snapshot baseados apenas na ordem são frágeis demais.

7. Diferenciar semanticamente os erros

Os códigos de erro fazem parte do contrato. O padrão do Resolver prevê uma resposta HTTP 400 para identificadores GS1 sintaticamente inválidos. Quando um tipo de link específico e indisponível é solicitado, redirecionar para o destino padrão não é a resposta correta. Esses casos devem ser diferenciados de um identificador desconhecido, mas sintaticamente válido.

Verifique também se as respostas de erro não expõem detalhes internos, tokens ou stack traces e se GET, HEAD e as solicitações baseadas em navegador preservam a mesma semântica. Um documento de erro HTML bem elaborado não corrige um código de status incorreto.

Usar corretamente a suíte de testes GS1

A suíte pública de testes recebe uma URI de Digital Link e verifica o comportamento em relação ao Resolver 1.2.0. Ela é adequada como verificação independente de smoke e conformidade. Para a aprovação, armazene a data do teste, a URI testada, a versão do padrão, o resultado e, quando aplicável, casos de erro reproduzíveis.

No entanto, a suíte não substitui sua própria regressão. A GS1 informa expressamente que ela atualmente não verifica compressão. Se o seu Resolver processa EPC binário ou outras formas compactadas, serão necessários vetores de teste separados. Da mesma forma, a suíte pública não conhece seus tipos de link técnicos nem seus requisitos de autorização, multi-inquilino ou disponibilidade.

Um processo robusto combina, portanto, três níveis:

a suíte pública GS1 como verificação externa de conformidade;
testes de esquema para o conjunto de links e a descrição do Resolver na CI;
seus próprios testes de ponta a ponta para identificadores reais, funções, idiomas e falhas.

O que deve constar da evidência de aprovação

Uma aceitação só pode ser repetida quando o resultado não estiver apenas visível no navegador, mas também documentado. A evidência de aprovação deve conter, no mínimo, a versão do padrão e da suíte, o momento do teste, o ambiente de destino, as URIs de teste, os tipos de link esperados, os resultados HTTP, a validação do esquema, a verificação de CORS e as exceções conhecidas.

Automatize as partes estáveis na CI, mas mantenha uma execução externa direcionada contra a suíte pública antes de cada alteração significativa do Resolver. Assim, “o código QR abre” se transforma em uma afirmação verificável sobre identidade, roteamento e informações de produto legíveis por máquina.