Abundera QR Pro API

تعارف

Abundera QR Pro API آپ کو پروگرامی طور پر متحرک QR کوڈز بنانے، ترمیم کرنے، اور تجزیہ کرنے دیتا ہے, وہ سب کچھ جو ایک developer dashboard سے automate کرنا چاہتا ہے۔ ٹیم مینجمنٹ، billing، اور account flows dashboard UI میں رہتے ہیں؛ یہ API developer-grade code operations تک محدود ہے۔

بنیادی URL: https://pro.qr.abundera.ai/api

درخواست فارمیٹ: JSON (Content-Type: application/json) POST / PATCH / DELETE پر۔

جواب فارمیٹ: JSON (application/json; charset=utf-8)۔

دستیابی: API تک رسائی Business+ کی خصوصیت ہے۔ Solo پلانز dashboard استعمال کر سکتے ہیں لیکن API نہیں۔

توثیق

ہر درخواست bearer token کے طور پر API key لے کر چلتی ہے:

Authorization: Bearer abnd_qrpro_...

/account/keys پر keys بنائیں اور منسوخ کریں (Business، Team، یا Agency tier)۔ خام abnd_qrpro_... token بنانے کے وقت صرف ایک بار دکھایا جاتا ہے, فوراً محفوظ کریں۔ ہم صرف اس کا SHA-256 hash محفوظ کرتے ہیں؛ کھوئی ہوئی key دوبارہ حاصل کرنے کا کوئی طریقہ نہیں ہے۔

غیر تصدیق شدہ درخواستیں 401 { "error": "not_signed_in" } لوٹاتی ہیں۔ غلط یا منسوخ keys 401 { "error": "invalid_api_key" } لوٹاتی ہیں۔

API keys اس user تک محدود ہیں جس نے انہیں بنایا۔ اگر وہ user کسی team کا رکن ہے، تو نیچے دیے گئے endpoints خود بخود team کے کوڈز پر کام کریں گے (current-team context user account پر محفوظ ہے اور dashboard کے ذریعے منظم ہے)۔

Rate limits

فی API key نافذ۔ ہر جواب X-RateLimit-Limit، X-RateLimit-Remaining، اور X-RateLimit-Reset (unix seconds جب window ختم ہوگی) لے کر آتا ہے۔

بجٹ سے زیادہ درخواستیں 429 { "error": "rate_limited", "window": "day", "retry_at": 1234567890 } سیکنڈوں میں Retry-After header کے ساتھ لوٹاتی ہیں۔

Scans پر rate-limit نہیں ہے, redirect hot path (aqr.net/{shortcode}) میں کوئی توثیق نہیں اور فی scan کوئی بجٹ نہیں۔ ہر پلان میں واضح ماہانہ scan cap ہے (100k / 1M / 10M / 30M)۔ cap سے تجاوز کریں اور redirect پھر بھی کام کرتا ہے؛ ہم آپ کو email کرتے ہیں تاکہ آپ فیصلہ کریں۔ تقریباً 10M روزانہ scans سے زیادہ منصوبہ بنا رہے ہیں؟ صلاحیت کو مربوط کرنے کے لیے ہمیں email کریں۔

خرابیاں

ہر error جواب machine-readable error code اور جہاں متعلقہ ہو، اضافی context کے ساتھ JSON ہے:

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

کوڈز

متحرک QR کوڈز: ایک 7-char Base58 shortcode جو aqr.net/{shortcode} سے redirect کرتا ہے۔ ہر کوڈ میں ایک static-backup QR ہے جسے آپ dashboard سے download کر سکتے ہیں, اگر آپ کبھی ادائیگی بند کر دیں، static ورژن ہمارے redirect کو چھوئے بغیر کام کرتا رہتا ہے۔

GET /api/codes

آپ کے current scope میں تمام کوڈز کی فہرست (ذاتی، یا وہ team جس کے تحت آپ ابھی کام کر رہے ہیں)۔ فی کوڈ 30 دن کے scan rollup کے ساتھ array لوٹاتا ہے۔

$ 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 سے پہلے آپ کے پلان کی active+paused code cap چیک ہوتی ہے۔ کم از کم body:

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

مکمل تخصیص (سب اختیاری):

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

تخلیق شدہ row کے ساتھ 201 لوٹاتا ہے جس میں generated shortcode اور short_url شامل ہے جو آپ پرنٹ کرتے ہیں۔

GET /api/codes/{id}

ایک کوڈ لائیں۔ اگر آپ کے scope میں نہیں تو 404۔

PATCH /api/codes/{id}

