Identificadores GS1 y Onboarding

qr3.app se basa en un modelo BYO-GTIN/BYO-GLN (Bring Your Own): tú aportas tus identificadores GS1 existentes y qr3 se encarga de la capa digital de producto (Product-Layer) sobre ellos.

¿Qué hace GS1?

GS1 asigna identificadores únicos a nivel mundial para productos y ubicaciones:

Identificador	Descripción	Ejemplo
GTIN-14	Global Trade Item Number (ID de producto)	`04012345678901`
GLN-13	Global Location Number (Ubicación/empresa)	`4012345000009`
Company Prefix	Prefijo de empresa (7-12 dígitos), del cual se derivan los GTIN	`4012345`

Para obtener GTIN, necesitas una afiliación a GS1 en tu organización nacional de GS1 (por ejemplo, GS1 Austria, GS1 Alemania).

¿Qué hace qr3.app?

qr3.app utiliza tus identificadores GS1 existentes y ofrece:

Resolver compatible con GS1 — /01/{GTIN}/21/{Serial} con negociación de contenido (Content-Negotiation)
Pasaporte Digital de Producto de la UE (DPP) — Creación de DPP, validación, vista del consumidor
Recursos QR listos para imprimir — SVG, PNG, PDF vectorial, EPS
JSON-LD, DCAT-AP — Datos de producto legibles por máquina

Flujo de onboarding

1. Registrar identificadores GS1

Antes de poder crear DPP, debes registrar tus GTIN (o tu Company Prefix):

Por 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"}'

Por panel de control (Dashboard):

Navega a Dashboard → GS1
Selecciona el tipo (GTIN, GLN o Company Prefix)
Introduce el valor; la validación del dígito de control (Check-Digit) se realiza automáticamente
Haz clic en Añadir identificador

Tu organización tiene cada identificador una sola vez, en uno de sus Workspaces. Si vuelves a registrar un identificador eliminado, vuelve (201, el mismo id) como autodeclaración y sin verificar, aunque estuviera verificado antes de eliminarlo; si estaba en otro Workspace, se traslada a este. Si sigue registrado, la respuesta es 409 con reason already_registered (en este Workspace) o registered_in_other_workspace (en otro; workspace lo nombra si puedes abrirlo). Si el Workspace se archiva mientras tanto, reason es workspace_archived; no se registra nada.

2. Crear DPP

Una vez que se ha registrado un GTIN (directamente o a través de un Company Prefix), puedes crear DPP con él:

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. Verificación de propiedad

qr3.app comprueba en cada creación de DPP si el GTIN utilizado pertenece a tu organización:

Registro directo — El GTIN está registrado como identifier_type: "gtin"
Coincidencia de prefijo (Prefix-Match) — El GTIN comienza con un Company Prefix registrado (posiciones 2..N del GTIN-14)

Sin un registro coincidente, se producirá un error 422 indicando que primero se debe registrar el GTIN.

La misma comprobación se aplica a POST /v1/dpp/batch y POST /v1/dpp/import, de forma síncrona y como trabajo en cola: un GTIN sin registro hace que se rechace toda la solicitud con 422 (título GTIN Not Registered, los GTIN rechazados en gtins, su número en total); no se crea ni se encola nada. Los pasaportes existentes no se ven afectados. Enviar un pasaporte al Registro de productos de la UE (POST /v1/dpp/:id/register) exige además que la organización del pasaporte sea titular del GTIN (ver la sección 4); si no, la respuesta es 409 (título GTIN Held by Another Organization).

4. Verificación

Un registro mediante la API o el dashboard es una autodeclaración (verified_by: "self", verified_at: null). Un identificador verificado lleva verified_at (verified_by: "gs1_registry" o "admin"); lo establece qr3 después de revisar una solicitud con prueba (ver más abajo). Un GTIN o Company Prefix verificado:

