GS1 идентификатори и онбординг

qr3.app залага на BYO-GTIN/BYO-GLN модел (Bring Your Own): Вие носите вашите съществуващи GS1 идентификатори — qr3 поема цифровия Product-Layer над тях.

Какво прави GS1?

GS1 издава глобално уникални идентификатори за продукти и локации:

Идентификатор	Описание	Пример
GTIN-14	Global Trade Item Number (ID на продукт)	`04012345678901`
GLN-13	Global Location Number (локация/фирма)	`4012345000009`
Company Prefix	Фирмен префикс (7-12 цифри), от който се извличат GTIN	`4012345`

За да получите GTIN, се нуждаете от GS1 членство във вашата национална GS1 организация (напр. GS1 Austria, GS1 Germany).

Какво прави qr3.app?

qr3.app използва вашите съществуващи GS1 идентификатори и предлага:

GS1-съвместим Resolver — /01/{GTIN}/21/{Serial} с Content-Negotiation
EU Digital Product Passport — създаване на DPP, валидиране, изглед за потребители
Готови за печат QR активи — SVG, PNG, векторно PDF, EPS
JSON-LD, DCAT-AP — машинно четими данни за продукти

Процес на онбординг

1. Регистриране на GS1 идентификатори

Преди да можете да създавате DPP, трябва да регистрирате вашите GTIN (или вашия Company Prefix):

Чрез 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"}'

Чрез таблото за управление (Dashboard):

Отидете на Dashboard → GS1
Изберете типа (GTIN, GLN oder Company Prefix)
Въведете стойността — валидирането на контролната цифра (Check-Digit) става автоматично
Кликнете върху Добавяне на идентификатор

Вашата организация притежава всеки идентификатор само веднъж, в едно от своите работни пространства (Workspace). Ако регистрирате отново премахнат идентификатор, той се връща (201, същото id) като собствена декларация и непотвърден, дори ако е бил потвърден преди премахването; ако е бил в друго работно пространство, се премества в това. Ако все още е регистриран, отговорът е 409 с reason already_registered (в това работно пространство) или registered_in_other_workspace (в друго; workspace го посочва, ако можете да го отворите). Ако междувременно работното пространство бъде архивирано, reason е workspace_archived; нищо не се регистрира.

2. Създаване на DPP

След като даден GTIN е регистриран (директно или чрез Company Prefix), можете да създавате DPP с него:

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. Проверка на собствеността (Ownership)

qr3.app проверява при всяко създаване на DPP дали използваният GTIN принадлежи на вашата организация:

Директна регистрация — GTIN е регистриран като identifier_type: "gtin"
Съвпадение на префикса (Prefix-Match) — GTIN започва с регистриран Company Prefix (позиция 2..N на GTIN-14)

Без съответстваща регистрация ще получите грешка 422 с указание първо да регистрирате GTIN.

Същата проверка важи за POST /v1/dpp/batch и POST /v1/dpp/import, синхронно и като задача в опашка: един GTIN без регистрация отхвърля цялата заявка с 422 (заглавие GTIN Not Registered, отхвърлените GTIN в gtins, броят им в total); нищо не се създава и не се поставя в опашка. Съществуващите паспорти не се засягат. Подаването на паспорт към Регистъра на продуктите на ЕС (POST /v1/dpp/:id/register) изисква допълнително организацията на паспорта да държи GTIN (вижте раздел 4); иначе отговорът е 409 (заглавие GTIN Held by Another Organization).

4. Потвърждение

Регистрацията чрез API или таблото е самодекларация (verified_by: "self", verified_at: null). Потвърденият идентификатор има verified_at (verified_by: "gs1_registry" или "admin"); задава го qr3, след като провери заявка с доказателство (вижте по-долу). Потвърден GTIN или Company Prefix:

