قواعد الوصول

GetQR API في مرحلة تجريبية (beta) ومتاحة لمساحات عمل مختارة. قد تتغير التفاصيل قبل الإصدار العام.

تحكّم في متى يعمل رمز QR، وكم مرة يمكن مسحه، وما إذا كان يطلب كلمة مرور، وما إذا كان موقوفًا مؤقتًا أو محذوفًا.

قبل أن تبدأ

الدور. يتطلب ضبط القواعد والإيقاف المؤقت وإعادة التفعيل والحذف صلاحية كتابة على رموز QR في مساحة العمل. راجع المصادقة.
الاشتراك. يتطلب كل طلب API، بما في ذلك هذه الطلبات، اشتراكًا نشطًا لمالك مساحة العمل.

كائن الوصول

أرسل كائن access عند إنشاء رمز QR أو تحديثه:

POST  /api/v1/qrs
PATCH /api/v1/qrs/{qrId}

الحقل	النوع	الوصف
`activeAt`	string (ISO 8601) \| null	البداية المجدولة. قبل هذه اللحظة، تعرض عمليات المسح صفحة الإيقاف المؤقت بدلًا من الوجهة. `null` تعني التفعيل فورًا.
`pauseAt`	string (ISO 8601) \| null	النهاية المجدولة. عند هذه اللحظة وبعدها، تعرض عمليات المسح صفحة الإيقاف المؤقت. `null` تعني عدم وجود تاريخ انتهاء.
`scanLimit`	integer \| null	الحد الأقصى لعدد عمليات المسح طوال عمر رمز QR. بعد تجاوزه، تعرض عمليات المسح صفحة الإيقاف المؤقت. `null` تعني بلا حد.
`password`	string \| null	كلمة المرور التي يجب على الزوار إدخالها قبل إعادة توجيههم. إرسالها يفعّل الحماية أيضًا.
`passwordProtected`	boolean	ما إذا كان رمز QR يطلب كلمة مرور. `false` يوقف الحماية لكنه يحتفظ بكلمة المرور المحفوظة. `true` يعيد تفعيلها.

تبقى الحقول التي لا ترسلها دون تغيير. أرسل null لمسح قاعدة. لا يعيد كائن access الجزئي أبدًا تعيين القواعد التي لم تذكرها.

تنتمي قواعد الوصول إلى access. إرسال activeAt أو pauseAt أو scanLimit أو password أو passwordProtected ضمن link يُرجع 422.

جدولة البداية والنهاية

activeAt وpauseAt مستقلان: اضبط أحدهما أو كليهما. يأخذ كلاهما تاريخًا ووقتًا بصيغة ISO 8601، مع Z أو فرق توقيت عن UTC.

curl -X PATCH "https://getqr.com/api/v1/qrs/qr_abc123" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access": {
      "activeAt": "2026-08-01T09:00:00Z",
      "pauseAt": "2026-08-31T23:59:59Z"
    }
  }'

أرسل null لمسح الجدول الزمني. يجعل هذا رمز QR نشطًا فورًا ويزيل تاريخ الانتهاء:

{
  "access": { "activeAt": null, "pauseAt": null }
}

حد المسح

حدّد العدد الإجمالي لعمليات المسح. بعد بلوغه، يتوقف رمز QR عن العمل:

{
  "access": { "scanLimit": 500 }
}

يعمل عدّاد المسح طوال العمر دائمًا، سواء ضُبط حد أم لا. وهذا يجعل نتيجة تغيير الحد متوقعة:

رفع الحد يتيح بالضبط (الحد الجديد ناقص إجمالي عمليات المسح) من عمليات المسح الإضافية.
خفض الحد إلى ما دون الإجمالي الحالي يحظر رمز QR فورًا.
ضبط حد لاحقًا يحتسب عمليات المسح التي جرت حين لم يكن هناك حد.

يجب أن تكون scanLimit عددًا صحيحًا موجبًا، حتى 2147483647. أرسل null لعدم وضع حد.

حماية كلمة المرور

اضبط كلمة المرور عبر كائن access نفسه. تُحفظ كلمة المرور عند إيقاف الحماية، فيمكنك إعادة تفعيلها دون إرسالها مرة أخرى.

اضبط كلمة المرور أو غيّرها

يفعّل هذا الحماية أيضًا.

{ "access": { "password": "hunter2" } }

أوقف الحماية

تبقى كلمة المرور المحفوظة.

{ "access": { "passwordProtected": false } }

أعد تفعيل الحماية

لا حاجة إلى إعادة إرسال كلمة المرور. يعمل هذا فقط إذا سبق ضبط كلمة مرور، وإلا يحصل الطلب على 422.

{ "access": { "passwordProtected": true } }

