Suite di test GS1 Resolver: DPP-Verificare in modo affidabile i link prima del go-live

Un codice QR che apre una pagina nel browser non dimostra ancora l'affidabilità di un resolver. Per un resolver GS1-Digital-Link conta l'intero comportamento HTTP: quali identificatori vengono accettati? Qual è la destinazione predefinita? Il servizio restituisce un linkset leggibile dalle macchine? Gli accessi del browser da altri domini funzionano? E le richieste non valide o non disponibili restituiscono l'errore corretto?

Dal 16 gennaio 2026 è disponibile lo GS1-Conformant Resolver Standard 1.2.0. La relativa suite di test GS1 pubblica è ormai considerata stabile; il suo codice è stato aggiornato l'ultima volta il 29 giugno 2026. È quindi possibile trasformare una norma astratta in un test di accettazione concreto. Questo articolo illustra cosa verificare prima del go-live, quali sono i limiti della suite di test e quali evidenze devono rientrare in un'approvazione tecnica.

Una scansione riuscita è solo l'inizio

Un GS1 Digital Link contiene un identificatore GS1 in un URI HTTPS. Il resolver collega questo identificatore a una o più risorse, ad esempio una pagina prodotto, un manuale, una scheda tecnica o un'interfaccia di programmazione. Il nostro articolo introduttivo spiega il resolver GS1-Digital-Link con un esempio live. Per un'approvazione in produzione, tuttavia, un redirect standard riuscito non è sufficiente.

Lo standard Resolver 1.2.0 richiede tra l'altro HTTPS, il supporto per GET, HEAD e OPTIONS, il Cross-Origin Resource Sharing (CORS), un link predefinito riconoscibile e un'uscita linkset. Con linkType=linkset o con l'header Accept application/linkset+json, il resolver non deve eseguire un redirect. Deve invece restituire i link tipizzati disponibili come rappresentazione autonoma.

Questa distinzione è importante: il percorso del browser umano può funzionare mentre l'accesso macchina, la lingua, i tipi di link o i casi di errore presentano problemi. Proprio queste discrepanze restano invisibili con un semplice test di scansione.

Il piano di accettazione in sette passaggi

1. Definire URI di test rappresentativi

Non iniziate con un unico prodotto di esempio. Preparate una piccola raccolta di test versionata:

almeno un identificatore valido per ogni chiave primaria GS1 supportata;
un caso GTIN senza qualificatore;
casi con lotto o numero di serie, se questo livello di granularità è supportato;
un identificatore sintatticamente non valido;
un identificatore valido, ma sconosciuto;
un identificatore conosciuto senza il tipo di link richiesto.

Lo standard consente a un resolver di supportare solo un sottoinsieme delle chiavi primarie GS1. Per ogni chiave primaria supportata, tuttavia, i relativi qualificatori e attributi dei dati devono essere elaborati completamente. Per questo la raccolta di test deve corrispondere alle capacità effettivamente dichiarate, non a una generica promessa di marketing.

2. Verificare redirect standard e metodi

Testate prima la chiamata normale senza header speciali. Ci si aspetta un link predefinito deterministico. Poi eseguite HEAD e OPTIONS: HEAD non deve usare una logica di routing diversa da GET e OPTIONS deve rendere comprensibili i metodi offerti.

Un test manuale minimo è il seguente:

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

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

Documentate il codice di stato, Location, gli header di cache e il numero di redirect. Un ciclo di redirect, una destinazione casuale o un percorso diverso a seconda del metodo costituiscono un errore di approvazione, anche se uno smartphone alla fine visualizza una pagina.

3. Richiedere il linkset invece della pagina web

Il controllo macchina più importante è il linkset:

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

RFC 9264 definisce application/linkset+json come una rappresentazione JSON autonoma di un insieme di web link tipizzati. GS1 rende il contratto più rigoroso: l'output deve essere validato rispetto allo schema normativo del linkset per la versione 1.2.0. Non verificate quindi solo che venga restituito JSON, ma anche il tipo di media, lo schema, gli URI di destinazione assoluti, Anchor e le relazioni dei link.

Particolarmente insidiosi sono i linkset formalmente validi, ma errati dal punto di vista funzionale: per esempio un manuale con il tipo di link di una pagina di informazioni sul prodotto o una destinazione relativa alla serie al livello GTIN. Per questo la validazione dello schema e i fixture funzionali devono essere considerati insieme.

