API Κωδικών QR

Δεσμευτική σύμβαση REST

Η ακόλουθη σύμβαση ισχύει για όλους τους πελάτες:

Το POST /v1/codes δέχεται μόνο τους τύπους url, vcard, wifi, email, sms και location. Τα πεδία είναι επίπεδα: url; τουλάχιστον vcard_first_name ή vcard_last_name; wifi_ssid; email_to; sms_phone; ή και τα δύο location_lat και location_lng.
Μόνο οι κωδικοί url μπορούν να είναι δυναμικοί. Τα αιτήματα δημιουργίας μπορούν προαιρετικά να περιλαμβάνουν expires_at ως χρονική σήμανση ISO 8601· τα ab_enabled, ab_target_url_b και ab_weight_a (προορισμοί A/B) γίνονται δεκτά για δυναμικούς κωδικούς url· το redirect_after_expiry δεν αποτελεί μέρος του συμβολαίου δημιουργίας.
Το GET /v1/codes υποστηρίζει μόνο limit, cursor και status (live, paused, flagged, draft).
Το POST /v1/codes/batch δέχεται url, vcard και wifi. Το όριο είναι 10 για Free, 500 για Pro και 1.000 εγγραφές για Business/Agency/Enterprise ανά αίτημα. Οι έλεγχοι URL εκτελούνται συγχρονισμένα για έως 50 στοιχεία URL· πάνω από 50 απαιτείται skip_url_scan: true.

Επισκόπηση

Το Codes API είναι η καρδιά του qr3.app. Με αυτό μπορείτε να δημιουργείτε, να ενημερώνετε και να διαγράφετε δυναμικούς και στατικούς κωδικούς QR.

Βασικό URL: https://qr3.app/v1/codes

Δημιουργία Κωδικού QR

`POST /v1/codes`

curl -X POST https://qr3.app/v1/codes \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "url": "https://example.com",
    "title": "Mein erster QR-Code",
    "tags": ["marketing", "q1"],
    "is_dynamic": true
  }'

const code = await qr3.codes.create({
  type: 'url',
  url: 'https://example.com',
  title: 'Mein erster QR-Code',
  tags: ['marketing', 'q1'],
  is_dynamic: true,
});

qr3 create https://example.com --title "Mein QR-Code" --tags marketing,q1

Απόκριση (HTTP 201):

{
  "data": {
    "id": "qr_a1b2c3d4",
    "short_code": "r7f3Kx",
    "redirect_url": "https://qr3.app/r7f3Kx",
    "image_svg_url": "https://qr3.app/v1/codes/r7f3Kx/qr.svg",
    "image_png_url": "https://qr3.app/v1/codes/r7f3Kx/qr.png",
    "image_pdf_url": "https://qr3.app/v1/codes/r7f3Kx/qr.pdf",
    "image_eps_url": "https://qr3.app/v1/codes/r7f3Kx/qr.eps",
    "type": "url",
    "target_url": "https://example.com",
    "is_dynamic": true,
    "status": "live",
    "tags": ["marketing", "q1"],
    "total_scans": 0,
    "created_at": "2026-03-15T10:00:00.000Z"
  },
  "meta": { "request_id": "req_xyz123" }
}

Τύποι Κωδικών QR

Τύπος	Περιγραφή	Υποχρεωτικά πεδία
`url`	URL ιστότοπου (δυναμικό ή στατικό)	`url`
`vcard`	Επαγγελματική κάρτα (vCard 3.0)	`vcard_first_name` ή `vcard_last_name`
`wifi`	Ρύθμιση παραμέτρων Wi-Fi	`wifi_ssid`
`email`	E-mail (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Τοποθεσία (geo:)	`location_lat`, `location_lng`

Μαζική Δημιουργία

`POST /v1/codes/batch`

curl -X POST https://qr3.app/v1/codes/batch \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "url", "url": "https://produkt-1.example.com", "tags": ["batch"] },
      { "type": "url", "url": "https://produkt-2.example.com", "tags": ["batch"] },
      { "type": "wifi", "wifi_ssid": "GastWLAN", "wifi_password": "geheim123" }
    ],
    "skip_url_scan": false
  }'

Απόκριση (HTTP 201):

{
  "data": {
    "created": [
      { "id": "qr_...", "short_code": "abc123", "redirect_url": "https://qr3.app/abc123" },
      { "id": "qr_...", "short_code": "def456", "redirect_url": "https://qr3.app/def456" },
      { "id": "qr_...", "short_code": "ghi789", "status": "live" }
    ],
    "total": 3,
    "failed": 0
  }
}

Λίστα Κωδικών QR

`GET /v1/codes`

curl https://qr3.app/v1/codes?status=live&limit=20 \
  -H "Authorization: Bearer qr3_sk_..."

Παράμετροι ερωτήματος (Query Parameters):

Παράμετρος	Τύπος	Προεπιλογή	Περιγραφή
`cursor`	string	—	Δρομέας (cursor) για σελιδοποίηση
`limit`	integer	20	Αποτελέσματα ανά σελίδα (μέγ. 100)
`status`	string	—	Φίλτρο: `live`, `paused`, `flagged`, `draft`

Ανάκτηση Κωδικού QR

`GET /v1/codes/:id`

curl https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..."

Ενημέρωση Κωδικού QR

`PATCH /v1/codes/:id`

Update contract: url may be changed only for an existing type: "url" code, and its value must use http:// or https://. Other code types must not receive url; invalid requests return 422.