کوئی بھی قابل تبدیل field اپ ڈیٹ کریں۔ سب سے عام استعمال: پہلے سے پرنٹ شدہ کوڈ کی منزل 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 کے لیے درست status values: "active"، "paused"۔ حذف کرنے کے لیے DELETE استعمال کریں۔

DELETE /api/codes/{id}

Soft-delete۔ grace_until = now + 90 days کے ساتھ status=grace میں منتقل ہوتا ہے۔ پوری grace ونڈو کے دوران redirect کام کرتا رہتا ہے, یہ no-lock-in قیمتی وعدہ عملی شکل میں ہے۔ 90 دن کے بعد کوڈ expired ہو جاتا ہے اور redirect 410 Gone لوٹاتا ہے۔

POST /api/codes/import

Array payload سے bulk-create کریں (یہ qr.abundera.ai پر "Save to Pro" flow بھی استعمال کرتا ہے)۔ ایک کوڈ payload یا array قبول کرتا ہے۔ Plan limit batch سے پہلے ایک بار چیک ہوتی ہے۔

Analytics

GET /api/codes/{id}/analytics

Query params:

• range=7d|30d|90d|1y|3y, آپ کے پلان کی retention پر محدود (Solo 1y، Business 2y، Team/Agency 3y)۔
• granularity=day|hour, hourly صرف Team اور Agency کے لیے؛ hourly کے لیے زیادہ سے زیادہ 7 دن کی ونڈو۔

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

ونڈو میں 5 سے کم scans والے ممالک privacy کے لیے "Other" میں ضم ہو جاتے ہیں (Privacy ماڈل دیکھیں)۔

API keys

/account/keys dashboard صفحے سے keys بنائیں اور منسوخ کریں۔ پروگرامی self-management API کے ذریعے صرف پڑھنے تک محدود ہے, آپ اپنی keys فہرست کر سکتے ہیں اور منسوخ کر سکتے ہیں، لیکن نئی key بنانے کے لیے dashboard ضروری ہے (chicken-and-egg: آپ کو key بنانے کے لیے key کی ضرورت ہوگی)۔

GET /api/keys

آپ کی API keys فہرست کریں۔ کبھی خام token نہیں لوٹاتا, صرف metadata۔

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

DELETE /api/keys/{id}

منسوخ کریں۔ key فوری طور پر کام کرنا بند کر دیتی ہے؛ اس کے بعد اسے carry کرنے والی کوئی بھی درخواست 401 invalid_api_key لوٹاتی ہے۔

ڈیٹا برآمد

GET /api/user/export

آپ کا مکمل dataset پر مشتمل ZIP download کریں, codes.csv (ہر کوڈ، grace + expired سمیت)، scans.csv (مجموعی روزانہ rollup)، اور فارمیٹ بیان کرنے والی README.txt۔ archive application/zip کے طور پر emit ہوتا ہے؛ اسے file میں pipe کریں:

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

کہیں بھی دوبارہ import کریں۔ یہ portable-format گارنٹی ہے, اگر آپ اپنا ڈیٹا خود رکھتے ہیں تو vendor lock-in ممکن نہیں۔

Privacy ماڈل

scan aggregate پوری privacy کہانی ہے۔ redirect hot path پر فی scan ہم کیا محفوظ کرتے ہیں:

• code_id, آپ کے کون سے کوڈ کو scan کیا گیا
• day_bucket, UTC تاریخ (YYYY-MM-DD)۔ آپ کو لوٹائے گئے aggregate پر sub-day precision نہیں۔
• country, Cloudflare کے CF-IPCountry header سے ISO-3166-1 alpha-2۔ کوئی شہر نہیں، کوئی علاقہ نہیں، کوئی geo-IP lookup نہیں۔
• device_type, mobile / tablet / desktop / unknown، مختصر User-Agent regex سے درجہ بند۔ خام UA string درجہ بندی کے وقت ضائع کر دی جاتی ہے۔
• scan_count, مجموعی counter، ہر hit پر upsert۔

ہم نہیں محفوظ کرتے: IP addresses (hash یا بصورت دیگر)، خام User-Agent strings، شہر سطح geo، sub-day timestamps، referer، cookies، retargeting pixels، یا کوئی بھی individual-identifying vector۔ 5 کا noise floor چھوٹے aggregate re-identification کو دباتا ہے۔

Team اور Agency tiers اضافی طور پر hour_bucket (YYYY-MM-DD-HH UTC) کے ساتھ ایک parallel hourly aggregate لکھتے ہیں۔ وہی privacy ماڈل, کوئی hour سے باریک timestamps نہیں، وہی noise floor، individual-scanner ڈیٹا کی وہی غیر موجودگی۔

پوری کہانی پڑھیں: free-tool سائٹ پر /manifesto/ اور /no-lock-in/۔