المطورون

مرجع API والتكاملات

كل ما تحتاجه لاستدعاء Business API وإدارة المفاتيح واستقبال الويب هوك.

← العودة إلى لوحة التحكم
المصادقةعنوان URL الأساسينقاط النهايةمفاتيح APIالصلاحياتأمثلةتحليلات المسحالمجلدات والوسومالإنشاء الجماعياشتراكات الويب هوكالويب هوكتتبّع التحويلاتالتصديرنصائح وأخطاء

المصادقة

تتحقق واجهة Business API من كل طلب عبر مفتاح API. أرسل المفتاح في ترويسة X-Api-Key، أو كرمز Bearer في ترويسة Authorization.

تبدأ المفاتيح بالبادئة qrg_ وتُعرض مرة واحدة فقط عند إنشائها. احفظها في مكان آمن؛ إذ لا يمكنك استرجاع المفتاح لاحقًا.

تُرجع الطلبات التي لا تتضمن مفتاحًا صالحًا الحالة 401. ويتلقى المفتاح الذي يفتقد الصلاحية المطلوبة الحالة 403 مع الخطأ insufficient_scope. أما الموارد خارج مساحة العمل الخاصة بك فتُرجع 404، كأنها غير موجودة.

عنوان URL الأساسي

تقع جميع نقاط نهاية Business API تحت البادئة /v1.

على سبيل المثال، اعرض قائمة رموز QR الخاصة بك عبر https://qr-global.com/api/v1/qr-codes.

عنوان URL الأساسي الفعلي
https://qr-global.com

نقاط النهاية

تقع جميع نقاط النهاية تحت /api/v1، وتتطلب كل منها مفتاحًا يملك الصلاحية المذكورة.

الطريقةالمسارالصلاحيةالوظيفة
GET/qr-codesqr:readعرض قائمة رموز QR (عوامل التصفية: type، search، folder_id، tag، archived)
POST/qr-codesqr:writeإنشاء رمز QR
POST/qr-codes/bulkqr:writeإنشاء حتى 100 رمز QR دفعة واحدة
GET/qr-codes/{id}qr:readجلب رمز QR واحد
PUT/qr-codes/{id}qr:writeتحديث رمز QR ومجلده ووسومه
DELETE/qr-codes/{id}qr:writeحذف رمز QR
GET/qr-codes/{id}/imageqr:readتوليد الصورة (PNG أو SVG)
GET/qr-codes/{id}/statsanalytics:readإحصاءات المسح
GET/qr-codes/{id}/scansanalytics:readسجل المسح
GET/foldersqr:readعرض قائمة المجلدات
GET/tagsqr:readعرض قائمة الوسوم
GET/webhookswebhooks:manageعرض قائمة اشتراكات الويب هوك
POST/webhookswebhooks:manageالاشتراك في الأحداث
DELETE/webhooks/{id}webhooks:manageإلغاء الاشتراك

وصف قابل للقراءة آليًا (OpenAPI 3.1) لاستخدامه في Postman ومولّدات الشيفرة وأدوات البرمجة دون كود: تنزيل openapi.json

مفاتيح API

أنشئ المفاتيح وألغِها من صفحة مفاتيح API في لوحة التحكم.

ينتمي كل مفتاح إلى مساحة العمل الخاصة بك ويرث حد معدل الطلبات في خطتك.

يسري إلغاء المفتاح فورًا.

مفاتيح API

الصلاحيات (النطاقات)

عند إنشاء مفتاح، امنحه وصولًا كاملًا أو الصلاحيات التي يحتاجها التكامل فقط. يتلقى المفتاح الذي يفتقد صلاحيةً الحالة 403 مع الخطأ insufficient_scope والحقل required_scope في الاستجابة.

qr:read — قراءة رموز QR
عرض قائمة رموز QR وتفاصيلها وصورها ومجلداتها ووسومها.
qr:write — إدارة رموز QR
إنشاء رموز QR (بما في ذلك الإنشاء الجماعي) وتعديلها ونقلها بين المجلدات ووسمها وحذفها.
analytics:read — قراءة التحليلات
إحصاءات المسح وسجل المسح لكل رمز QR.
webhooks:manage — إدارة الويب هوك
اشتراك نقاط النهاية في الأحداث وإلغاء اشتراكها (Zapier وMake).

تحتفظ المفاتيح التي أُنشئت قبل إضافة الصلاحيات بوصول كامل. ويشمل الوصول الكامل أيضًا الصلاحيات التي تُضاف لاحقًا.

أمثلة

أوامر curl جاهزة للنسخ واللصق لتبدأ بسرعة. استبدل YOUR_API_KEY بمفتاح من صفحة مفاتيح API.

