Abundera QR Pro API

المقدمة

يتيح لك Abundera QR Pro API إنشاء رموز QR الديناميكية وتعديلها وتحليلها برمجياً, كل ما يريد المطور أتمتته من لوحة التحكم dashboard. إدارة الفريق والفوترة وتدفقات الحسابات تبقى في واجهة لوحة التحكم؛ هذا API مخصص لعمليات الرموز على مستوى المطورين.

عنوان URL الأساسي: https://pro.qr.abundera.ai/api

صيغة الطلب: JSON (Content-Type: application/json) في POST / PATCH / DELETE.

صيغة الاستجابة: JSON (application/json; charset=utf-8).

التوفر: الوصول إلى API ميزة خاصة بخطة Business وما فوق. خطط Solo يمكنها استخدام لوحة التحكم لكن ليس API.

المصادقة

كل طلب يحمل مفتاح API كـ bearer token:

Authorization: Bearer abnd_qrpro_...

أنشئ المفاتيح وألغِها في /account/keys (خطة Business أو Team أو Agency). يُعرض الـ token الخام abnd_qrpro_... مرة واحدة فقط عند الإنشاء, احفظه فوراً. نخزّن فقط هاش SHA-256 الخاص به؛ لا توجد طريقة لاسترداد مفتاح مفقود.

الطلبات غير المصادق عليها تُعيد 401 { "error": "not_signed_in" }. المفاتيح غير الصالحة أو الملغاة تُعيد 401 { "error": "invalid_api_key" }.

مفاتيح API مرتبطة بالمستخدم الذي أنشأها. إن كان هذا المستخدم عضواً في فريق، تعمل نقاط الوصول التالية على رموز الفريق تلقائياً (سياق الفريق الحالي مخزّن في حساب المستخدم ويُدار عبر لوحة التحكم).

حدود الاستخدام

تُطبَّق لكل مفتاح API. كل استجابة تحمل X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset (ثوانٍ unix عند انتهاء النافذة الزمنية).

الطلبات التي تتجاوز الميزانية تُعيد 429 { "error": "rate_limited", "window": "day", "retry_at": 1234567890 } مع ترويسة Retry-After بالثواني.

عمليات المسح لا تخضع لحدود الاستخدام, مسار إعادة التوجيه (aqr.net/{shortcode}) لا يتطلب مصادقة ولا ميزانية لكل مسح. لكل خطة حد شهري صريح للمسح (100k / 1M / 10M / 30M). عند تجاوز الحد، إعادة التوجيه تستمر في العمل؛ نرسل لك بريداً إلكترونياً لتقرر إن كنت تريد الترقية أو الاستمرار بعد ارتفاع استثنائي. تتوقع أكثر من ~10M مسح يومياً؟ راسلنا لتنسيق الطاقة.

الأخطاء

كل استجابة خطأ هي JSON تحتوي كود error قابل للقراءة آلياً وسياقاً إضافياً عند الاقتضاء:

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

الرموز

رموز QR الديناميكية: shortcode من 7 أحرف Base58 يُعيد التوجيه عبر aqr.net/{shortcode}. كل رمز يأتي بنسخة احتياطية ثابتة يمكنك تنزيلها من لوحة التحكم, إن أوقفت الاشتراك، النسخة الثابتة تظل تعمل بدون لمس مسار إعادة التوجيه لدينا.

GET /api/codes

أدرج جميع الرموز في نطاقك الحالي (شخصي، أو الفريق الذي تعمل تحته حالياً). يُعيد مصفوفة مع ملخص مسح 30 يوماً لكل رمز.

$ 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

أنشئ رمزاً ديناميكياً جديداً. يُتحقق من حد رموز خطتك النشطة والموقوفة قبل الإدراج. الجسم الأدنى:

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

يُعيد 201 + الصف الذي أُنشئ بما في ذلك shortcode المُولَّد وshort_url الذي تطبعه.

GET /api/codes/{id}

جلب رمز واحد. 404 إن لم يكن ضمن نطاقك.