vincula el resolver GS1 público para esos GTIN a tu organización, aunque otra organización haya creado antes un pasaporte;
bloquea a cualquier otra organización: crear un DPP para un GTIN así, también por lote o importación, devuelve 409 (errors/conflict, título GTIN Verified by Another Organization, los GTIN rechazados en gtins). El lote y la importación se rechazan en su totalidad.

Sin verificación, un GTIN pertenece a la organización que lo tiene desde hace más tiempo sin interrupción (detalles: Resolver GS1). Si tu GTIN se resuelve al pasaporte de otra organización, solicita su verificación.

Solicitar la verificación

En el dashboard, en GS1, sección Solicitar verificación: introduce el tipo (GTIN o Company Prefix) y el valor, sube una prueba y envía la solicitud. La prueba demuestra que tu organización tiene el GTIN o el Company Prefix de GS1, por ejemplo la confirmación de licencia de tu organización GS1 (PDF, PNG, JPEG o WebP). Se guarda de forma privada; solo tu organización y el equipo de qr3 pueden verla. No hay consulta automática a GS1.

El equipo de qr3 revisa la prueba y aprueba la solicitud o la rechaza con un motivo. Tras la aprobación, el identificador queda verificado (verified_by: "admin") y tiene el efecto descrito arriba. Recibes un correo electrónico sobre cada decisión en la dirección de notificaciones de tu organización o, si no la hay, en la del propietario.

Quién: solo los administradores de la organización (org_admin o el propietario). Los demás roles y las claves API directas reciben 403. Tampoco el soporte de qr3 puede enviar una solicitud en tu nombre.
Estado: pending (en revisión), approved, rejected, withdrawn (retirada por ti) o revoked (verificación revocada después). Puedes retirar una solicitud en revisión.
409: reason es request_pending (tu organización ya tiene una solicitud para este identificador), already_verified o verified_elsewhere (otra organización lo ha verificado; no se nombra). Si tu organización tiene la licencia GS1 correspondiente, escribe a [email protected]: qr3 revisa ambas partes y puede revocar una verificación. Si la prueba cambia mientras se envía la solicitud, reason es proof_changed; envía la solicitud de nuevo.
Otro Workspace: con request_pending, workspace (id, name) y request_id nombran la solicitud abierta si puedes abrir su Workspace; retírala allí. Si no, ambos son null. Si el Workspace se archiva mientras envías la solicitud, reason es workspace_archived; no se envía nada.
Archivar: cuando se archiva un Workspace, sus solicitudes en revisión se retiran (withdrawn, en el registro de auditoría con el motivo workspace archived). La prueba vuelve a quedar libre y puedes solicitar de nuevo el identificador desde otro Workspace.
Prueba: mientras la solicitud esté en revisión o aprobada, el archivo no se puede sustituir ni eliminar (409, reason: "gs1_verification_proof"). Tras un rechazo, una retirada o una revocación vuelve a estar libre.
Eliminar: un identificador verificado no se puede eliminar (409, reason: "verified"). Solo qr3 deja sin efecto la verificación, revocándola.

¿Cuándo necesito ambos?

Tarea	GS1	qr3.app
Obtener tus propios GTIN/GLN	✅ Requiere afiliación	—
Validar el dígito de control del GTIN	—	✅ API + Dashboard
Generar código QR para el producto	—	✅
Crear DPP según el reglamento de la UE	—	✅
Resolver GS1 Digital Link	—	✅ Resolver + `/.well-known/gs1resolver`
Registrar en el registro de la UE	Planificado (Q4 2026)	Planificado (Fase 4c)

Referencia de la API

POST /v1/gs1/identifiers — Registrar
GET /v1/gs1/identifiers — Listar
DELETE /v1/gs1/identifiers/:id — Eliminar
POST /v1/gs1/validate — Validar (sin registro, sin autenticación)
POST /v1/gs1/verifications — Solicitar verificación (administradores de la organización)
GET /v1/gs1/verifications — Listar solicitudes
GET /v1/gs1/verifications/:id — Obtener una solicitud
POST /v1/gs1/verifications/:id/withdraw — Retirar una solicitud

Consulta la documentación de la API para más detalles.