Przejdź do głównej zawartości
qr3.app Docs

Identyfikatory GS1 & Onboarding

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:

IdentyfikatorOpisPrzykład
GTIN-14Global Trade Item Number (identyfikator produktu)04012345678901
GLN-13Global Location Number (lokalizacja/firma)4012345000009
Company PrefixPrefiks firmy (7-12 cyfr), z którego generowane są GTIN4012345

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:

Okno terminala
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):

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

Twoja organizacja ma każdy identyfikator tylko raz, w jednym ze swoich Workspace. Jeśli ponownie zarejestrujesz usunięty identyfikator, wraca on (201, to samo id) jako deklaracja własna i bez weryfikacji, nawet jeśli przed usunięciem był zweryfikowany; jeśli był w innym Workspace, zostaje przeniesiony do tego. Jeśli nadal jest zarejestrowany, odpowiedź to 409 z reason already_registered (w tym Workspace) lub registered_in_other_workspace (w innym; workspace go wskazuje, jeśli możesz go otworzyć). Jeśli w międzyczasie Workspace zostanie zarchiwizowany, reason to workspace_archived; nic nie zostaje zarejestrowane.

2. Tworzenie DPP

Gdy tylko GTIN zostanie zarejestrowany (bezpośrednio lub poprzez Company Prefix), możesz tworzyć dla niego DPP:

Okno terminala
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:

  1. Bezpośrednia rejestracja — GTIN jest zarejestrowany jako identifier_type: "gtin"
  2. 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.

Ta sama kontrola obowiązuje dla POST /v1/dpp/batch i POST /v1/dpp/import, synchronicznie i jako zadanie w kolejce: jeden GTIN bez rejestracji odrzuca całe żądanie z 422 (tytuł GTIN Not Registered, odrzucone GTIN w gtins, ich liczba w total); nic nie jest tworzone ani kolejkowane. Istniejące paszporty pozostają bez zmian. Zgłoszenie paszportu do Rejestru produktów UE (POST /v1/dpp/:id/register) wymaga dodatkowo, aby organizacja paszportu posiadała GTIN (zob. sekcję 4); w przeciwnym razie odpowiedź to 409 (tytuł GTIN Held by Another Organization).

4. Weryfikacja

Rejestracja przez API lub dashboard jest deklaracją własną (verified_by: "self", verified_at: null). Zweryfikowany identyfikator ma verified_at (verified_by: "gs1_registry" lub "admin"); ustawia go qr3 po sprawdzeniu wniosku z dowodem (zob. niżej). Zweryfikowany GTIN lub Company Prefix:

  • wiąże publiczny resolver GS1 dla tych GTIN z Twoją organizacją, nawet jeśli inna organizacja wcześniej utworzyła paszport;
  • blokuje każdą inną organizację: utworzenie DPP dla takiego GTIN, także partią lub importem, zwraca 409 (errors/conflict, tytuł GTIN Verified by Another Organization, odrzucone GTIN w gtins). Partia i import są odrzucane w całości.

Bez weryfikacji GTIN należy do organizacji, która ma go najdłużej bez przerwy (szczegóły: Resolver GS1). Jeśli Twój GTIN rozwiązuje się do paszportu innej organizacji, złóż wniosek o jego weryfikację.

Wniosek o weryfikację

W dashboardzie w sekcji GS1, w części Poproś o weryfikację: wpisz typ (GTIN lub Company Prefix) i wartość, prześlij dowód i wyślij wniosek. Dowód pokazuje, że Twoja organizacja ma GTIN lub Company Prefix od GS1, na przykład potwierdzenie licencji od Twojej organizacji GS1 (PDF, PNG, JPEG lub WebP). Jest przechowywany prywatnie; widzą go tylko Twoja organizacja i zespół qr3. Automatycznego zapytania do GS1 nie ma.

Zespół qr3 sprawdza dowód i zatwierdza wniosek albo odrzuca go z uzasadnieniem. Po zatwierdzeniu identyfikator jest zweryfikowany (verified_by: "admin") i działa tak, jak opisano wyżej. O każdej decyzji dostajesz e-mail na adres powiadomień Twojej organizacji, a w jego braku na adres właściciela.

  • Kto: tylko administratorzy organizacji (org_admin lub właściciel). Inne role i bezpośrednie klucze API otrzymują 403. Również pomoc techniczna qr3 nie może złożyć wniosku w Twoim imieniu.
  • Status: pending (w weryfikacji), approved, rejected, withdrawn (wycofany przez Ciebie) lub revoked (weryfikacja później unieważniona). Wniosek w weryfikacji możesz wycofać.
  • 409: reason to request_pending (Twoja organizacja ma już wniosek dla tego identyfikatora), already_verified lub verified_elsewhere (zweryfikowała go inna organizacja; nie jest wymieniana). Jeśli Twoja organizacja ma do niego licencję GS1, napisz na [email protected]: qr3 sprawdza obie strony i może unieważnić weryfikację. Jeśli dowód zmieni się podczas wysyłania wniosku, reason to proof_changed; wyślij wniosek ponownie.
  • Inny Workspace: przy request_pending pola workspace (id, name) i request_id wskazują otwarty wniosek, jeśli możesz otworzyć jego Workspace; wycofaj go tam. W przeciwnym razie oba mają wartość null. Jeśli Workspace zostanie zarchiwizowany podczas składania wniosku, reason to workspace_archived; nic nie zostaje złożone.
  • Archiwizacja: gdy Workspace zostaje zarchiwizowany, jego wnioski w weryfikacji są wycofywane (withdrawn, w dzienniku audytu z powodem workspace archived). Dowód jest wtedy znów wolny i możesz ponownie złożyć wniosek o identyfikator z innego Workspace.
  • Dowód: dopóki wniosek jest w weryfikacji lub zatwierdzony, pliku nie można zastąpić ani usunąć (409, reason: "gs1_verification_proof"). Po odrzuceniu, wycofaniu lub unieważnieniu jest znów wolny.
  • Usuwanie: zweryfikowanego identyfikatora nie można usunąć (409, reason: "verified"). Weryfikację znosi tylko qr3, unieważniając ją.

Kiedy potrzebuję obu rozwiązań?

ZadanieGS1qr3.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 UEPlanowane (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)
  • POST /v1/gs1/verifications — Wniosek o weryfikację (administratorzy organizacji)
  • GET /v1/gs1/verifications — Lista wniosków
  • GET /v1/gs1/verifications/:id — Pobranie wniosku
  • POST /v1/gs1/verifications/:id/withdraw — Wycofanie wniosku

Szczegółowe informacje znajdziesz w dokumentacji API.