PATCH /api/codes/{id}

حدِّث أي حقل قابل للتعديل. الاستخدام الأكثر شيوعاً: تغيير 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

التغييرات تنتشر إلى إعادة التوجيه في غضون ثوانٍ. قيم status الصالحة في PATCH: "active"، "paused". للحذف استخدم DELETE.

DELETE /api/codes/{id}

حذف ناعم. ينتقل إلى status=grace مع grace_until = now + 90 days. إعادة التوجيه تستمر في العمل طوال فترة السماح, هذا هو وعد التسعير بلا قيود مجسّداً. بعد 90 يوماً يصبح الرمز expired وتُعيد إعادة التوجيه 410 Gone.

POST /api/codes/import

إنشاء مجمّع من payload مصفوفة (يُستخدم أيضاً في تدفق "Save to Pro" على qr.abundera.ai). يقبل payload رمز واحد أو مصفوفة. يُطبَّق حد الخطة مرة واحدة قبل الدفعة.

التحليلات

GET /api/codes/{id}/analytics

معاملات الاستعلام:

• range=7d|30d|90d|1y|3y, محدود بالاحتفاظ في خطتك (Solo سنة، Business سنتان، Team/Agency 3 سنوات).
• granularity=day|hour, الساعي متاح لـ Team وAgency فقط؛ أقصى نافذة 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 }
  ]
}

Countries with fewer than 5 scans in the window are folded into "Other" for privacy (see نموذج الخصوصية).

مفاتيح API

أنشئ المفاتيح وألغِها من صفحة لوحة التحكم /account/keys. الإدارة الذاتية البرمجية للقراءة فقط عبر API, يمكنك إدراج مفاتيحك وإلغاؤها، لكن إنشاء مفتاح جديد يتطلب لوحة التحكم (دجاجة وبيضة: ستحتاج مفتاحاً لإنشاء مفتاح).

GET /api/keys

أدرج مفاتيح API الخاصة بك. لا يُعيد الـ token الخام أبداً, البيانات الوصفية فقط.

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

DELETE /api/keys/{id}

إلغاء. يتوقف المفتاح عن العمل فوراً؛ أي طلب يحمله يُعيد 401 invalid_api_key بعد ذلك.

تصدير البيانات

GET /api/user/export

نزِّل ZIP يحتوي مجموعة بياناتك الكاملة, codes.csv (كل رمز، بما في ذلك grace والمنتهية)، scans.csv (ملخص يومي مجمَّع)، وREADME.txt يشرح الصيغة. يُبث الأرشيف بصيغة application/zip؛ وجِّهه إلى ملف:

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

استورده في أي مكان. هذا ضمان الصيغة المحمولة, لا قيود على مزوّد الخدمة ممكنة إن كنت تمتلك بياناتك.

نموذج الخصوصية

الملخص المجمَّع للمسح هو القصة الكاملة للخصوصية. ما نخزّنه لكل مسح في مسار إعادة التوجيه السريع:

• code_id, أي من رموزك تم مسحه
• day_bucket, UTC date (YYYY-MM-DD). No sub-day precision on the aggregate returned to you.
• country, ISO-3166-1 alpha-2 from Cloudflare's CF-IPCountry header. No city, no region, no geo-IP lookup.
• device_type, mobile / tablet / desktop / unknown, classified from a short User-Agent regex. The raw UA string is discarded at classification time.
• scan_count, aggregate counter, upserted on every hit.

What we do not store: IP addresses (hashed or otherwise), raw User-Agent strings, city-level geo, sub-day timestamps, referer, cookies, retargeting pixels, or any individual-identifying vector. A noise floor of 5 suppresses small-aggregate re-identification.

Team and Agency tiers additionally write a parallel hourly aggregate with hour_bucket (YYYY-MM-DD-HH UTC). Same privacy model, no finer-than-hour timestamps, same noise floor, same absence of individual-scanner data.

Read the full story: /manifesto/ and /no-lock-in/ on the free-tool site.