Salta ai contenuti
qr3.app Docs

GS1-Resolver

GS1-Resolver

Il GS1-Resolver è il livello di lettura pubblico per un DPP. L’URL canonico si presenta così:

https://qr3.app/01/{GTIN}
https://qr3.app/01/{GTIN}/10/{LOT}
https://qr3.app/01/{GTIN}/21/{SERIAL}
https://qr3.app/01/{GTIN}/10/{LOT}/21/{SERIAL}

Alla creazione di un DPP (POST /v1/dpp) si applicano le seguenti regole: serial e lot devono utilizzare segmenti di percorso GS1 sicuri: solo A-Z, a-z, 0-9, ., _, ~, - e una lunghezza da 1 a 20 caratteri. I separatori URL riservati vengono rifiutati per garantire che il link canonico rimanga risolvibile.

Content Negotiation

Lo stesso resolver fornisce diverse rappresentazioni a seconda dell’header Accept:

AcceptRisposta
text/htmlHTML per il consumatore
application/ld+jsonJSON-LD
application/jsonJSON del DPP grezzo
application/linkset+jsonLinkset con alternative

Rotte visibili pubblicamente

  • GET /01/... è il resolver canonico
  • GET /dpp/:gtin/:serial?lot=... è un alias HTML
  • GET /v1/dpp/:id/qr.svg fornisce l’SVG
  • GET /v1/dpp/:id/qr.png fornisce il PNG
  • GET /v1/dpp/:id/qr.pdf fornisce il PDF
  • GET /v1/dpp/:id/qr.eps fornisce l’EPS

La visibilità degli asset QR dipende dallo stato del DPP:

  • live è accessibile pubblicamente senza autenticazione
  • draft e archived richiedono un contesto di autenticazione valido e l’accesso al workspace
  • Un’autenticazione non valida restituisce 401
  • I workspace non visibili o di terzi restituiscono 404

Fallback

Senza una corrispondenza locale, il resolver GS1 reindirizza con 307 a https://id.gs1.org. Per l’alias GTIN /dpp/:gtin/:serial?lot=..., questo vale anche con una cifra di controllo GTIN non valida: gtin, lot e serial vengono codificati separatamente come segmenti di percorso URL, inclusi i separatori riservati. Il reindirizzamento non conferma la validità del GTIN né la disponibilità di dati presso GS1.

Eccezione: se un identificatore decodificato è soltanto . o .., l’alias senza corrispondenza locale risponde con 422, application/problem+json, il tipo https://docs.qr3.app/errors/validation e il campo interessato in errors[], senza reindirizzamento. I parser URL normalizzano questi segmenti anche in forma codificata. Valori come LOT.1 e ... possono ancora essere inoltrati. L’eccezione riguarda solo questo alias senza corrispondenza; la validazione alla creazione, il resolver canonico e le corrispondenze esistenti restano invariati.

GET /dpp/{GTIN}/UNKNOWN?lot=LOT%2F1
307 Location: https://id.gs1.org/01/{GTIN}/10/LOT%2F1/21/UNKNOWN


GET /dpp/{GTIN}/UNKNOWN?lot=.
422 Content-Type: application/problem+json

Pratica

  1. Creare il DPP nella dashboard.
  2. Utilizzare l’URI GS1 come destinazione del QR.
  3. Indirizzare i sistemi client al formato desiderato tramite l’header Accept.