عند الإنشاء. أرسل password لتفعيل الحماية. لا تأثير لـ passwordProtected وحده ما لم توجد كلمة مرور.
إزالة كلمة المرور. أرسل "password": null. تتوقف الحماية أيضًا.
القراءة. لا تُرجع الاستجابات كلمة المرور أبدًا، بل access.passwordProtected فقط.

الإيقاف المؤقت وإعادة التفعيل والحذف

الإيقاف المؤقت وإعادة التفعيل نقطتا نهاية منفصلتان وليسا حقلين في access، لأنهما يسريان فورًا لا وفق جدول زمني.

الطريقة	المسار	الوصف
`POST`	`/api/v1/qrs/{qrId}/pause`	أوقف رمز QR مؤقتًا الآن. تعرض عمليات المسح صفحة الإيقاف المؤقت حتى تعيد تفعيله.
`POST`	`/api/v1/qrs/{qrId}/activate`	أعد تفعيل رمز QR موقوف مؤقتًا. يظل أي جدول زمني أو حد مسح ساريًا.
`DELETE`	`/api/v1/qrs/{qrId}`	احذف رمز QR ورابطه القصير نهائيًا.

لا يأخذ الإيقاف المؤقت والتفعيل جسم طلب، ويُرجعان رمز QR المحدَّث:

curl -X POST "https://getqr.com/api/v1/qrs/qr_abc123/pause" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "qr_abc123",
  "archived": true,
  "…": "…"
}

يمكنك أيضًا ضبط حالة الإيقاف المؤقت باستخدام PUT /api/v1/qrs/{qrId} و{ "archived": true }، أو باستخدام archived في طلب PATCH. راجع ضبط حالة الإيقاف المؤقت. يزيل الحذف رمز QR ورابطه القصير معًا:

{ "id": "qr_abc123", "deleted": true }

لا يمكن التراجع عن الحذف. يتوقف الرابط القصير عن العمل، فتتوقف الرموز المطبوعة. أوقف رمز QR مؤقتًا بدلًا من ذلك إذا كنت قد تحتاج إليه مجددًا.

متى تسري التغييرات

المسح التالي. تُفحص القواعد عند مسح الرمز، لذا يسري التغيير من المسح التالي، لا بأثر رجعي.
صفحة الإيقاف المؤقت. يعرض رمز QR المحظور بسبب جدول زمني أو حد مسح أو إيقاف مؤقت صفحةَ الإيقاف المؤقت. لا تُعاد توجيه عملية المسح.
كلمة المرور. يحتفظ الزوار الذين أدخلوا كلمة المرور بالفعل بالوصول حتى تتغير كلمة المرور، أو حتى تُوقف الحماية ثم تُفعَّل مجددًا.
الساعة. تستخدم الجداول الزمنية ساعة الخادم بتوقيت UTC، لا التوقيت المحلي للزائر.
القواعد تجتمع. لا يعمل رمز QR إلا إذا لم يكن موقوفًا مؤقتًا، وكان ضمن جدوله الزمني، ودون حد المسح.

المشكلات الشائعة

الخطأ 422 عند ضبط قاعدة ضمن link

أرسل القاعدة ضمن access، لا link.

الخطأ 422 عند تفعيل حماية كلمة المرور

لا توجد لرمز QR كلمة مرور بعد. أرسل password بدلًا من passwordProtected: true.

لا يزال رمز QR يعرض صفحة الإيقاف المؤقت بعد إعادة التفعيل

لا يزال جدول زمني أو حد مسح ساريًا. تحقّق من access.activeAt وaccess.pauseAt وaccess.scanLimit في رمز QR، وقارن scans بالحد.

أحتاج إلى أن تنتهي صلاحية الرابط

link.expiresAt غير متاح في هذه الواجهة. استخدم access.pauseAt بدلًا منه.

API

قواعد الوصول

قبل أن تبدأ

كائن الوصول

جدولة البداية والنهاية

حد المسح

حماية كلمة المرور

الإيقاف المؤقت وإعادة التفعيل والحذف

متى تسري التغييرات

المشكلات الشائعة

الخطوات التالية

رموز QR

بيانات رمز QR حسب النوع

​قبل أن تبدأ

​كائن الوصول

​جدولة البداية والنهاية

​حد المسح

​حماية كلمة المرور

​الإيقاف المؤقت وإعادة التفعيل والحذف

​متى تسري التغييرات

​المشكلات الشائعة

​الخطوات التالية

رموز QR

بيانات رمز QR حسب النوع

قبل أن تبدأ

كائن الوصول

جدولة البداية والنهاية

حد المسح

حماية كلمة المرور

الإيقاف المؤقت وإعادة التفعيل والحذف

متى تسري التغييرات

المشكلات الشائعة

الخطوات التالية