Identyfikatory GS1 & Onboarding

qr3.app opiera się na modelu BYO-GTIN/BYO-GLN (Bring Your Own): przynosisz swoje istniejące identyfikatory GS1 — qr3 zajmuje się cyfrową warstwą produktową (Product-Layer) nad nimi.

Co robi GS1?

GS1 przydziela unikalne na całym świecie identyfikatory dla produktów i lokalizacji:

Identyfikator	Opis	Przykład
GTIN-14	Global Trade Item Number (identyfikator produktu)	`04012345678901`
GLN-13	Global Location Number (lokalizacja/firma)	`4012345000009`
Company Prefix	Prefiks firmy (7-12 cyfr), z którego generowane są GTIN	`4012345`

Aby otrzymać GTIN, potrzebujesz członkostwa w GS1 w swojej krajowej organizacji GS1 (np. GS1 Polska, GS1 Germany).

Co robi qr3.app?

qr3.app wykorzystuje Twoje istniejące identyfikatory GS1 i oferuje:

Resolver zgodny z GS1 — /01/{GTIN}/21/{Serial} z Content-Negotiation
EU Digital Product Passport — tworzenie DPP, walidacja, widok konsumencki
Gotowe do druku zasoby QR — SVG, PNG, wektorowy PDF, EPS
JSON-LD, DCAT-AP — maszynowo czytelne dane produktów

Proces onboardingowy

1. Rejestracja identyfikatorów GS1

Zanim będziesz mógł tworzyć DPP, musisz zarejestrować swoje GTIN (lub swój Company Prefix):

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

Przez panel administracyjny (Dashboard):

Przejdź do Dashboard → GS1
Wybierz typ (GTIN, GLN lub Company Prefix)
Wprowadź wartość — walidacja cyfry kontrolnej (Check-Digit) odbywa się automatycznie
Kliknij Dodaj identyfikator

2. Tworzenie DPP

Gdy tylko GTIN zostanie zarejestrowany (bezpośrednio lub poprzez Company Prefix), możesz tworzyć dla niego 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. Weryfikacja własności (Ownership)

qr3.app sprawdza przy każdym tworzeniu DPP, czy użyty GTIN należy do Twojej organizacji:

Bezpośrednia rejestracja — GTIN jest zarejestrowany jako identifier_type: "gtin"
Dopasowanie prefiksu (Prefix-Match) — GTIN zaczyna się od zarejestrowanego Company Prefix (pozycje 2..N w GTIN-14)

Bez odpowiedniej rejestracji wystąpi błąd 422 z informacją o konieczności uprzedniej rejestracji GTIN.

Kiedy potrzebuję obu rozwiązań?

Zadanie	GS1	qr3.app
Uzyskanie własnych GTIN/GLN	✅ Wymagane członkostwo	—
Walidacja cyfry kontrolnej GTIN	—	✅ API + Dashboard
Generowanie kodu QR dla produktu	—	✅
Tworzenie DPP zgodnie z rozporządzeniem UE	—	✅
Rozwiązywanie GS1 Digital Link	—	✅ Resolver + `/.well-known/gs1resolver`
Rejestracja w rejestrze UE	Planowane (Q4 2026)	Planowane (Faza 4c)

Referencja API

POST /v1/gs1/identifiers — Rejestracja
GET /v1/gs1/identifiers — Listowanie
DELETE /v1/gs1/identifiers/:id — Usuwanie
POST /v1/gs1/validate — Walidacja (bez rejestracji, brak autoryzacji)

Szczegółowe informacje znajdziesz w dokumentacji API.