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

> أنشئ حتى 100 رمز QR دفعة واحدة ونزّلها كأرشيف ZIP.

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

يحوّل الإنشاء المجمّع قائمة من الأسماء والروابط إلى رموز QR لمواقع ويب بتصميم مشترك واحد. يعمل في الخلفية: ابدأه، واستطلع تقدّمه، ثم نزّل أرشيف ZIP.

| الطريقة | المسار | الوصف |
| - | - | - |
| `GET` | `/api/v1/bulk-qr-creations` | [الحصول على الإنشاء المجمّع الحالي](#الحصول-على-الإنشاء-المجمّع-الحالي) |
| `POST` | `/api/v1/bulk-qr-creations` | [الإنشاء من JSON](#الإنشاء-من-json) |
| `POST` | `/api/v1/bulk-qr-creations/csv` | [الإنشاء من ملف CSV](#الإنشاء-من-ملف-csv) |
| `GET` | `/api/v1/bulk-qr-creations/{id}` | [الحصول على إنشاء مجمّع](#الحصول-على-إنشاء-مجمّع) |
| `DELETE` | `/api/v1/bulk-qr-creations/{id}` | [إلغاء إنشاء مجمّع](#إلغاء-إنشاء-مجمّع) |
| `GET` | `/api/v1/bulk-qr-creations/{id}/download` | [تنزيل الأرشيف](#تنزيل-الأرشيف) |

## طريقة العمل

**1. ابدأ الإنشاء المجمّع**

أرسل صفوفك عبر [الإنشاء من JSON](#الإنشاء-من-json) أو [الإنشاء من ملف CSV](#الإنشاء-من-ملف-csv). تُرجع الواجهة `202` مع الإنشاء المجمّع و`id` الخاص به.

**2. استطلع تقدّمه**

استدعِ [الحصول على إنشاء مجمّع](#الحصول-على-إنشاء-مجمّع) كل بضع ثوانٍ حتى تصبح قيمة `status` هي `completed` أو `failed`.

**3. نزّل الأرشيف**

عندما تكون قيمة `status` هي `completed`، استدعِ [تنزيل الأرشيف](#تنزيل-الأرشيف) للحصول على ملف ZIP يضم صور رموز QR.

* **الحد.** حتى 100 صف لكل إنشاء مجمّع.
* **واحد في كل مرة.** لا يعمل إلا إنشاء مجمّع واحد لكل مساحة عمل. بدء إنشاء آخر أثناء تشغيل أحدها يُرجع الإنشاء الجاري.
* **عدم التكرار (Idempotency).** يحتاج كل طلب إلى `idempotencyKey`. تكرار الطلب بالمفتاح نفسه والجسم نفسه يُرجع الإنشاء المجمّع الذي بدأ بالفعل. المفتاح نفسه مع جسم مختلف يُرجع `422`.
* **الصفوف.** يحتاج كل صف إلى `name` و`url`. راجع [الصفوف](#الصفوف).
* **الخطة.** الإنشاء المجمّع غير متاح في خطة Single QR: يُرجع الطلب `403 exceeded_limit`.

## الصفوف

* **الاسم.** يصبح عنوان رمز QR. تُزال المسافات من طرفيه ويُقتطع إلى 40 حرفًا. تحصل الأسماء المكررة (بغض النظر عن حالة الأحرف) على رقم: `Menu`، `Menu 2`، `Menu 3`.
* **الرابط.** يصبح الوجهة. يجب أن يكون عنوان `http` أو `https` بنطاق حقيقي، مثل `example.com/menu`، ودون مسافات. الرابط الذي لا مخطط له يُضاف إليه `https://`.
* **الصفوف الفارغة.** تُتخطى الصفوف التي لا تحتوي على اسم ولا رابط. ويُرفض الصف الذي يحتوي على أحدهما فقط.

كل رمز QR هو رمز QR من نوع `website` على رابط قصير. راجع [أنواع QR](https://docs.getqr.com/ar/api/guides/qr-types.md).

## الترويسات

**Authorization** `string` *required*

`Bearer` متبوعة بمفتاح API الخاص بك. راجع [المصادقة](https://docs.getqr.com/ar/api/authentication.md).

**Content-Type** `string`

`application/json` لـ [الإنشاء من JSON](#الإنشاء-من-json)، و`multipart/form-data` لـ [الإنشاء من ملف CSV](#الإنشاء-من-ملف-csv).

## كائن الإنشاء المجمّع

**id** `string`

معرّف الإنشاء المجمّع، مثل `cm2k7x9qb0003ax8eb4f6gh2t`.

**status** `string`

`queued` أو `processing` أو `packaging` أو `completed`. يمر الإنشاء المجمّع الفاشل أو الملغى عبر `rollingBack` إلى `failed`.

**sourceFilename** `string`

اسم الملف المصدر.

**totalCount** `integer`

عدد الصفوف.

**createdCount** `integer`

رموز QR المُنشأة حتى الآن.

**renderedCount** `integer`

صور رموز QR المُعالجة حتى الآن.

**percent** `integer`

التقدّم الإجمالي، من 0 إلى 100. يصل الإنشاء حتى 40، والمعالجة حتى 90، والتحزيم 95، و`completed` يساوي 100.

**stalled** `boolean`

`true` عندما لا يحرز إنشاء مجمّع جارٍ أي تقدّم لمدة دقيقتين. واصل الاستطلاع: يعيد [الحصول على إنشاء مجمّع](#الحصول-على-إنشاء-مجمّع) تشغيل الإنشاء المجمّع المتوقف.

**error** `object | null`

عندما تكون قيمة `status` هي `failed`: `code` و`message`. رمز الإنشاء المجمّع الملغى هو `cancelled_by_user`. يُتراجع عن الإنشاء المجمّع الفاشل، فلا يُحتفظ بأي من رموز QR الخاصة به.

**downloadUrl** `string | null`

مسار [تنزيل الأرشيف](#تنزيل-الأرشيف)، بمجرد أن تصبح قيمة `status` هي `completed`.

**createdAt** `string`

تاريخ البدء، بصيغة ISO 8601.

**updatedAt** `string`

تاريخ آخر تحديث، بصيغة ISO 8601.

**completedAt** `string | null`

تاريخ الاكتمال، بصيغة ISO 8601.

**failedAt** `string | null`

تاريخ الفشل، بصيغة ISO 8601.

## الحصول على الإنشاء المجمّع الحالي

`GET /api/v1/bulk-qr-creations`

يُرجع الإنشاء المجمّع الذي لا يزال قيد التشغيل في مساحة عملك. عند عدم وجود إنشاء جارٍ، يُرجع آخر إنشاء منتهٍ (`completed` أو `failed`) حتى يُغلق: يحدث ذلك بتنزيل أرشيفه أو إغلاقه في لوحة التحكم. وإلا يُرجع `null`. استخدمه لاستئناف التتبع بعد إعادة التشغيل.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "processing",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 18,
  "renderedCount": 12,
  "percent": 26,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:20.000Z",
  "completedAt": null,
  "failedAt": null
}
```

```json 200 (nothing to resume) theme={null}
null
```

## الإنشاء من JSON

`POST /api/v1/bulk-qr-creations`

يبدأ إنشاءً مجمّعًا من قائمة صفوف. يُرجع `202 Accepted`. يعمل الإنشاء المجمّع في الخلفية.

**rows** `object[]` *required*

رموز QR المراد إنشاؤها، حتى 100. كل صف هو `{ "name": "...", "url": "..." }` ولا يأخذ حقولًا أخرى. راجع [الصفوف](#الصفوف).

**design** `object` *required*

التصميم المطبَّق على كل رمز QR: `styles` و`frameOptions` و`logoOptions`، وكلها اختيارية. أرسل `{}` للتصميم الافتراضي. تُرفض الحقول الأخرى. راجع [التخصيص](https://docs.getqr.com/ar/api/guides/customization.md).

**sourceFilename** `string` *required*

الاسم المعروض في لوحة التحكم والمستخدم للأرشيف، من 1 إلى 255 حرفًا.

**idempotencyKey** `string` *required*

مفتاحك الخاص لهذا الإنشاء المجمّع، من 8 إلى 100 حرف.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "name": "Menu", "url": "https://example.com/menu" },
      { "name": "Wine list", "url": "example.com/wine" }
    ],
    "design": { "styles": { "dotsOptions": { "type": "rounded" } } },
    "sourceFilename": "campaign-links.csv",
    "idempotencyKey": "campaign-2026-08-14"
  }'
```

```json 202 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "queued",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 2,
  "createdCount": 0,
  "renderedCount": 0,
  "percent": 0,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:00.000Z",
  "completedAt": null,
  "failedAt": null
}
```

## الإنشاء من ملف CSV

`POST /api/v1/bulk-qr-creations/csv`

مثل [الإنشاء من JSON](#الإنشاء-من-json)، لكنه يأخذ الصفوف كملف CSV يُرسل بصيغة `multipart/form-data`. يُرجع `202 Accepted`.

يجب أن يكون الملف بامتداد `.csv` وبحجم 1,000,000 بايت على الأكثر. يجب أن يكون صف العناوين `name,url` بالضبط، يليه حتى 100 صف بيانات. راجع [تنسيق CSV](https://docs.getqr.com/ar/bulk/csv-format.md).

**file** `file` *required*

ملف CSV.

**design** `string` *required*

كائن التصميم، مُسلسَلًا كـ JSON، مثل `{"styles":{"dotsOptions":{"type":"rounded"}}}`. أرسل `{}` للتصميم الافتراضي.

**idempotencyKey** `string` *required*

مفتاحك الخاص لهذا الإنشاء المجمّع، من 8 إلى 100 حرف.

**sourceFilename** `string`

الاسم المعروض في لوحة التحكم والمستخدم للأرشيف، حتى 255 حرفًا. القيمة الافتراضية اسم الملف المرفوع.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/bulk-qr-creations/csv" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -F "file=@campaign-links.csv" \
  -F 'design={"styles":{"dotsOptions":{"type":"rounded"}}}' \
  -F "idempotencyKey=campaign-2026-08-14"
```

```csv campaign-links.csv theme={null}
name,url
Menu,https://example.com/menu
Wine list,example.com/wine
```

```json 202 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "queued",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 2,
  "createdCount": 0,
  "renderedCount": 0,
  "percent": 0,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:00.000Z",
  "completedAt": null,
  "failedAt": null
}
```

## الحصول على إنشاء مجمّع

`GET /api/v1/bulk-qr-creations/{id}`

يُرجع حالة الإنشاء المجمّع وتقدّمه. استطلعه ما دامت قيمة `status` هي `queued` أو `processing` أو `packaging`. يظهر `downloadUrl` بمجرد جاهزية الأرشيف.

**id** `string` *required*

معرّف الإنشاء المجمّع. خذه من استجابة الإنشاء أو استجابة الإنشاء المجمّع الحالي.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "completed",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 50,
  "renderedCount": 50,
  "percent": 100,
  "stalled": false,
  "error": null,
  "downloadUrl": "/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t/download",
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:02:10.000Z",
  "completedAt": "2026-08-14T08:02:10.000Z",
  "failedAt": null
}
```

## إلغاء إنشاء مجمّع

`DELETE /api/v1/bulk-qr-creations/{id}`

يوقف إنشاءً مجمّعًا جاريًا ويحذف رموز QR التي أنشأها بالفعل. يجري التراجع أثناء الطلب، لذا تحتوي الاستجابة عادةً على `status` بالقيمة `failed` و`error.code` بالقيمة `cancelled_by_user`. إلغاء إنشاء مجمّع فشل بالفعل يُرجعه دون تغيير.

> [!WARNING]
>
> لا يمكن إلغاء إنشاء مجمّع اكتمل: يُرجع الطلب `400`. احذف رموز QR الخاصة به واحدًا تلو الآخر عبر [رموز QR](https://docs.getqr.com/ar/api/endpoints/qr-codes.md) بدلًا من ذلك.

**id** `string` *required*

معرّف الإنشاء المجمّع.

```bash cURL theme={null}
curl -X DELETE "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "failed",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 18,
  "renderedCount": 12,
  "percent": 26,
  "stalled": false,
  "error": {
    "code": "cancelled_by_user",
    "message": "Bulk QR creation was cancelled."
  },
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:40.000Z",
  "completedAt": null,
  "failedAt": "2026-08-14T08:00:40.000Z"
}
```

## تنزيل الأرشيف

`GET /api/v1/bulk-qr-creations/{id}/download`

يُرجع أرشيف ZIP يحتوي على صورة JPEG واحدة بدقة 1024 px لكل رمز QR، مسمّاة باسم صفها: `001-Menu.jpg` و`002-Wine list.jpg` وهكذا. يُسمّى الأرشيف باسم `sourceFilename`. متاح بمجرد أن تصبح قيمة `status` هي `completed`. التنزيل يُغلق الإنشاء المجمّع، فيتوقف [الحصول على الإنشاء المجمّع الحالي](#الحصول-على-الإنشاء-المجمّع-الحالي) عن إرجاعه.

**id** `string` *required*

معرّف الإنشاء المجمّع.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t/download" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-codes.zip
```

```http 200 theme={null}
HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="campaign-links-qr-codes.zip"

<binary archive data>
```

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

> [accordion] الخطأ 422 مع "contains an invalid HTTP(S) URL"
>
> تذكر الرسالة الصف. يجب أن يكون كل رابط عنوان `http` أو `https` بنطاق حقيقي، مثل `example.com/menu`. أصلح الصف وأرسل الطلب مرة أخرى.

> [accordion] 422 "CSV headers must be exactly: name,url."
>
> يجب أن يكون الصف الأول من ملف CSV هو `name,url`، بهذا الترتيب وبأحرف صغيرة، دون أعمدة أخرى.

> [accordion] 422 "This idempotencyKey was already used with a different request body."
>
> لا يمكن إعادة استخدام المفاتيح لدفعة مختلفة. أرسل `idempotencyKey` جديدًا.

> [accordion] 409 "The bulk QR archive is not ready for download."
>
> لم يكتمل الإنشاء المجمّع بعد. واصل الاستطلاع حتى تصبح قيمة `status` هي `completed`.

> [accordion] 400 "Cannot cancel a finished bulk QR creation."
>
> اكتمل الإنشاء المجمّع بالفعل، لذا لا يمكن التراجع عنه.

> [accordion] 403 exceeded\_limit
>
> مساحة عملك على خطة Single QR، التي لا تتضمن الإنشاء المجمّع. رقِّ الخطة.

> [accordion] حصلت على إنشاء مجمّع أقدم بدلًا من إنشاء جديد
>
> لا يزال إنشاء مجمّع آخر قيد التشغيل في مساحة عملك، أو أنك أعدت استخدام `idempotencyKey`. انتظر حتى ينتهي، أو استخدم مفتاحًا جديدًا.

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

> [card] [التخصيص](https://docs.getqr.com/ar/api/guides/customization.md)

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

> [card] [الإنشاء المجمّع في التطبيق](https://docs.getqr.com/ar/bulk/overview.md)

> [card] [تنسيق CSV](https://docs.getqr.com/ar/bulk/csv-format.md)


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