Οι δυναμικοί κωδικοί QR σάς επιτρέπουν να αλλάζετε το URL προορισμού ανά πάσα στιγμή — χωρίς να χρειάζεται να εκτυπώσετε ξανά τον κωδικό QR.

curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://neue-zielseite.example.com", "status": "live" }'

Σελίδα Προορισμού & Εξωτερικοί Σύνδεσμοι

Για δυναμικούς κωδικούς url, μπορείτε να ορίσετε is_landing_page: true (κατά τη δημιουργία ή μέσω PATCH). Μια σάρωση θα εμφανίσει τότε μια σελίδα που φιλοξενείται από το qr3 με τα δημόσια αρχεία και τους εξωτερικούς συνδέσμους του κωδικού, αντί να κάνει ανακατεύθυνση. Οι εξωτερικοί σύνδεσμοι μεταβιβάζονται ως πίνακας links:

{
  "is_landing_page": true,
  "links": [
    { "label": "Datenblatt", "url": "https://example.com/datenblatt.pdf" },
    { "label": "Zertifikat", "url": "https://example.com/zertifikat.pdf" }
  ]
}

0–20 σύνδεσμοι ανά κωδικό. Το label πρέπει να είναι 1–100 χαρακτήρες. Το url πρέπει να είναι http(s) (≤ 2048 χαρακτήρες).
Κάθε URL ελέγχεται με το Google Web Risk — ένα μη ασφαλές URL επιστρέφει 422.
Εάν το Web Risk δεν είναι προσβάσιμο κατά την αποθήκευση, ο σύνδεσμος γίνεται παρ’ όλα αυτά αποδεκτός, αλλά επισημαίνεται για επανέλεγχο. Μια καθημερινή εργασία ελέγχει ξανά τους αποθηκευμένους συνδέσμους (και επανελέγχει περιοδικά τους συνδέσμους που έχουν χαρακτηριστεί ως ασφαλείς) και θέτει σε παύση αυτόματα τον κωδικό, εάν κάποιος σύνδεσμος αναγνωριστεί αργότερα ως μη ασφαλής.
Το "links": [] διαγράφει όλους τους συνδέσμους. Δείτε τον οδηγό σελίδας προορισμού.

Διαγραφή Κωδικού QR

`DELETE /v1/codes/:id`

Ήπια διαγραφή (Soft-Delete) — ο κωδικός QR αρχειοθετείται, τα δεδομένα σάρωσης διατηρούνται.

curl -X DELETE https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..."

Λήψη Εικόνων QR

Όλες οι μορφές εικόνας είναι δημόσια προσβάσιμες — δεν απαιτείται έλεγχος ταυτότητας.

Μορφή	URL	Χρήση
SVG (Διανυσματικό)	`/v1/codes/:code/qr.svg`	Ιστός, Κλιμάκωση, Ψηφιακά μέσα
PNG (Ψηφιογραφικό)	`/v1/codes/:code/qr.png`	E-mail, Παρουσιάσεις
PDF (Διανυσματικό)	`/v1/codes/:code/qr.pdf`	Προεπιλογή: τετράγωνο (μόνο ο κώδικας), `?format=a4` για φύλλο εκτύπωσης
EPS (Διανυσματικό)	`/v1/codes/:code/qr.eps`	Επαγγελματικές ροές εργασίας εκτύπωσης (Adobe, τυπογραφεία)

Προαιρετικά: ?size=N — Μέγεθος στοιχείου (module) σε pixel (2–20, προεπιλογή: 4) για SVG, PNG και EPS. Το PDF χρησιμοποιεί σταθερό μέγεθος στοιχείου.

Μόνο για PDF: ?format=a4|square — Μορφή σελίδας (προεπιλογή: square — μόνο ο κώδικας + Quiet Zone, χωρίς λευκό χώρο A4, a4 για ένα έτοιμο προς εκτύπωση φύλλο A4)

# SVG für Web
curl https://qr3.app/v1/codes/r7f3Kx/qr.svg

# PNG in hoher Auflösung
curl https://qr3.app/v1/codes/r7f3Kx/qr.png?size=10 -o qr-hires.png

# Kompaktes PDF (nur der Code, Standard)
curl https://qr3.app/v1/codes/r7f3Kx/qr.pdf -o qr.pdf

# Druckfertiges A4-Blatt
curl "https://qr3.app/v1/codes/r7f3Kx/qr.pdf?format=a4" -o qr-a4.pdf

Σχόλια

Τα σχόλια επιτρέπουν κύκλους ανατροφοδότησης (feedback loops) μεταξύ διαφημιστικών εταιρειών (agencies) και πελατών.

`GET /v1/codes/:id/comments`

`POST /v1/codes/:id/comments`

`PATCH /v1/codes/:id/comments/:commentId`

`DELETE /v1/codes/:id/comments/:commentId`

# Kommentar hinzufügen
curl -X POST https://qr3.app/v1/codes/qr_a1b2c3d4/comments \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "body": "QR-Code bitte auf grünen Hintergrund abstimmen.", "author_name": "Max Müller" }'

# Offene Kommentare auflisten
curl "https://qr3.app/v1/codes/qr_a1b2c3d4/comments?resolved=false" \
  -H "Authorization: Bearer qr3_sk_..."

# Kommentar als erledigt markieren
curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4/comments/cmt_xyz \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "resolved": true }'