обвързва публичния GS1 резолвер за тези GTIN с вашата организация, дори ако друга организация е създала паспорт по-рано;
блокира всяка друга организация: създаването на DPP за такъв GTIN, включително чрез пакет или импорт, връща 409 (errors/conflict, заглавие GTIN Verified by Another Organization, отхвърлените GTIN в gtins). Пакетът и импортът се отхвърлят изцяло.

Без потвърждение GTIN принадлежи на организацията, която го държи най-дълго без прекъсване (подробности: GS1 Резолвер). Ако вашият GTIN се разрешава към паспорт на друга организация, подайте заявка за потвърждението му.

Заявка за потвърждение

В таблото, в раздел GS1, секция Заявка за потвърждение: въведете типа (GTIN или Company Prefix) и стойността, качете доказателство и подайте заявката. Доказателството показва, че вашата организация притежава GTIN или Company Prefix от GS1, например потвърждението на лиценза от вашата GS1 организация (PDF, PNG, JPEG или WebP). То се съхранява поверително; виждат го само вашата организация и екипът на qr3. Автоматична проверка в GS1 няма.

Екипът на qr3 проверява доказателството и одобрява заявката или я отхвърля с обосновка. След одобрение идентификаторът е потвърден (verified_by: "admin") и действа, както е описано по-горе. За всяко решение получавате имейл на адреса за известия на вашата организация, а ако такъв няма – на адреса на собственика.

Кой: само администраторите на организацията (org_admin или собственикът). Другите роли и директните API ключове получават 403. Поддръжката на qr3 също не може да подаде заявка от ваше име.
Статус: pending (в проверка), approved, rejected, withdrawn (оттеглена от вас) или revoked (потвърждението е отменено по-късно). Заявка в проверка можете да оттеглите.
409: reason е request_pending (за този идентификатор вече има заявка на вашата организация), already_verified или verified_elsewhere (друга организация го е потвърдила; тя не се посочва). Ако вашата организация притежава GS1 лиценза за него, пишете на [email protected]: qr3 проверява и двете страни и може да отмени потвърждение. Ако доказателството се промени, докато заявката се подава, reason е proof_changed; подайте заявката отново.
Друго работно пространство: при request_pending workspace (id, name) и request_id посочват отворената заявка, ако можете да отворите нейното работно пространство; оттеглете я там. Иначе и двете са null. Ако работното пространство бъде архивирано, докато подавате заявката, reason е workspace_archived; нищо не се подава.
Архивиране: когато работно пространство се архивира, заявките му в проверка се оттеглят (withdrawn, в одитния журнал с причина workspace archived). Доказателството отново е свободно и можете да заявите идентификатора отново от друго работно пространство.
Доказателство: докато заявката е в проверка или одобрена, файлът не може да бъде заменен или изтрит (409, reason: "gs1_verification_proof"). След отхвърляне, оттегляне или отмяна той отново е свободен.
Премахване: потвърден идентификатор не може да бъде премахнат (409, reason: "verified"). Потвърждението се отменя само от qr3.

Кога имам нужда и от двете?

Задача	GS1	qr3.app
Получаване на собствени GTIN/GLN	✅ Необходимо е членство	—
Валидиране на GTIN контролна цифра	—	✅ API + Dashboard
Генериране на QR код за продукт	—	✅
Създаване на DPP съгласно регламента на ЕС	—	✅
Разрешаване (resolving) на GS1 Digital Link	—	✅ Resolver + `/.well-known/gs1resolver`
Регистриране в регистъра на ЕС	Планирано (Q4 2026)	Планирано (Фаза 4c)

API Справка

POST /v1/gs1/identifiers — Регистриране
GET /v1/gs1/identifiers — Списък
DELETE /v1/gs1/identifiers/:id — Изтриване
POST /v1/gs1/validate — Валидиране (без регистрация, без оторизация)
POST /v1/gs1/verifications — Заявка за потвърждение (администратори на организацията)
GET /v1/gs1/verifications — Списък на заявките
GET /v1/gs1/verifications/:id — Извличане на заявка
POST /v1/gs1/verifications/:id/withdraw — Оттегляне на заявка

Вижте API документацията за подробности.