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

A sua organização tem cada identificador apenas uma vez, em um de seus workspaces. Se você registrar novamente um identificador removido, ele volta (201, o mesmo id) como autodeclaração e não verificado, mesmo que estivesse verificado antes da remoção; se estava em outro workspace, ele é movido para este. Se ainda estiver registrado, a resposta é 409 com reason already_registered (neste workspace) ou registered_in_other_workspace (em outro; workspace o nomeia se você puder abri-lo). Se o workspace for arquivado nesse meio-tempo, reason é workspace_archived; nada é registrado.

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.

A mesma verificação vale para POST /v1/dpp/batch e POST /v1/dpp/import, de forma síncrona e como job na fila: uma GTIN sem registro faz com que toda a requisição seja recusada com 422 (título GTIN Not Registered, as GTINs recusadas em gtins, o número delas em total); nada é criado nem colocado na fila. Os passaportes existentes não são afetados. Enviar um passaporte ao registro de produtos da UE (POST /v1/dpp/:id/register) exige, além disso, que a organização do passaporte detenha a GTIN (veja a seção 4); caso contrário, a resposta é 409 (título GTIN Held by Another Organization).

4. Verificação

Um registro pela API ou pelo dashboard é uma autodeclaração (verified_by: "self", verified_at: null). Um identificador verificado traz verified_at (verified_by: "gs1_registry" ou "admin"); quem define isso é a qr3, depois de analisar uma solicitação com comprovante (veja abaixo). Uma GTIN ou um Prefixo de Empresa verificado:

vincula o resolver GS1 público para essas GTINs à sua organização, mesmo que outra organização tenha criado um passaporte antes;
bloqueia qualquer outra organização: criar um DPP para uma GTIN assim, também por lote ou importação, retorna 409 (errors/conflict, título GTIN Verified by Another Organization, as GTINs recusadas em gtins). Lote e importação são recusados por inteiro.

Sem verificação, uma GTIN pertence à organização que a detém há mais tempo sem interrupção (detalhes: Resolver GS1). Se a sua GTIN for resolvida para o passaporte de outra organização, solicite a verificação dela.

Solicitar a verificação

No dashboard, em GS1, seção Pedir verificação: informe o tipo (GTIN ou Prefixo de Empresa) e o valor, envie um comprovante e faça a solicitação. O comprovante mostra que a sua organização tem a GTIN ou o Prefixo de Empresa da GS1, por exemplo a confirmação de licença da sua organização GS1 (PDF, PNG, JPEG ou WebP). Ele é armazenado de forma privada; só a sua organização e a equipe da qr3 podem vê-lo. Não há consulta automática à GS1.

A equipe da qr3 analisa o comprovante e aprova a solicitação ou a recusa com um motivo. Depois da aprovação, o identificador fica verificado (verified_by: "admin") e tem o efeito descrito acima. Você recebe um e-mail sobre cada decisão no endereço de notificações da sua organização ou, na falta dele, no endereço do proprietário.

Quem: somente os administradores da organização (org_admin ou o proprietário). Outras funções e chaves de API diretas recebem 403. O suporte da qr3 também não pode fazer uma solicitação em seu nome.
Status: pending (em análise), approved, rejected, withdrawn (retirada por você) ou revoked (verificação revogada depois). Você pode retirar uma solicitação em análise.
409: reason é request_pending (a sua organização já tem uma solicitação para este identificador), already_verified ou verified_elsewhere (outra organização o verificou; ela não é nomeada). Se a sua organização tiver a licença GS1 correspondente, escreva para [email protected]: a qr3 analisa os dois lados e pode revogar uma verificação. Se o comprovante mudar enquanto a solicitação é enviada, reason é proof_changed; envie a solicitação novamente.
Outro workspace: com request_pending, workspace (id, name) e request_id indicam a solicitação aberta se você puder abrir o workspace dela; retire-a lá. Caso contrário, ambos são null. Se o workspace for arquivado enquanto você envia a solicitação, reason é workspace_archived; nada é enviado.
Arquivamento: quando um workspace é arquivado, as solicitações dele em análise são retiradas (withdrawn, no log de auditoria com o motivo workspace archived). O comprovante fica livre novamente, e você pode solicitar o identificador outra vez a partir de outro workspace.
Comprovante: enquanto a solicitação estiver em análise ou aprovada, o arquivo não pode ser substituído nem excluído (409, reason: "gs1_verification_proof"). Depois de uma recusa, retirada ou revogação, ele fica livre de novo.
Remoção: um identificador verificado não pode ser removido (409, reason: "verified"). Só a qr3 desfaz a verificação, revogando-a.

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)
POST /v1/gs1/verifications — Solicitar verificação (administradores da organização)
GET /v1/gs1/verifications — Listar solicitações
GET /v1/gs1/verifications/:id — Obter uma solicitação
POST /v1/gs1/verifications/:id/withdraw — Retirar uma solicitação

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