عرض قائمة رموز QR

curl -sS -H "X-Api-Key: YOUR_API_KEY" -H "Accept: application/json" \
  "https://qr-global.com/api/v1/qr-codes"

إنشاء رمز QR

أرسل نوع QR والمحتوى؛ وسيُنشئ الخادم الرمز ويحفظه.

curl -sS -X POST "https://qr-global.com/api/v1/qr-codes" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"url","content":"https://example.com","display_name":"Example link"}'

توليد صورة

احصل على ملف PNG أو SVG جاهز — مرّر ?format=png

curl -sS "https://qr-global.com/api/v1/qr-codes/123/image?format=png&size=512" \
  -H "X-Api-Key: YOUR_API_KEY" -o qr.png

# SVG (vector, no size limit on scale):
curl -sS "https://qr-global.com/api/v1/qr-codes/123/image?format=svg" \
  -H "X-Api-Key: YOUR_API_KEY" -o qr.svg

مثال على حمولة الويب هوك

{
  "event": "qr.scan.created",
  "timestamp": "2026-04-03T12:00:00+00:00",
  "data": {
    "qr_code_id": 7,
    "qr_code_uuid": "9b2f0c1e-4d4a-4f7e-9a51-2a7c3c1d8e10",
    "type": "url",
    "scan_id": 42,
    "country": "UA",
    "device_type": "mobile",
    "scanned_at": "2026-04-03T12:00:00+00:00"
  }
}

تحليلات المسح

يُرجع GET /qr-codes/{id}/stats الإجماليات والزوار الفريدين وأبرز الدول والأجهزة والمتصفحات وعمليات المسح اليومية. ويُرجع GET /qr-codes/{id}/scans سجل المسح من الأحدث إلى الأقدم، بواقع 50 في الصفحة (ويصل per_page إلى 100).

يقبل كلاهما from وto (تاريخًا مثل 2026-10-01 أو طابعًا زمنيًا كاملًا) وtimezone (افتراضيًا UTC). التاريخ دون وقت يغطي اليوم كاملًا في تلك المنطقة الزمنية.

لا يتوفر إلا السجل ضمن الفترة التي تتيحها خطتك، وتُحذف عمليات المسح الأقدم. لا تُرجَع عناوين IP للزوار ولا بيانات User-Agent أبدًا.

إحصاءات المسح لفترة محددة

curl -sS "https://qr-global.com/api/v1/qr-codes/123/stats?from=2026-10-01&to=2026-10-31&timezone=Europe/Kyiv" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

سجل المسح، الصفحة الثانية

curl -sS "https://qr-global.com/api/v1/qr-codes/123/scans?per_page=100&page=2" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

المجلدات والوسوم

يعرض GET /folders وGET /tags مجلدات مساحة العمل الخاصة بك ووسومها. مرّر folder_id وtags (قيم slug للوسوم) عند إنشاء رمز QR أو تحديثه: القيمة folder_id null تُخرج الرمز من مجلده، وtags يستبدل مجموعة الوسوم كاملة.

صفِّ قائمة رموز QR باستخدام ?folder_id= أو ?tag=.

نقل رمز QR إلى مجلد ووسمه

curl -sS -X PUT "https://qr-global.com/api/v1/qr-codes/123" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "folder_id": 4,
  "tags": [
    "campaign",
    "priority"
  ]
}'

الإنشاء الجماعي

ينشئ POST /qr-codes/bulk حتى 100 رمز QR في طلب واحد. ويتطلب خطة تتضمن الإنشاء الجماعي، مثل استيراد CSV في لوحة التحكم، ويلتزم بحد رموز QR النشطة في خطتك.

يُعالَج كل عنصر على حدة: تسرد الاستجابة كل عنصر بالحالة created (مع الرمز الجديد) أو failed (مع error وerrors). لا تُعِد إرسال الدفعة كاملة، بل العناصر الفاشلة فقط.

إنشاء رمزي QR

curl -sS -X POST "https://qr-global.com/api/v1/qr-codes/bulk" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "codes": [
    {
      "type": "url",
      "content": "https://example.com/spring",
      "display_name": "Spring flyer",
      "tags": [
        "campaign"
      ]
    },
    {
      "type": "url",
      "content": "https://example.com/menu",
      "display_name": "Table menu",
      "folder_id": 4
    }
  ]
}'

اشتراكات الويب هوك (REST hooks)

يمكن لـ Zapier وMake وخدماتك الخاصة الاشتراك في الأحداث عبر API: أرسل POST /webhooks مع url وevents، ثم DELETE /webhooks/{id} لإلغاء الاشتراك. وهي نقاط النهاية نفسها التي تراها في صفحة الويب هوك.