4. Controllare la descrizione del resolver

Un resolver conforme mette a disposizione una descrizione leggibile dalle macchine all'indirizzo /.well-known/gs1resolver. Essa indica, tra le altre cose, la radice del resolver e le chiavi primarie supportate. Il file deve essere validato rispetto allo schema GS1 per i Resolver Description Files.

Questo test previene una frequente incoerenza: il servizio può supportare più o meno di quanto dichiari la propria descrizione. Includete quindi nell'accettazione sia la validazione dello schema sia un confronto con casi di test reali.

5. Testare CORS e la content negotiation

CORS non è una caratteristica di comodità. Lo standard lo richiede affinché le applicazioni basate sul browser possano interrogare il resolver tra domini diversi. Testate almeno un'origine browser consentita e il percorso di preflight. Verificate inoltre che Accept: application/linkset+json e linkType=linkset producano risultati coerenti.

Aggiungete un test negativo per un tipo di media non supportato. Un servizio che invia sempre HTML indipendentemente dall'header Accept è raggiungibile dagli utenti, ma non è affidabile per l'elaborazione automatica.

6. Coprire lingua, contesto e granularità

Lo standard prevede Accept-Language e il parametro di query context come strumenti per distinguere tra più link pertinenti. Non tutti i resolver devono offrire ogni variante. Se lingua o contesto sono supportati, tuttavia, le regole di selezione devono essere riproducibili.

Testate quindi una lingua disponibile, una lingua non disponibile e una sequenza di fallback definita. Per GTIN, lotto e numero di serie vale lo stesso principio: un identificatore più granulare può prendere in considerazione link pertinenti di livelli superiori senza confondere l'associazione funzionale. Fissate il numero di link previsto come fixture; i soli test snapshot sull'ordine sono troppo fragili.

7. Distinguere semanticamente gli errori

I codici di errore fanno parte del contratto. Lo standard Resolver prevede, per gli identificatori GS1 sintatticamente non validi, un messaggio con HTTP 400. Se viene richiesto un tipo di link concreto non disponibile, un redirect verso la destinazione predefinita non è la risposta corretta. Questi casi devono essere distinti da un identificatore sconosciuto ma sintatticamente valido.

Verificate inoltre che le risposte di errore non rivelino dettagli interni, token o stack trace e che GET, HEAD e le richieste basate sul browser mantengano la stessa semantica. Un elegante documento HTML di errore non può compensare un codice di stato errato.

Utilizzare correttamente la suite di test GS1

La suite di test pubblica accetta un URI Digital-Link e verifica il comportamento rispetto a Resolver 1.2.0. È adatta come controllo indipendente di smoke test e conformità. Per l'approvazione, salvate la data del test, l'URI verificato, la versione dello standard, il risultato ed eventualmente i casi di errore riproducibili.

La suite non sostituisce tuttavia una regressione propria. GS1 indica esplicitamente che attualmente non verifica la compressione. Se il vostro resolver elabora stringhe binarie EPC o altre forme compresse, vi servono vettori di test separati. Inoltre, la suite pubblica non conosce i vostri tipi di link funzionali né i vostri requisiti di autorizzazione, multi-tenancy o disponibilità.

Un processo affidabile combina quindi tre livelli:

la suite GS1 pubblica come controllo di conformità esterno;
test dello schema per linkset e descrizione del resolver in CI;
test end-to-end propri per identificatori reali, ruoli, lingue e indisponibilità.

Cosa deve contenere la documentazione di approvazione

Un'accettazione è ripetibile solo quando il risultato non è semplicemente visibile nel browser, ma anche documentato. La documentazione di approvazione dovrebbe contenere almeno la versione dello standard e della suite, il momento del test, l'ambiente di destinazione, gli URI di test, i tipi di link previsti, i risultati HTTP, la validazione dello schema, il controllo CORS e le eccezioni note.

Automatizzate in CI le parti stabili, ma mantenete un'esecuzione esterna mirata contro la suite pubblica prima di ogni modifica sostanziale al resolver. In questo modo «il codice QR si apre» diventa un'affermazione verificabile su identità, routing e informazioni di prodotto leggibili dalle macchine.