> ## 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.

# مقدمة عن API

> أدِر رموز QR والقوالب والتحليلات والتقارير من شيفرتك الخاصة.

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

GetQR API هي واجهة REST لما تفعله في لوحة التحكم: أنشئ رموز QR وحدّثها، ونزّل صورها، واقرأ تحليلات المسح، وصدّر التقارير. صادِق باستخدام مفتاح API الخاص بحسابك، واستدعِ نقاط النهاية ذات الإصدارات ضمن `/api/v1`.

## ما يمكنك فعله

> [card] [رموز QR](https://docs.getqr.com/ar/api/endpoints/qr-codes.md)
>
> أنشئ رموز QR واعرضها وحدّثها وأوقفها مؤقتًا وكرّرها واحذفها ونزّلها.

> [card] [التحليلات](https://docs.getqr.com/ar/api/endpoints/analytics.md)
>
> إجماليات المسح وتصنيفاته لرمز QR واحد أو لمساحة العمل بالكامل.

> [card] [التقارير](https://docs.getqr.com/ar/api/endpoints/reports.md)
>
> صدّر تقريرًا لمرة واحدة أو جدوِل رسائل بريد إلكتروني دورية بالتقارير.

> [card] [القوالب](https://docs.getqr.com/ar/api/endpoints/templates.md)
>
> احفظ التصاميم وطبّقها على رموز QR الجديدة.

> [card] [الإنشاء المجمّع لرموز QR](https://docs.getqr.com/ar/api/endpoints/bulk-qr-creations.md)
>
> أنشئ حتى 100 رمز QR دفعة واحدة من JSON أو من ملف CSV.

> [card] [الملفات](https://docs.getqr.com/ar/api/endpoints/files.md)
>
> ارفع ملفات PDF والصور ومقاطع الفيديو والشعارات لرموز QR الخاصة بك.

> [card] [الحالة](https://docs.getqr.com/ar/api/endpoints/health.md)
>
> تحقّق من أن الواجهة تعمل. لا حاجة إلى مفتاح API.

## الأدلة

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

> [card] [التخصيص](https://docs.getqr.com/ar/api/guides/customization.md)
>
> أنماط النقاط والزوايا والألوان والإطارات والشعارات.

> [card] [قواعد الوصول](https://docs.getqr.com/ar/api/guides/access-rules.md)
>
> الجداول الزمنية وحدود المسح وكلمات المرور والإيقاف المؤقت والحذف.

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

توجد جميع نقاط النهاية ضمن عنوان URL أساسي واحد:

```text theme={null}
https://getqr.com/api/v1
```

## الإصدارات

إصدار الواجهة جزء من المسار: توجد كل نقطة نهاية ضمن `/api/v1/`.

* تصدر التغييرات غير المتوافقة مع الإصدارات السابقة ضمن بادئة إصدار جديدة مثل `/api/v2/`، ويستمر `/api/v1/` في العمل.
* قد تظهر التغييرات الإضافية، مثل الحقول الاختيارية الجديدة أو نقاط النهاية الجديدة، ضمن v1. تجاهل حقول الاستجابة التي لا تتعرّف عليها شيفرتك.

## البدء السريع

**1. احصل على مفتاح API**

أنشئ مفتاحك أو اعرضه في إعدادات حسابك. راجع [المصادقة](https://docs.getqr.com/ar/api/authentication.md).

**2. تحقّق من إمكانية الوصول إلى الواجهة**

```bash theme={null}
curl https://getqr.com/api/v1/health
```

الاستجابة هي `{ "status": "ok", "version": "v1" }`.

**3. أنشئ أول رمز QR**

```bash theme={null}
curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-qr-0001" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page"
  }'
```

تُرجع الواجهة `201` مع رمز QR الجديد، بما في ذلك `id` و`shortLink`.

**4. نزّل الصورة**

```bash theme={null}
curl "https://getqr.com/api/v1/qrs/{qrId}/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png
```

## الطلبات والاستجابات

* **الصيغة.** أرسل أجسام الطلبات بصيغة JSON مع `Content-Type: application/json`. الاستثناء هو رفع ملف CSV في [الإنشاء المجمّع](https://docs.getqr.com/ar/api/endpoints/bulk-qr-creations.md)، الذي يستخدم `multipart/form-data`.
* **الاستجابات.** الاستجابات بصيغة JSON. أما التنزيلات، مثل صور QR وأرشيفات ZIP المجمّعة، فتُرجع الملف نفسه.
* **التواريخ.** التواريخ سلاسل ISO 8601 بتوقيت UTC، مثل `2026-08-01T10:00:00.000Z`.
* **معاملات الاستعلام.** تأخذ المعاملات المنطقية السلسلتين `true` أو `false`.
* **التحديثات الجزئية.** لا تغيّر نقاط النهاية `PATCH` إلا الحقول التي ترسلها.
* **البيانات السرية.** لا تتضمن الاستجابات أبدًا كلمات المرور أو المعرّفات الداخلية. لا يُبلغ رمز QR المحمي بكلمة مرور إلا عن `passwordProtected: true`.
* **مساحة العمل.** يُنفَّذ كل طلب في مساحة العمل التي ينتمي إليها مفتاح API الخاص بك. لا تمرّر معرّف مساحة العمل. راجع [الوصول والأدوار](https://docs.getqr.com/ar/api/authentication.md#الوصول-والأدوار).
* **الأخطاء.** تُرجع الطلبات الفاشلة كائن `error` يحتوي على `code` ثابت. راجع [الأخطاء](https://docs.getqr.com/ar/api/errors.md).

## ترقيم الصفحات

تأخذ نقاط نهاية القوائم (رموز QR والقوالب والتقارير المجدولة) معاملَي استعلام:

| المعامل | الوصف |
| - | - |
| `page` | الصفحة التي تُعاد. القيمة الافتراضية `1`. |
| `pageSize` | النتائج في كل صفحة، حتى `100`. القيمة الافتراضية `100`. |

وتُرجع مصفوفة `data` وكائن `pagination`:

```json theme={null}
{
  "data": [ … ],
  "pagination": { "page": 1, "pageSize": 50, "total": 128, "hasMore": true }
}
```

| الحقل | الوصف |
| - | - |
| `page` | الصفحة التي تلقيتها. |
| `pageSize` | حجم الصفحة الذي تلقيته. |
| `total` | عدد النتائج في جميع الصفحات. |
| `hasMore` | `true` ما دامت هناك صفحة أخرى. |

اطلب الصفحة التالية ما دام `hasMore` يساوي `true`. تُرجع قيمة `pageSize` أكبر من `100` الخطأ [`422`](https://docs.getqr.com/ar/api/errors#أخطاء-التحقق).

## عدم التكرار (Idempotency)

قد يتركك خطأ في الشبكة غير متأكد مما إذا كان الطلب قد نُفّذ. لإعادة محاولة [إنشاء رمز QR](https://docs.getqr.com/ar/api/endpoints/qr-codes.md#إنشاء-رمز-qr) بأمان، أرسل الترويسة `Idempotency-Key` بقيمة فريدة من اختيارك:

```bash theme={null}
-H "Idempotency-Key: order-4821-qr"
```

* تكرار الطلب بالمفتاح نفسه خلال 24 ساعة يُرجع الاستجابة الأصلية بدلًا من إنشاء رمز QR ثانٍ.
* تكون ترويسة الاستجابة `x-idempotent-replay` بالقيمة `true` للاستجابة المُعادة و`false` للاستجابة الجديدة.
* إذا كان الطلب الأول بهذا المفتاح لا يزال قيد التنفيذ، تُرجع الواجهة `409 conflict`. أعد المحاولة بعد انتهائه.
* إعادة استخدام مفتاح مع جسم طلب مختلف تُرجع `422 unprocessable_entity`.
* دون الترويسة، يُعامَل جسم الطلب المطابق المُرسَل خلال 30 ثانية على أنه مكرر.

أما عمليات الإنشاء المجمّع فتأخذ بدلًا من ذلك الحقل `idempotencyKey` في جسم الطلب. راجع [الإنشاء المجمّع لرموز QR](https://docs.getqr.com/ar/api/endpoints/bulk-qr-creations.md).

## حدود الطلبات

يمكن لكل مفتاح API إرسال ما يصل إلى 600 طلب في الدقيقة. راجع [حدود الطلبات](https://docs.getqr.com/ar/api/rate-limits.md).

## قريبًا

حِزم جاهزة للطباعة مُخطط لها في إصدار لاحق.

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

> [card] [المصادقة](https://docs.getqr.com/ar/api/authentication.md)

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


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