Αναγνωριστικά GS1 & Onboarding

Το 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 Ελλάς, GS1 Germany).

Τι κάνει το qr3.app;

Το qr3.app χρησιμοποιεί τα υπάρχοντα αναγνωριστικά GS1 σας και προσφέρει:

Resolver συμβατός με GS1 — /01/{GTIN}/21/{Serial} με Content-Negotiation
Ψηφιακό Διαβατήριο Προϊόντος ΕΕ (DPP) — Δημιουργία DPP, επικύρωση, προβολή καταναλωτή
Έτοιμα για εκτύπωση QR assets — SVG, PNG, διανυσματικό PDF, EPS
JSON-LD, DCAT-AP — Μηχανικά αναγνώσιμα δεδομένα προϊόντος

Ροή Onboarding

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 ή Company Prefix)
Εισαγάγετε την τιμή — η επικύρωση του ψηφίου ελέγχου (Check-Digit) γίνεται αυτόματα
Κάντε κλικ στο Προσθήκη αναγνωριστικού

Ο οργανισμός σας έχει κάθε αναγνωριστικό μόνο μία φορά, σε ένα από τα Workspaces του. Αν καταχωρίσετε ξανά ένα αναγνωριστικό που αφαιρέθηκε, επιστρέφει (201, το ίδιο id) ως αυτοδήλωση και χωρίς επαλήθευση, ακόμη κι αν ήταν επαληθευμένο πριν από την αφαίρεση· αν βρισκόταν σε άλλο Workspace, μετακινείται σε αυτό. Αν είναι ακόμη καταχωρισμένο, η απάντηση είναι 409 με reason already_registered (σε αυτό το Workspace) ή registered_in_other_workspace (σε άλλο· το 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 ή του dashboard είναι αυτοδήλωση (verified_by: "self", verified_at: null). Ένα επαληθευμένο αναγνωριστικό φέρει verified_at (verified_by: "gs1_registry" ή "admin")· το ορίζει το qr3 αφού ελέγξει ένα αίτημα με αποδεικτικό (βλ. παρακάτω). Ένα επαληθευμένο GTIN ή Company Prefix:

δεσμεύει τον δημόσιο GS1 resolver για αυτά τα GTIN στον οργανισμό σας, ακόμη κι αν άλλος οργανισμός δημιούργησε νωρίτερα διαβατήριο·
αποκλείει κάθε άλλο οργανισμό: η δημιουργία DPP για τέτοιο GTIN, και μέσω παρτίδας ή εισαγωγής, επιστρέφει 409 (errors/conflict, τίτλος GTIN Verified by Another Organization, τα απορριφθέντα GTIN στο gtins). Η παρτίδα και η εισαγωγή απορρίπτονται στο σύνολό τους.

Χωρίς επαλήθευση, ένα GTIN ανήκει στον οργανισμό που το κατέχει για το μεγαλύτερο διάστημα χωρίς διακοπή (λεπτομέρειες: GS1 Resolver). Αν το GTIN σας επιλύεται στο διαβατήριο άλλου οργανισμού, υποβάλετε αίτημα επαλήθευσής του.

Αίτημα επαλήθευσης

Στο dashboard, στην ενότητα GS1, τμήμα Αίτημα επαλήθευσης: συμπληρώστε τον τύπο (GTIN ή Company Prefix) και την τιμή, ανεβάστε ένα αποδεικτικό και υποβάλετε το αίτημα. Το αποδεικτικό δείχνει ότι ο οργανισμός σας κατέχει το GTIN ή το Company Prefix από την GS1, για παράδειγμα την επιβεβαίωση άδειας από τον οργανισμό GS1 σας (PDF, PNG, JPEG ή WebP). Αποθηκεύεται ιδιωτικά· το βλέπουν μόνο ο οργανισμός σας και η ομάδα του qr3. Αυτόματος έλεγχος στην GS1 δεν υπάρχει.

Η ομάδα του qr3 ελέγχει το αποδεικτικό και εγκρίνει το αίτημα ή το απορρίπτει με αιτιολόγηση. Μετά την έγκριση το αναγνωριστικό είναι επαληθευμένο (verified_by: "admin") και ισχύει όπως περιγράφεται παραπάνω. Για κάθε απόφαση λαμβάνετε email στη διεύθυνση ειδοποιήσεων του οργανισμού σας, αλλιώς στη διεύθυνση του κατόχου.

Ποιος: μόνο οι διαχειριστές του οργανισμού (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· υποβάλετε το αίτημα ξανά.
Άλλο Workspace: με request_pending, τα workspace (id, name) και request_id κατονομάζουν το ανοιχτό αίτημα, αν μπορείτε να ανοίξετε το Workspace του· αποσύρετέ το εκεί. Διαφορετικά και τα δύο είναι null. Αν το Workspace αρχειοθετηθεί ενώ υποβάλλετε το αίτημα, το reason είναι workspace_archived· δεν υποβάλλεται τίποτα.
Αρχειοθέτηση: όταν ένα Workspace αρχειοθετείται, τα αιτήματά του σε έλεγχο αποσύρονται (withdrawn, στο αρχείο ελέγχου με αιτία workspace archived). Το αποδεικτικό είναι έπειτα ξανά ελεύθερο και μπορείτε να ζητήσετε ξανά το αναγνωριστικό από άλλο Workspace.
Αποδεικτικό: όσο το αίτημα είναι σε έλεγχο ή εγκεκριμένο, το αρχείο δεν μπορεί ούτε να αντικατασταθεί ούτε να διαγραφεί (409, reason: "gs1_verification_proof"). Μετά από απόρριψη, απόσυρση ή ανάκληση είναι ξανά ελεύθερο.
Κατάργηση: ένα επαληθευμένο αναγνωριστικό δεν μπορεί να καταργηθεί (409, reason: "verified"). Την επαλήθευση την αίρει μόνο το qr3 με ανάκληση.

Πότε χρειάζομαι και τα δύο;

Εργασία	GS1	qr3.app
Απόκτηση δικών σας GTIN/GLN	✅ Απαιτείται συνδρομή μέλους	—
Επικύρωση ψηφίου ελέγχου GTIN	—	✅ API + Dashboard
Δημιουργία κώδικα QR για προϊόν	—	✅
Δημιουργία DPP σύμφωνα με τον κανονισμό της ΕΕ	—	✅
Ανάλυση (Resolve) GS1 Digital Link	—	✅ Resolver + `/.well-known/gs1resolver`
Καταχώριση στο Μητρώο της ΕΕ (EU Registry)	Σχεδιάζεται (Q4 2026)	Σχεδιάζεται (Φάση 4c)

Αναφορά API

POST /v1/gs1/identifiers — Καταχώριση
GET /v1/gs1/identifiers — Λίστα
DELETE /v1/gs1/identifiers/:id — Κατάργηση
POST /v1/gs1/validate — Επικύρωση (χωρίς καταχώριση, χωρίς Auth)
POST /v1/gs1/verifications — Αίτημα επαλήθευσης (διαχειριστές οργανισμού)
GET /v1/gs1/verifications — Λίστα αιτημάτων
GET /v1/gs1/verifications/:id — Ανάκτηση αιτήματος
POST /v1/gs1/verifications/:id/withdraw — Απόσυρση αιτήματος

Δείτε την Τεκμηρίωση API για λεπτομέρειες.