تتضمن الاستجابة لطلب POST قيمة secret التي تُعرض مرة واحدة فقط: استخدمها للتحقق من ترويسة X-Webhook-Signature. إذا لم ترسل secret خاصًا بك (16 حرفًا أو أكثر)، فسنُنشئ واحدًا.

الأحداث: qr.scan.created, subscription.updated, payment.succeeded, lead.captured, rsvp.received, feedback.received, poll.voted. يتطلب الاشتراك خطة تتضمن الويب هوك، أما إلغاء الاشتراك فمتاح دائمًا. يمكن أن تضم مساحة العمل حتى 25 نقطة نهاية.

الاشتراك في عمليات المسح

curl -sS -X POST "https://qr-global.com/api/v1/webhooks" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://hooks.zapier.com/hooks/catch/123/abc/",
  "events": [
    "qr.scan.created"
  ]
}'

إلغاء الاشتراك

curl -sS -X DELETE "https://qr-global.com/api/v1/webhooks/42" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
الويب هوك متاح في خطة لايت. قم بالترقية لتفعيله.

الويب هوك

يرسل الويب هوك الأحداث إلى نقطة النهاية الخاصة بك لحظة وقوعها، فلا حاجة إلى الاستعلام الدوري.

اضبط نقاط النهاية من صفحة الويب هوك في لوحة التحكم.

كل عملية تسليم موقّعة، وتُعاد محاولتها عند الفشل مع تأخير متزايد أُسّيًا.

يُطلَق حدث المسح عندما يمسح أحدهم أحد رموز QR الخاصة بك.

افحص محاولات التسليم والحمولات والاستجابات في سجل التسليم.

أعِد حالة 2xx لتأكيد استلام التسليم؛ وتُعامَل أي حالة أخرى على أنها فشل.

عمليات تسليم الويب هوك
الويب هوك متاح في خطة لايت. قم بالترقية لتفعيله.

تتبّع التحويلات

تُخبر التحويلات اختبار A/B أي وجهة تجلب طلبات أو تسجيلات، لا مسحات فقط. عند تفعيل التحسين التلقائي، تنتقل الزيارات إلى المتغير الأعلى تحويلًا.

أضف السكربت إلى الصفحة التي يراها الزائر بعد التحويل: تأكيد الطلب أو صفحة الشكر أو النجاح. يعمل على أي نطاق ولا يحتاج إلى مفتاح API.

المقتطف

<script src="https://qr-global.com/c.js" async></script>
  • يضيف كل مسح إلى رابط الوجهة معاملًا موقّعًا qrg_v، فيُربط التحويل برمز QR والمتغير.
  • يحفظ السكربت الرمز في ملف تعريف ارتباط خاص بموقعك لمدة 30 يومًا، فيُحتسب التحويل حتى لو تصفّح الزائر صفحات أخرى أولًا.
  • يُحتسب كل مسح مرة واحدة: إعادة تحميل صفحة الشكر لا تضيف تحويلات.
  • يعمل مع رموز QR التي تعيد التوجيه إلى صفحة http(s).

التصدير

صدّر رموز QR وعمليات المسح والمواقع والنشاط بصيغة CSV من صفحة التصدير.

يعتمد التصدير على جلسة لوحة التحكم وليس على مفتاح API — افتحه وأنت مسجّل الدخول.

التصدير

نصائح وأخطاء شائعة

  • 401 Unauthorized — مفتاح API مفقود أو غير صالح. تحقق من ترويسة X-Api-Key.
  • 403 Forbidden — يفتقد المفتاح الصلاحية المطلوبة (insufficient_scope) أو لا تتضمن خطتك هذه الميزة (api_access_required، bulk_not_available، webhooks_not_available).
  • 404 Not Found — المورد غير موجود أو يتبع مساحة عمل أخرى.
  • 429 Too Many Requests — بلغت الحد الأقصى للطلبات في الدقيقة ضمن خطتك. انتظر عدد الثواني المحدد في ترويسة Retry-After.
  • تعتمد بعض الميزات (مثل الويب هوك) على خطتك. قم بالترقية إذا أعادت نقطة نهاية خطأً يتعلق بميزة غير متاحة.
  • لا توجد عمليات تسليم للويب هوك بعد؟ امسح أحد رموز QR الخاصة بك لإنشاء واحدة.
  • تُعاد محاولة عمليات تسليم الويب هوك الفاشلة تلقائيًا، ويمكنك أيضًا إعادة محاولتها يدويًا من سجل التسليم.
  • يعمل أعضاء الفريق داخل مساحة العمل الخاصة بك، وترتبط المفاتيح والبيانات بمالك مساحة العمل.

روابط مفيدة