Pular para o conteúdo
qr3.app Docs

Resolver GS1

Resolver GS1

O Resolver GS1 é a camada de leitura pública para um DPP. O URL canônico tem a seguinte aparência:

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}

Ao criar um DPP (POST /v1/dpp), aplicam-se as seguintes regras: serial e lot devem usar segmentos de caminho seguros do GS1: apenas A-Z, a-z, 0-9, ., _, ~, - e um comprimento de 1 a 20 caracteres. Separadores de URL reservados são rejeitados para garantir que o link canônico permaneça resolvível.

Negociação de Conteúdo

O mesmo resolver fornece diferentes representações dependendo do cabeçalho Accept:

AcceptResposta
text/htmlHTML do consumidor
application/ld+jsonJSON-LD
application/jsonJSON bruto do DPP
application/linkset+jsonLinkset com alternativas

Rotas publicamente visíveis

  • GET /01/... é o resolver canônico
  • GET /dpp/:gtin/:serial?lot=... é um alias HTML
  • GET /v1/dpp/:id/qr.svg fornece o SVG
  • GET /v1/dpp/:id/qr.png fornece o PNG
  • GET /v1/dpp/:id/qr.pdf fornece o PDF
  • GET /v1/dpp/:id/qr.eps fornece o EPS

A visibilidade dos assets de QR depende do status do DPP:

  • live está disponível publicamente sem autenticação
  • draft e archived precisam de um contexto de autenticação válido e acesso ao Workspace
  • Autenticação inválida retorna 401
  • Workspaces invisíveis ou de terceiros retornam 404

Fallback

Sem correspondência local, o resolver GS1 redireciona com 307 para https://id.gs1.org. Para o alias GTIN /dpp/:gtin/:serial?lot=..., isto também se aplica a um dígito de controle GTIN inválido: gtin, lot e serial são codificados separadamente como segmentos do caminho URL, incluindo os separadores reservados. O redirecionamento não confirma a validade do GTIN nem a disponibilidade de dados na GS1.

Exceção: se um identificador decodificado for apenas . ou .., o alias sem correspondência local responde com 422, application/problem+json, o tipo https://docs.qr3.app/errors/validation e o campo afetado em errors[], sem redirecionamento. Os analisadores de URL normalizam estes segmentos mesmo quando codificados. Valores como LOT.1 e ... continuam a poder ser encaminhados. A exceção aplica-se apenas a este alias sem correspondência; a validação na criação, o resolver canônico e as correspondências existentes não mudam.

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

Na Prática

  1. Criar o DPP no painel (Dashboard).
  2. Usar o URI do GS1 como destino do QR.
  3. Direcionar os sistemas consumidores para o formato desejado usando o cabeçalho Accept.