> ## 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 قابلة لإعادة الاستخدام وطبّقها على رموز QR الجديدة.

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

يحفظ القالب تصميمًا قابلًا لإعادة الاستخدام: `styles` و`frameOptions` و`logoOptions`. لا يحمل أبدًا محتوى أو رابطًا. القوالب مشتركة بين جميع أعضاء مساحة العمل.

| الطريقة | المسار | الوصف |
| - | - | - |
| `GET` | `/api/v1/templates` | [عرض قائمة القوالب](#عرض-قائمة-القوالب) |
| `POST` | `/api/v1/templates` | [إنشاء قالب](#إنشاء-قالب) |
| `GET` | `/api/v1/templates/{templateId}` | [الحصول على قالب](#الحصول-على-قالب) |
| `PATCH` | `/api/v1/templates/{templateId}` | [تحديث قالب](#تحديث-قالب) |
| `DELETE` | `/api/v1/templates/{templateId}` | [حذف قالب](#حذف-قالب) |
| `POST` | `/api/v1/templates/{templateId}/duplicate` | [تكرار قالب](#تكرار-قالب) |

## تطبيق قالب

مرّر `templateId` عند [إنشاء رمز QR](https://docs.getqr.com/ar/api/endpoints/qr-codes.md). يُطبَّق تصميم القالب على رمز QR الجديد. ويُدمج فوقه أي من كائنات التصميم الثلاثة التي ترسلها في الطلب نفسه.

* **نسخ لا ربط.** يحتفظ رمز QR بنسخته الخاصة من التصميم. تعديل القالب أو حذفه لاحقًا لا يغيّره.
* **التصاميم المخصصة فقط.** لا يمكن تطبيق قالب قيمة `designKind` فيه `branded` أو `ai` عبر API، ويُرجع `422` (`art_template_unsupported`).
* **مساحة عملك فقط.** يُرجع القالب غير المعروف، أو القالب من مساحة عمل أخرى، `404`.

## الترويسات

**Authorization** `string` *required*

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

**Content-Type** `string`

`application/json`. مطلوب في الطلبات التي تحتوي على جسم.

## كائن القالب

**id** `string`

معرّف القالب، مثل `qrt_8Hs2mQvKpLd4RtYw`.

**name** `string`

الاسم المعروض عند اختيار قالب.

**designKind** `string`

للقراءة فقط. `custom` تصميم يمكن لـ API تعديله بالكامل. `branded` و`ai` تصميم بعلامة تجارية أو تصميم بالذكاء الاصطناعي أُنشئ في لوحة التحكم: لا يمكن تعديل صورته عبر API، ويُحتفظ به عند تغيير حقول التصميم الأخرى.

**design** `object`

التصميم المحفوظ. لكل حقل البنية نفسها لحقل الطلب الذي يحمل الاسم نفسه، فيمكنك إرساله مرة أخرى.

**properties**

**styles** `object | null`

أشكال النقاط والزوايا وألوانها.

**frameOptions** `object | null`

الإطار حول رمز QR ونص الدعوة إلى الإجراء.

**logoOptions** `object | null`

الشعار في الوسط.

**createdAt** `string`

تاريخ الإنشاء، بصيغة ISO 8601.

**updatedAt** `string`

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

## عرض قائمة القوالب

`GET /api/v1/templates`

يُرجع قوالب مساحة عملك، الأحدث أولًا. القائمة مقسّمة إلى صفحات: راجع [ترقيم الصفحات](https://docs.getqr.com/ar/api/introduction.md#ترقيم-الصفحات).

**page** `integer` (default: 1)

الصفحة التي تُعاد، 1 أو أكبر.

**pageSize** `integer` (default: 100)

النتائج في كل صفحة، من 1 إلى 100.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/templates?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "qrt_8Hs2mQvKpLd4RtYw",
      "name": "Brand blue",
      "designKind": "custom",
      "design": {
        "styles": {
          "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
          "backgroundOptions": { "color": "#FFFFFF" }
        },
        "frameOptions": null,
        "logoOptions": null
      },
      "createdAt": "2026-07-20T09:12:00.000Z",
      "updatedAt": "2026-07-20T09:12:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}
```

## إنشاء قالب

`POST /api/v1/templates`

يحفظ تصميمًا جديدًا. يُرجع `201 Created`. يُتحقق من حقول التصميم وفق الكتالوجات في [التخصيص](https://docs.getqr.com/ar/api/guides/customization.md)، لذا يُرفض الشكل أو الإطار أو الشعار غير المعروف بالخطأ `422`.

**name** `string` *required*

الاسم المعروض عند اختيار قالب، من 1 إلى 40 حرفًا.

**styles** `object`

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

**frameOptions** `object`

الإطار المرسوم حول رمز QR ونص الدعوة إلى الإجراء. راجع [التخصيص](https://docs.getqr.com/ar/api/guides/customization.md).

**logoOptions** `object`

الشعار الموضوع في الوسط: شعار مقترح، أو ملفك الخاص المرفوع بالغرض `logo` عبر [الملفات](https://docs.getqr.com/ar/api/endpoints/files.md). راجع [التخصيص](https://docs.getqr.com/ar/api/guides/customization.md).

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/templates" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand blue",
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    }
  }'
```

```json 201 theme={null}
{
  "id": "qrt_8Hs2mQvKpLd4RtYw",
  "name": "Brand blue",
  "designKind": "custom",
  "design": {
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    },
    "frameOptions": null,
    "logoOptions": null
  },
  "createdAt": "2026-07-20T09:12:00.000Z",
  "updatedAt": "2026-07-20T09:12:00.000Z"
}
```

## الحصول على قالب

`GET /api/v1/templates/{templateId}`

**templateId** `string` *required*

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

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

```json 200 theme={null}
{
  "id": "qrt_8Hs2mQvKpLd4RtYw",
  "name": "Brand blue",
  "designKind": "custom",
  "design": {
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    },
    "frameOptions": null,
    "logoOptions": null
  },
  "createdAt": "2026-07-20T09:12:00.000Z",
  "updatedAt": "2026-07-20T09:12:00.000Z"
}
```

## تحديث قالب

`PATCH /api/v1/templates/{templateId}`

أرسل فقط الحقول التي تريد تغييرها. تُدمج كائنات التصميم في التصميم المحفوظ، لذا يحتفظ `styles` الجزئي ببقية القيم. تحتفظ رموز QR المُنشأة سابقًا من القالب بالتصميم الذي أُنشئت به.

**templateId** `string` *required*

معرّف القالب.

**name** `string`

الاسم الجديد، من 1 إلى 40 حرفًا.

**styles** `object`

تغييرات الأنماط، تُدمج في `styles` المحفوظ.

**frameOptions** `object`

تغييرات الإطار، تُدمج في الإطار المحفوظ.

**logoOptions** `object`

تغييرات الشعار، تُدمج في الشعار المحفوظ.

```bash cURL theme={null}
curl -X PATCH "https://getqr.com/api/v1/templates/qrt_8Hs2mQvKpLd4RtYw" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Brand blue (2026)" }'
```

```json 200 theme={null}
{
  "id": "qrt_8Hs2mQvKpLd4RtYw",
  "name": "Brand blue (2026)",
  "designKind": "custom",
  "design": {
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    },
    "frameOptions": null,
    "logoOptions": null
  },
  "createdAt": "2026-07-20T09:12:00.000Z",
  "updatedAt": "2026-08-14T09:00:00.000Z"
}
```

## حذف قالب

`DELETE /api/v1/templates/{templateId}`

يحذف القالب. تحتفظ رموز QR المُنشأة منه بتصميمها.

**templateId** `string` *required*

معرّف القالب.

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

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

## تكرار قالب

`POST /api/v1/templates/{templateId}/duplicate`

يُنشئ نسخة باسم `<name> copy`، لها معرّفها الخاص وتصميم مستقل يمكنك تعديله بحرية. لا يأخذ جسم طلب. يُرجع `201 Created`.

**templateId** `string` *required*

معرّف القالب المراد نسخه.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/templates/qrt_8Hs2mQvKpLd4RtYw/duplicate" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 201 theme={null}
{
  "id": "qrt_2Kd9pLm4Xs7BnVcQ",
  "name": "Brand blue copy",
  "designKind": "custom",
  "design": {
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    },
    "frameOptions": null,
    "logoOptions": null
  },
  "createdAt": "2026-08-14T09:30:00.000Z",
  "updatedAt": "2026-08-14T09:30:00.000Z"
}
```

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

> [accordion] 404 "QR template not found."
>
> لا يطابق `templateId` أي قالب في مساحة عملك. خذه من [عرض قائمة القوالب](#عرض-قائمة-القوالب).

> [accordion] الخطأ 422 عند إنشاء قالب أو تحديثه
>
> أحد حقول التصميم لا يطابق الكتالوجات، مثل نوع نقاط أو إطار أو شعار مقترح غير معروف. تذكر الرسالة اسم الحقل. راجع [التخصيص](https://docs.getqr.com/ar/api/guides/customization.md).

> [accordion] الخطأ 422 art\_template\_unsupported عند إنشاء رمز QR
>
> يستخدم القالب تصميمًا بعلامة تجارية أو تصميمًا بالذكاء الاصطناعي. طبّق بدلًا منه قالبًا قيمة `designKind` فيه `custom`.

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

> [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/templates/save-template.md)

> [card] [الملفات](https://docs.getqr.com/ar/api/endpoints/files.md)


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