QR Codes għall-Iżviluppaturi: REST API, SDK u CLI

Bħala żviluppatur, ma tridx toħloq kodiċijiet QR manwalment permezz ta' dashboard — trid tiġġenerahom awtomatikament, tintegrahom fil-build pipeline tiegħek, u tirreaġixxi għall-iskens permezz tal-webhooks. Dak hu eżattament dak li għalih inbena qr3.app.

L-Istack

qr3.app huwa kompletament Cloudflare-native:

API Worker: Hono fuq Cloudflare Workers (V8 runtime, bla ebda dipendenza fuq Node.js)
Redirect Worker: worker ultra-rqiq, redirects KV-cached f'< 5ms p50
Database: Cloudflare D1 (SQLite) b'multi-tenancy permezz ta' workspace_id
Queue: avvenimenti ta' skens diżakkoppjati permezz ta' Cloudflare Queues

Awtentikazzjoni

It-talbiet API kollha jeħtieġu Bearer token u workspace ID:

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

Oħloq API keys fuq app.qr3.app/dashboard/api-keys.

SDK tat-TypeScript

npm install @qr3/sdk
# jew
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!,
});

// Oħloq kodiċi QR
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);    // URL tal-immaġni SVG
console.log(code.redirect_url);     // https://qr3.app/r7f3Kx

// Ibdel l-URL aktar tard (kodiċijiet dinamiċi biss)
await client.codes.update(code.id, {
  url: "https://my-shop.com/product/42-new",
});

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

REST API Diretta

Mingħajr dipendenza fuq l-SDK? Ir-REST API tista' tintuża direttament:

# Oħloq kodiċi QR
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
  }'

# Elenka l-kodiċijiet QR kollha
curl https://qr3.app/v1/codes?limit=20 \
  -H "Authorization: Bearer $QR3_API_KEY"

# Niżżel il-kodiċi QR bħala SVG (b'logo overlay)
curl "https://qr3.app/v1/codes/r7f3Kx/qr.svg?size=8&logo_url=https://mylogo.com/logo.png" \
  -o qrcode.svg

CLI

Għall-iscripting u s-CI/CD hemm il-@qr3/cli:

npm install -g @qr3/cli
qr3 login

# Oħloq kodiċi QR u ħżnu bħala SVG
qr3 codes create --url "https://my-site.com" --title "CI Deploy" --output qr.svg

# Ħolqien batch minn CSV
qr3 codes batch import urls.csv --format svg --output ./qr-codes/

Webhooks: Irreaġixxi għall-Iskens

Il-webhooks huma l-aktar funzjoni b'saħħitha: tista' tirreaġixxi f'ħin reali għal kull sken.

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

Payload tal-Webhook

{
  "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"
  }
}

Ivverifika l-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

Pjan	Kodiċijiet/Jum	Talbiet API/Min
Free	10	60
Pro	100	300
Business	1,000	1,200
Enterprise	Bla limitu	Personalizzat

Headers tar-rate limit f'kull rispons:

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

Format tal-Iżbalji (RFC 7807)

L-iżbalji kollha jsegwu 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" }
  ]
}

Konklużjoni

qr3.app inbena mill-bidu nett bħala għodda għall-iżviluppaturi: REST API miftuħa, SDK TypeScript-first, CLI, webhooks u dokumentazzjoni OpenAPI kompluta. Iċċekkja d-dokumentazzjoni tal-API jew ibda fid-Dashboard.