Abundera QR Pro API

ভূমিকা

Abundera QR Pro API আপনাকে programmatically ডায়নামিক QR কোড তৈরি, edit ও analyze করতে দেয়, dashboard থেকে একজন developer যা automate করতে চান সব কিছু। Team management, billing ও account flow dashboard UI-তে থাকে; এই API developer-grade code operation-এ scoped।

Base URL: https://pro.qr.abundera.ai/api

Request format: POST / PATCH / DELETE-এ JSON (Content-Type: application/json)।

Response format: JSON (application/json; charset=utf-8)।

Availability: API access একটি Business+ feature। Solo plan dashboard ব্যবহার করতে পারে কিন্তু API নয়।

Authentication

প্রতিটি request bearer token হিসেবে একটি API key বহন করে:

Authorization: Bearer abnd_qrpro_...

/account/keys-এ (Business, Team বা Agency tier) key তৈরি ও revoke করুন। Raw abnd_qrpro_... token creation-এ একবারই দেখানো হয়, অবিলম্বে store করুন। আমরা শুধুমাত্র এর SHA-256 hash store করি; হারানো key recover করার কোনো উপায় নেই।

Unauthenticated request 401 { "error": "not_signed_in" } return করে। Invalid বা revoked key 401 { "error": "invalid_api_key" } return করে।

API key সেই user-এর কাছে scoped যে তৈরি করেছে। যদি সেই user কোনো team-এর member হয়, নিচের endpoint স্বয়ংক্রিয়ভাবে team-এর কোডে operate করে (current-team context user account-এ stored এবং dashboard-এর মাধ্যমে managed)।

Rate limit

API key প্রতি enforced। প্রতিটি response X-RateLimit-Limit, X-RateLimit-Remaining ও X-RateLimit-Reset (window roll over-এর unix seconds) বহন করে।

Over-budget request 429 { "error": "rate_limited", "window": "day", "retry_at": 1234567890 } সেকেন্ডে Retry-After header সহ return করে।

Scan rate-limited নয়, redirect hot path (aqr.net/{shortcode})-এ কোনো auth ও কোনো per-scan budget নেই। প্রতিটি plan-এ explicit monthly scan cap (১০০k / ১M / ১০M / ৩০M) আছে। Cap অতিক্রম করলে redirect এখনো resolve করে; আমরা ইমেইল করি যাতে আপনি upgrade বা one-off spike ride out করবেন সিদ্ধান্ত নিতে পারেন। ~১০M daily scan-এর উপরে plan করছেন? capacity coordinate করতে ইমেইল করুন।

Error

প্রতিটি error response machine-readable error code সহ JSON এবং, relevant হলে, অতিরিক্ত context:

{ "error": "plan_limit", "plan": "business", "limit": 500, "current": 500 }

Codes

ডায়নামিক QR কোড: একটি ৭-char Base58 shortcode যা aqr.net/{shortcode}-এর মাধ্যমে redirect করে। প্রতিটি কোড একটি static-backup QR বহন করে যা dashboard থেকে download করা যায়, কখনো pay বন্ধ করলে, static version আমাদের redirect স্পর্শ না করেই resolve করে।

GET /api/codes

আপনার current scope-এ (personal, বা যে team-এর অধীনে কাজ করছেন) সব কোড list করুন। প্রতি কোডে ৩০-দিনের scan rollup সহ array return করে।

$ curl -H "Authorization: Bearer abnd_qrpro_..." \
       https://pro.qr.abundera.ai/api/codes

{
  "codes": [
    { "id": "uuid", "shortcode": "aBc123x",
      "url": "https://example.com/landing",
      "label": "Q2 campaign", "tags": "q2,print",
      "status": "active", "scans_30d": 1245,
      "created_at": 1713288000, "updated_at": 1713370000 }
  ],
  "plan": "business",
  "plan_limit": 500,
  "scope": { "type": "user" }
}

POST /api/codes

একটি নতুন ডায়নামিক কোড তৈরি করুন। Insert-এর আগে আপনার plan-এর active+paused code cap check করা হয়। Minimal body:

{ "url": "https://example.com/landing" }

সম্পূর্ণ customization (সব optional):

{ "url":          "https://example.com/landing",
  "label":        "Spring campaign",
  "tags":         "q2,print",
  "qr_type":      "url",
  "style_json":   "{...}",
  "logo_key":     "instagram",
  "frame_style":  "scan-me",
  "frame_text":   "SCAN ME" }

Generated shortcode ও আপনি print করা short_url সহ created row-সহ 201 return করে।

GET /api/codes/{id}

একটি single কোড fetch করুন। আপনার scope-এ না থাকলে 404।

PATCH /api/codes/{id}

যেকোনো mutable field আপডেট করুন। সবচেয়ে সাধারণ ব্যবহার: ইতোমধ্যে-print করা কোডের destination URL পরিবর্তন করুন।

$ curl -X PATCH \
       -H "Authorization: Bearer abnd_qrpro_..." \
       -H "Content-Type: application/json" \
       -d '{"url":"https://example.com/new-landing"}' \
       https://pro.qr.abundera.ai/api/codes/uuid

