> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# قواعد الوصول

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

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

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

## قبل أن تبدأ

* **الدور.** يتطلب ضبط القواعد والإيقاف المؤقت وإعادة التفعيل والحذف صلاحية كتابة على رموز QR في مساحة العمل. راجع [المصادقة](https://docs.getqr.com/ar/api/authentication.md).
* **الاشتراك.** يتطلب كل طلب API، بما في ذلك هذه الطلبات، اشتراكًا نشطًا لمالك مساحة العمل.

## كائن الوصول

أرسل كائن `access` عند [إنشاء](https://docs.getqr.com/ar/api/endpoints/qr-codes.md#إنشاء-رمز-qr) رمز QR أو [تحديثه](https://docs.getqr.com/ar/api/endpoints/qr-codes.md#تحديث-رمز-qr):

```text theme={null}
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` الجزئي أبدًا تعيين القواعد التي لم تذكرها.

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

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

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

```bash theme={null}
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 نشطًا فورًا ويزيل تاريخ الانتهاء:

```json theme={null}
{
  "access": { "activeAt": null, "pauseAt": null }
}
```

## حد المسح

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

```json theme={null}
{
  "access": { "scanLimit": 500 }
}
```

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

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

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

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

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

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

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

```json theme={null}
{ "access": { "password": "hunter2" } }
```

**2. أوقف الحماية**

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

```json theme={null}
{ "access": { "passwordProtected": false } }
```

**3. أعد تفعيل الحماية**

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

```json theme={null}
{ "access": { "passwordProtected": true } }
```

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

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

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

| الطريقة | المسار | الوصف |
| - | - | - |
| `POST` | `/api/v1/qrs/{qrId}/pause` | [أوقف رمز QR مؤقتًا الآن](https://docs.getqr.com/ar/api/endpoints/qr-codes.md#إيقاف-رمز-qr-مؤقتًا). تعرض عمليات المسح صفحة الإيقاف المؤقت حتى تعيد تفعيله. |
| `POST` | `/api/v1/qrs/{qrId}/activate` | [أعد تفعيل رمز QR موقوف مؤقتًا](https://docs.getqr.com/ar/api/endpoints/qr-codes.md#إعادة-تفعيل-رمز-qr). يظل أي جدول زمني أو حد مسح ساريًا. |
| `DELETE` | `/api/v1/qrs/{qrId}` | [احذف رمز QR](https://docs.getqr.com/ar/api/endpoints/qr-codes.md#حذف-رمز-qr) ورابطه القصير نهائيًا. |

لا يأخذ الإيقاف المؤقت والتفعيل جسم طلب، ويُرجعان [رمز QR](https://docs.getqr.com/ar/api/endpoints/qr-codes.md#كائن-رمز-qr) المحدَّث:

```bash theme={null}
curl -X POST "https://getqr.com/api/v1/qrs/qr_abc123/pause" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json theme={null}
{
  "id": "qr_abc123",
  "archived": true,
  "…": "…"
}
```

يمكنك أيضًا ضبط حالة الإيقاف المؤقت باستخدام `PUT /api/v1/qrs/{qrId}` و`{ "archived": true }`، أو باستخدام `archived` في طلب `PATCH`. راجع [ضبط حالة الإيقاف المؤقت](https://docs.getqr.com/ar/api/endpoints/qr-codes.md#ضبط-حالة-الإيقاف-المؤقت).

يزيل الحذف رمز QR ورابطه القصير معًا:

```json theme={null}
{ "id": "qr_abc123", "deleted": true }
```

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

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

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

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

> [accordion] الخطأ 422 عند ضبط قاعدة ضمن link
>
> أرسل القاعدة ضمن `access`، لا `link`.

> [accordion] الخطأ 422 عند تفعيل حماية كلمة المرور
>
> لا توجد لرمز QR كلمة مرور بعد. أرسل `password` بدلًا من `passwordProtected: true`.

> [accordion] لا يزال رمز QR يعرض صفحة الإيقاف المؤقت بعد إعادة التفعيل
>
> لا يزال جدول زمني أو حد مسح ساريًا. تحقّق من `access.activeAt` و`access.pauseAt` و`access.scanLimit` في [رمز QR](https://docs.getqr.com/ar/api/endpoints/qr-codes.md#الحصول-على-رمز-qr)، وقارن `scans` بالحد.

> [accordion] أحتاج إلى أن تنتهي صلاحية الرابط
>
> `link.expiresAt` غير متاح في هذه الواجهة. استخدم `access.pauseAt` بدلًا منه.

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

> [card] [رموز QR](https://docs.getqr.com/ar/api/endpoints/qr-codes.md)

> [card] [بيانات رمز QR حسب النوع](https://docs.getqr.com/ar/api/guides/qr-types.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.