Identificadores GS1 & Onboarding

O qr3.app baseia-se num modelo BYO-GTIN/BYO-GLN (Bring Your Own): você traz os seus identificadores GS1 existentes — o qr3 assume a camada digital do produto (Product-Layer) por cima.

O que faz a GS1?

A GS1 emite identificadores globalmente exclusivos para produtos e localizações:

Identificador	Descrição	Exemplo
GTIN-14	Global Trade Item Number (ID do Produto)	`04012345678901`
GLN-13	Global Location Number (Localização/Empresa)	`4012345000009`
Company Prefix	Prefixo de Empresa (7 a 12 dígitos), a partir do qual as GTINs são derivadas	`4012345`

Para obter GTINs, necessita de uma adesão à GS1 junto da sua organização nacional GS1 (por exemplo, GS1 Austria, GS1 Germany).

O que faz o qr3.app?

O qr3.app utiliza os seus identificadores GS1 existentes e oferece:

Resolver compatível com GS1 — /01/{GTIN}/21/{Serial} com Content-Negotiation
EU Digital Product Passport — Criação de DPP, validação, visualização do consumidor
Ativos de QR prontos para impressão — SVG, PNG, PDF vetorial, EPS
JSON-LD, DCAT-AP — Dados de produto legíveis por máquina

Fluxo de Onboarding

1. Registrar Identificadores GS1

Antes de poder criar DPPs, deve registrar as suas GTINs (ou o seu Prefixo de Empresa):

Via API:

curl -X POST https://qr3.app/v1/gs1/identifiers \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"identifier_type": "company_prefix", "value": "4012345", "label": "GreenPower GmbH"}'

Via Dashboard:

Navegue até Dashboard → GS1
Selecione o tipo (GTIN, GLN ou Company Prefix)
Insira o valor — a validação do dígito de controle (Check-Digit) ocorre automaticamente
Clique em Adicionar Identificador

2. Criar DPPs

Assim que uma GTIN estiver registrada (diretamente ou através de um Prefixo de Empresa), poderá criar DPPs com ela:

curl -X POST https://qr3.app/v1/dpp \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"gtin": "04012345678901", "product_name": "EcoMax Battery", ...}'

3. Verificação de Propriedade

O qr3.app verifica, a cada criação de DPP, se a GTIN utilizada pertence à sua organização:

Registro Direto — A GTIN está registrada como identifier_type: "gtin"
Correspondência de Prefixo — A GTIN começa com um Prefixo de Empresa registrado (posições 2..N da GTIN-14)

Sem um registro correspondente, será retornado um erro 422 com a indicação para registrar a GTIN primeiro.

Quando preciso de ambos?

Tarefa	GS1	qr3.app
Obter as suas próprias GTINs/GLNs	✅ Adesão necessária	—
Validar dígito de controle da GTIN	—	✅ API + Dashboard
Gerar código QR para o produto	—	✅
Criar DPP de acordo com o regulamento da UE	—	✅
Resolver GS1 Digital Link	—	✅ Resolver + `/.well-known/gs1resolver`
Registrar no registro da UE	Planejado (Q4 2026)	Planejado (Fase 4c)

Referência da API

POST /v1/gs1/identifiers — Registrar
GET /v1/gs1/identifiers — Listar
DELETE /v1/gs1/identifiers/:id — Remover
POST /v1/gs1/validate — Validar (sem registro, sem autenticação)

Consulte a Documentação da API para mais detalhes.