Saltearse al contenido
qr3.app Docs

Resolver GS1

Resolver GS1

El Resolver GS1 es la capa de lectura pública para un DPP. La URL canónica se ve así:

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}

Al crear un DPP (POST /v1/dpp), se aplican las siguientes reglas: serial y lot deben utilizar segmentos de ruta seguros de GS1: solo A-Z, a-z, 0-9, ., _, ~, - y una longitud de 1 a 20 caracteres. Se rechazan los delimitadores de URL reservados para garantizar que el enlace canónico siga siendo resoluble.

Negociación de contenido

El mismo resolver ofrece diferentes representaciones según la cabecera Accept:

AcceptRespuesta
text/htmlHTML para el consumidor
application/ld+jsonJSON-LD
application/jsonJSON de DPP sin procesar
application/linkset+jsonLinkset con alternativas

Rutas visibles públicamente

  • GET /01/... es el resolver canónico
  • GET /dpp/:gtin/:serial?lot=... es un alias HTML
  • GET /v1/dpp/:id/qr.svg entrega el SVG
  • GET /v1/dpp/:id/qr.png entrega el PNG
  • GET /v1/dpp/:id/qr.pdf entrega el PDF
  • GET /v1/dpp/:id/qr.eps entrega el EPS

La visibilidad de los recursos QR depende del estado del DPP:

  • live está disponible públicamente sin autenticación
  • draft y archived requieren un contexto de autenticación válido y acceso al espacio de trabajo (workspace)
  • Una autenticación no válida devuelve 401
  • Los espacios de trabajo no visibles o ajenos devuelven 404

Fallback

Sin una coincidencia local, el resolver GS1 redirige con 307 a https://id.gs1.org. Para el alias GTIN /dpp/:gtin/:serial?lot=..., esto también se aplica a un dígito de control GTIN no válido: gtin, lot y serial se codifican por separado como segmentos de ruta URL, incluidos los separadores reservados. La redirección no confirma la validez del GTIN ni la disponibilidad de datos en GS1.

Excepción: si un identificador decodificado es solo . o .., el alias sin coincidencia local responde con 422, application/problem+json, el tipo https://docs.qr3.app/errors/validation y el campo afectado en errors[], sin redirección. Los analizadores de URL normalizan estos segmentos incluso cuando están codificados. Los valores como LOT.1 y ... siguen pudiendo delegarse. La excepción solo afecta a este alias sin coincidencia; la validación al crear, el resolver canónico y las coincidencias existentes no cambian.

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

En la práctica

  1. Crear el DPP en el panel de control (dashboard).
  2. Utilizar la URI de GS1 como destino del QR.
  3. Dirigir los sistemas consumidores al formato deseado mediante Accept.