API Κωδικών QR

Επισκόπηση

Το 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`

Δοκιμές A/B

Δοκιμάστε δύο διαφορετικά URL προορισμού με σταθμισμένη ανακατεύθυνση:

{
  "type": "url",
  "url": "https://version-a.example.com",
  "ab_enabled": true,
  "ab_target_url_b": "https://version-b.example.com",
  "ab_weight_a": 50
}

Λήξη (Expiry)

Οι κωδικοί QR μπορούν να λήγουν αυτόματα:

{
  "type": "url",
  "url": "https://aktionsseite.example.com",
  "expires_at": "2026-12-31T23:59:59Z",
  "redirect_after_expiry": "https://archiv.example.com"
}

Μετά τη λήξη, γίνεται είτε ανακατεύθυνση στο redirect_after_expiry είτε εμφανίζεται μια σελίδα 410.

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

`POST /v1/codes/batch`

Δημιουργεί έως και 1.000 κωδικούς QR σε ένα μόνο αίτημα. Ιδανικό για μαζικές εφαρμογές.

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`

Οι δυναμικοί κωδικοί 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 }'