الإنشاء المجمّع لرموز QR

curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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
}

null

curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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
}

null

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

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

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

طريقة العمل

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

أرسل صفوفك عبر الإنشاء من JSON أو الإنشاء من ملف CSV. تُرجع الواجهة 202 مع الإنشاء المجمّع وid الخاص به.

استطلع تقدّمه

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

نزّل الأرشيف

عندما تكون قيمة 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.

الترويسات

string

مطلوب

Bearer متبوعة بمفتاح API الخاص بك. راجع المصادقة.

string

application/json لـ الإنشاء من JSON، وmultipart/form-data لـ الإنشاء من ملف CSV.

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

string

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

string

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

string

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

integer

عدد الصفوف.

integer

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

integer

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

integer

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

boolean

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

object | null

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

string | null

مسار تنزيل الأرشيف، بمجرد أن تصبح قيمة status هي completed.

string

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

string

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

string | null

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

string | null

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

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

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

curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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
}

null

الإنشاء من JSON

POST /api/v1/bulk-qr-creations يبدأ إنشاءً مجمّعًا من قائمة صفوف. يُرجع 202 Accepted. يعمل الإنشاء المجمّع في الخلفية.

object[]

مطلوب

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

object

مطلوب

التصميم المطبَّق على كل رمز QR: styles وframeOptions وlogoOptions، وكلها اختيارية. أرسل {} للتصميم الافتراضي. تُرفض الحقول الأخرى. راجع التخصيص.

string

مطلوب

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

string

مطلوب

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

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"
  }'

{
  "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، لكنه يأخذ الصفوف كملف CSV يُرسل بصيغة multipart/form-data. يُرجع 202 Accepted. يجب أن يكون الملف بامتداد .csv وبحجم 1,000,000 بايت على الأكثر. يجب أن يكون صف العناوين name,url بالضبط، يليه حتى 100 صف بيانات. راجع تنسيق CSV.

file

مطلوب

ملف CSV.

string

مطلوب

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

string

مطلوب

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

string

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

curl -X POST "https://getqr.com/api/v1/bulk-qr-creations/csv" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -F "[email protected]" \
  -F 'design={"styles":{"dotsOptions":{"type":"rounded"}}}' \
  -F "idempotencyKey=campaign-2026-08-14"

name,url
Menu,https://example.com/menu
Wine list,example.com/wine

{
  "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 بمجرد جاهزية الأرشيف.

string

مطلوب

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

curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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. إلغاء إنشاء مجمّع فشل بالفعل يُرجعه دون تغيير.

لا يمكن إلغاء إنشاء مجمّع اكتمل: يُرجع الطلب 400. احذف رموز QR الخاصة به واحدًا تلو الآخر عبر رموز QR بدلًا من ذلك.

string

مطلوب

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

curl -X DELETE "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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. التنزيل يُغلق الإنشاء المجمّع، فيتوقف الحصول على الإنشاء المجمّع الحالي عن إرجاعه.

string

مطلوب

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

curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t/download" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-codes.zip

HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="campaign-links-qr-codes.zip"

<binary archive data>

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

الخطأ 422 مع "contains an invalid HTTP(S) URL"

تذكر الرسالة الصف. يجب أن يكون كل رابط عنوان http أو https بنطاق حقيقي، مثل example.com/menu. أصلح الصف وأرسل الطلب مرة أخرى.

422 "CSV headers must be exactly: name,url."

يجب أن يكون الصف الأول من ملف CSV هو name,url، بهذا الترتيب وبأحرف صغيرة، دون أعمدة أخرى.

422 "This idempotencyKey was already used with a different request body."

لا يمكن إعادة استخدام المفاتيح لدفعة مختلفة. أرسل idempotencyKey جديدًا.

409 "The bulk QR archive is not ready for download."

لم يكتمل الإنشاء المجمّع بعد. واصل الاستطلاع حتى تصبح قيمة status هي completed.

400 "Cannot cancel a finished bulk QR creation."

اكتمل الإنشاء المجمّع بالفعل، لذا لا يمكن التراجع عنه.

403 exceeded_limit

مساحة عملك على خطة Single QR، التي لا تتضمن الإنشاء المجمّع. رقِّ الخطة.

حصلت على إنشاء مجمّع أقدم بدلًا من إنشاء جديد

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

API

الإنشاء المجمّع لرموز QR

طريقة العمل

الصفوف

الترويسات

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

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

الإنشاء من JSON

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

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

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

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

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

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

التخصيص

رموز QR

الإنشاء المجمّع في التطبيق

تنسيق CSV

​طريقة العمل

​الصفوف

​الترويسات

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

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

​الإنشاء من JSON

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

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

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

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

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

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

التخصيص

رموز QR

الإنشاء المجمّع في التطبيق

تنسيق CSV

طريقة العمل

الصفوف

الترويسات

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

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

الإنشاء من JSON

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

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

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

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

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

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