QR Codes για Developers: REST API, SDK και CLI

Ως developer, δεν θέλετε να δημιουργείτε QR codes χειροκίνητα μέσα από ένα dashboard — θέλετε να τα παράγετε αυτόματα, να τα ενσωματώνετε στο build pipeline σας και να αντιδράτε σε σαρώσεις μέσω webhooks. Ακριβώς γι' αυτό είναι φτιαγμένο το qr3.app.

Το Stack

Το qr3.app είναι πλήρως Cloudflare-native:

• API Worker: Hono πάνω σε Cloudflare Workers (V8 runtime, μηδέν εξαρτήσεις από Node.js)
• Redirect Worker: Εξαιρετικά ελαφρύς worker, ανακατευθύνσεις με KV-cache σε < 5ms p50
• Database: Cloudflare D1 (SQLite) με multi-tenancy μέσω workspace_id
• Queue: Τα events σάρωσης αποσυνδέονται μέσω Cloudflare Queues

Authentication

Όλα τα αιτήματα προς το API απαιτούν ένα Bearer token και ένα workspace ID:

POST https://qr3.app/v1/codes
Authorization: Bearer qr3_sk_...
Content-Type: application/json

Δημιουργήστε API keys στο app.qr3.app/dashboard/api-keys.

TypeScript SDK

npm install @qr3/sdk
# ή
pnpm add @qr3/sdk

import { QR3 } from "@qr3/sdk";

const client = new QR3({
  apiKey: process.env.QR3_API_KEY!,
  workspaceId: process.env.QR3_WORKSPACE_ID!,
});

// Create a QR code
const { data: code } = await client.codes.create({
  type: "url",
  url: "https://my-shop.com/product/42",
  title: "Product 42",
  tags: ["shop", "product"],
});

console.log(code.short_code);       // "r7f3Kx"
console.log(code.image_svg_url);    // SVG image URL
console.log(code.redirect_url);     // https://qr3.app/r7f3Kx

// Change URL later (dynamic codes only)
await client.codes.update(code.id, {
  url: "https://my-shop.com/product/42-new",
});

// Query analytics
const stats = await client.codes.stats(code.id, {
  from: "2026-01-01",
  to: "2026-03-31",
});
console.log(stats.data.total_scans); // e.g. 1247

REST API απευθείας

Δεν θέλετε εξάρτηση από το SDK; Το REST API είναι άμεσα αξιοποιήσιμο:

# Create a QR code
curl -X POST https://qr3.app/v1/codes \
  -H "Authorization: Bearer $QR3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "url": "https://my-site.com",
    "title": "My Site",
    "is_dynamic": true
  }'

# List all QR codes
curl https://qr3.app/v1/codes?limit=20 \
  -H "Authorization: Bearer $QR3_API_KEY"

# Download QR code as SVG (with logo overlay)
curl "https://qr3.app/v1/codes/r7f3Kx/qr.svg?size=8&logo_url=https://mylogo.com/logo.png" \
  -o qrcode.svg

CLI

Για scripting και CI/CD υπάρχει το @qr3/cli:

npm install -g @qr3/cli
qr3 login

# Create QR code and save as SVG
qr3 codes create --url "https://my-site.com" --title "CI Deploy" --output qr.svg

# Batch creation from CSV
qr3 codes batch import urls.csv --format svg --output ./qr-codes/

Webhooks: Αντιδράστε στις σαρώσεις

Τα webhooks είναι το πιο ισχυρό χαρακτηριστικό: μπορείτε να αντιδράτε σε πραγματικό χρόνο σε κάθε σάρωση.

// Register a webhook
const { data: webhook } = await client.webhooks.create({
  url: "https://your-app.com/webhooks/qr3",
  events: ["scan.created", "code.updated"],
});

Webhook Payload

{
  "event": "scan.created",
  "timestamp": "2026-03-15T14:30:00Z",
  "data": {
    "code_id": "code_abc123",
    "short_code": "r7f3Kx",
    "country": "DE",
    "city": "Berlin",
    "device": "mobile",
    "os": "iOS",
    "browser": "Safari"
  }
}

Επαλήθευση Webhooks (HMAC)

import { createHmac } from "crypto";

export async function verifyWebhook(
  payload: string,
  signature: string,
  secret: string,
): Promise<boolean> {
  const expected = createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return `sha256=${expected}` === signature;
}

Rate Limiting

Πλάνο	Codes/Ημέρα	API Requests/Λεπτό
Free	10	60
Pro	100	300
Business	1,000	1,200
Enterprise	Απεριόριστα	Custom

Headers του rate limit σε κάθε απόκριση:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1710510060

Μορφή σφαλμάτων (RFC 7807)

Όλα τα σφάλματα ακολουθούν το RFC 7807 Problem Details:

{
  "type": "https://docs.qr3.app/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "url is required for type 'url'",
  "errors": [
    { "field": "url", "message": "Required" }
  ]
}

Συμπέρασμα

Το qr3.app είναι φτιαγμένο εξαρχής ως εργαλείο για developers: ανοιχτό REST API, SDK με TypeScript-first προσέγγιση, CLI, webhooks και πλήρης τεκμηρίωση OpenAPI. Ρίξτε μια ματιά στην τεκμηρίωση του API ή ξεκινήστε από το Dashboard.