পরিবর্তন সেকেন্ডের মধ্যে redirect-এ প্রচার হয়। PATCH-এর জন্য valid status মান: "active", "paused"। Delete করতে DELETE ব্যবহার করুন।

DELETE /api/codes/{id}

Soft-delete। grace_until = now + 90 days সহ status=grace-এ transition। পুরো grace window-এ redirect কাজ করতে থাকে, এটাই no-lock-in pricing promise concrete। ৯০ দিন পরে কোড expired হয় এবং redirect 410 Gone return করে।

POST /api/codes/import

Array payload থেকে bulk-create (qr.abundera.ai-এ "Save to Pro" flow-ও ব্যবহার করে)। Single code payload বা array accept করে। Batch-এর আগে plan limit একবার enforced।

Analytics

GET /api/codes/{id}/analytics

Query param:

• range=7d|30d|90d|1y|3y, আপনার plan-এর retention-এ capped (Solo 1y, Business 2y, Team/Agency 3y)।
• granularity=day|hour, hourly শুধুমাত্র Team ও Agency; hourly-র জন্য সর্বোচ্চ ৭-দিনের window।

{
  "range": "30d", "days": 30, "granularity": "day",
  "total": 4321,
  "timeseries": [
    { "bucket": "2026-04-01", "scans": 142 },
    { "bucket": "2026-04-02", "scans": 178 },
    ...
  ],
  "by_country": [
    { "key": "US", "total": 3012 },
    { "key": "CA", "total": 402 },
    { "key": "Other", "total": 108 }
  ],
  "by_device":  [
    { "key": "mobile",  "total": 3850 },
    { "key": "tablet",  "total": 312 },
    { "key": "desktop", "total": 159 }
  ]
}

Window-এ ৫-এর কম স্ক্যান সহ দেশ privacy-র জন্য "Other"-এ fold হয় (Privacy model দেখুন)।

API keys

/account/keys dashboard page থেকে key তৈরি ও revoke করুন। Programmatic self-management API দিয়ে read-only, আপনি আপনার key list ও revoke করতে পারেন, কিন্তু নতুন key তৈরিতে dashboard লাগে (chicken-and-egg: key তৈরিতে key লাগত)।

GET /api/keys

আপনার API key list করুন। কখনো raw token return করে না, শুধুমাত্র metadata।

{
  "keys": [
    { "id": "uuid", "label": "Production server",
      "created_at": 1713288000, "last_used_at": 1713370000 }
  ],
  "allowed": true,
  "plan": "business"
}

DELETE /api/keys/{id}

Revoke করুন। Key অবিলম্বে কাজ বন্ধ করে; এর পরে এটি বহনকারী যেকোনো request 401 invalid_api_key return করে।

ডেটা export

GET /api/user/export

আপনার full dataset ধারণকারী একটি ZIP download করুন, codes.csv (grace + expired সহ প্রতিটি কোড), scans.csv (aggregated daily rollup) ও format explain করে একটি README.txt। Archive application/zip হিসেবে emitted; একটি file-এ pipe করুন:

$ curl -H "Authorization: Bearer abnd_qrpro_..." \
       -o abundera-qr-export.zip \
       https://pro.qr.abundera.ai/api/user/export

যেকোনো জায়গায় re-import করুন। এটাই portable-format guarantee, আপনি আপনার ডেটার মালিক হলে কোনো vendor lock-in সম্ভব নয়।

Privacy model

স্ক্যান aggregate হলো পুরো privacy গল্প। redirect hot path-এ প্রতি স্ক্যানে আমরা কী store করি:

• code_id, আপনার কোনো কোড scan হয়েছিল
• day_bucket, UTC date (YYYY-MM-DD)। আপনাকে return করা aggregate-এ sub-day precision নেই।
• country, Cloudflare-এর CF-IPCountry header থেকে ISO-3166-1 alpha-2। কোনো city নেই, কোনো region নেই, কোনো geo-IP lookup নেই।
• device_type, mobile / tablet / desktop / unknown, একটি short User-Agent regex থেকে classified। Raw UA string classification সময়ে বাতিল হয়।
• scan_count, aggregate counter, প্রতিটি hit-এ upserted।

আমরা store করি না: IP address (hashed বা অন্যথায়), raw User-Agent string, city-level geo, sub-day timestamp, referer, cookie, retargeting pixel, বা যেকোনো individual-identifying vector। ৫-এর noise floor ছোট-aggregate re-identification দমন করে।

Team ও Agency tier অতিরিক্তভাবে hour_bucket (YYYY-MM-DD-HH UTC) সহ একটি parallel hourly aggregate লেখে। একই privacy model, hour-এর চেয়ে finer timestamp নেই, একই noise floor, individual-scanner ডেটার একই অনুপস্থিতি।

সম্পূর্ণ গল্প পড়ুন: free-tool site-এ /manifesto/ ও /no-lock-in/।