> ## 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 عبر API: أشكال النقاط والزوايا، والألوان، والإطارات، والشعارات.

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

نسّق رمز QR باستخدام الكائنات الاختيارية `styles` و`frameOptions` و`logoOptions` عند إنشائه أو تحديثه. جميع الحقول اختيارية، وتُطبَّق القيم الافتراضية على كل ما تتركه.

تعمل الكائنات الثلاثة نفسها مع [رموز QR](https://docs.getqr.com/ar/api/endpoints/qr-codes.md) و[القوالب](https://docs.getqr.com/ar/api/endpoints/templates.md) و[الإنشاء المجمّع](https://docs.getqr.com/ar/api/endpoints/bulk-qr-creations.md). تُرفض الأشكال أو الإطارات أو الشعارات غير المعروفة بالخطأ `422`.

## مثال على كائن التصميم

```json theme={null}
{
  "styles": {
    "dotsOptions": { "type": "rounded", "color": "#000000" },
    "backgroundOptions": { "color": "#ffffff" },
    "cornersSquareOptions": { "type": "dot", "color": "#000000" },
    "cornersDotOptions": { "type": "dot", "color": "#000000" }
  },
  "frameOptions": { "id": "card", "text": "Scan me!", "color": "#000000", "textColor": "#ffffff" },
  "logoOptions": { "type": "suggested", "id": "logo-google", "scalePercent": 25 }
}
```

أرسله مع بقية بيانات رمز QR:

```bash theme={null}
curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "styles": { "dotsOptions": { "type": "rounded", "color": "#1E40AF" } },
    "frameOptions": { "id": "card", "text": "Scan me!" },
    "logoOptions": { "type": "suggested", "id": "logo-website-3" }
  }'
```

## الأنماط

يحدد الكائن `styles` أشكال النمط وألوانه.

| الحقل | القيم |
| - | - |
| `dotsOptions.type` | شكل نقاط الجسم: `square`، `dots`، `rounded`، `classy`، `classy-rounded`، `extra-rounded` |
| `cornersSquareOptions.type` | شكل مربع الزاوية (إطار العين): `square`، `rounded`، `dot`، `classy-rounded` |
| `cornersDotOptions.type` | شكل نقطة الزاوية (بؤبؤ العين): `square`، `dot`، `dots`، `rounded`، `classy` |
| `dotsOptions.color` | لون المقدمة. القيمة الافتراضية `#000000`. |
| `backgroundOptions.color` | لون الخلفية. القيمة الافتراضية `#ffffff`. |
| `cornersSquareOptions.color`، `cornersDotOptions.color` | مقبولة لكن بلا تأثير: تستخدم الزوايا دائمًا `dotsOptions.color`. |

* **الألوان.** قيم hex فقط: `#RGB` أو `#RRGGBB`.
* **تصحيح الأخطاء.** دائمًا `Q`، وليس مُدخلًا. إرسال `styles.qrOptions` يُرجع `422`.
* **التصاميم ذات العلامة التجارية وتصاميم الذكاء الاصطناعي.** لا يمكن ضبطها عبر API. إرسال `styles.logoQrArt` يُرجع `422`.
* **المحتوى.** يُتجاهل `styles.data`. ترمّز الصورة دائمًا محتوى رمز QR.

> [!TIP]
>
> حافظ على تباين كافٍ بين لون المقدمة ولون الخلفية، مع مقدمة داكنة على خلفية فاتحة. قد لا تُمسح الرموز منخفضة التباين. راجع [الألوان](https://docs.getqr.com/ar/design/colors.md).

## الإطارات

يضيف الكائن `frameOptions` إطارًا زخرفيًا يحمل عبارة تحث على اتخاذ إجراء حول رمز QR.

| الحقل | الوصف |
| - | - |
| `id` | مطلوب عند إرسال `frameOptions`. نوع الإطار، من القوائم أدناه. `none` تعني بلا إطار. |
| `text` | تسمية الدعوة إلى الإجراء، حتى 12 حرفًا. القيمة الافتراضية `Scan me!`. |
| `color` | لون الإطار، hex. |
| `textColor` | لون التسمية، hex. يجب أن يختلف عن `color` عندما يعرض الإطار تسمية، ما لم يكن الزوج أحد إعدادات الألوان المدمجة للإطار. |
| `borderColor` | لون الحد، hex. |
| `fingerPrintColor` | لون التمييز لأيقونة الإطار، hex. |

> [accordion] الإطارات العامة
>
> `none`, `card`, `card-1`, `card-2`, `card-3`, `card-4`, `card-5`, `card-7`, `card-8`, `card-9`, `card-10`, `card-11`, `card-12`, `card-13`, `card-14`, `card-15`, `card-hor`, `wreath`, `envelope`, `waitress`, `coffee-cup`, `scooter`, `clipboard`
>
> لا يعرض `card-hor` أي تسمية.

> [accordion] الإطارات حسب نوع رمز QR
>
> | النوع | إطارات بتسمية | إطارات دون تسمية |
> | - | - | - |
> | رابط التطبيق | `app-3` | `app-1`، `app-2` |
> | vCard | `contact-1`، `contact-5` | `contact-2`، `contact-3`، `contact-4` |
> | البريد الإلكتروني | `email-1` | `email-2`، `email-3`، `email-4`، `email-5` |
> | الآراء والتقييمات | — | `feedback-1`، `feedback-2`، `feedback-3`، `feedback-4`، `feedback-5` |
> | الصور | — | `image-1`، `image-2`، `image-3`، `image-4`، `image-5`، `image-6` |
> | الموقع الجغرافي | `location-3` | `location-1`، `location-2`، `location-4`، `location-5`، `location-6` |
> | متعدد الروابط | `multilink-3` | `multilink-1`، `multilink-2` |
> | الدفع | — | `payment-1`، `payment-2`، `payment-3`، `payment-4`، `payment-5` |
> | PDF | `pdf-1` | `pdf-2`، `pdf-3`، `pdf-4` |
> | SMS | `sms-3`، `sms-5`، `sms-7` | `sms-1`، `sms-2`، `sms-4`، `sms-6` |
> | وسائل التواصل الاجتماعي | `social-3` | `social-1`، `social-2`، `social-4` |
> | الفيديو | `video-1`، `video-3` | `video-2`، `video-4`، `video-5`، `video-6` |
> | موقع ويب | `website-1` | `website-2`، `website-3`، `website-4`، `website-5` |
> | WhatsApp | `whatsapp-2` | `whatsapp-1`، `whatsapp-3`، `whatsapp-4` |
> | WiFi | — | `wifi-1`، `wifi-2`، `wifi-3`، `wifi-4` |
>
> يعمل أي إطار مع أي نوع من رموز QR. يطابق التجميع ما في لوحة التحكم.

لا تحتوي الإطارات دون تسمية على حقل للدعوة إلى الإجراء في لوحة التحكم، ولا تنطبق عليها قاعدة وجوب اختلاف `textColor` عن `color`.

## الشعارات

يضع الكائن `logoOptions` شعارًا في وسط رمز QR. اضبط `type` لاختيار نوع الشعار.

### شعار مقترح

اضبط `type` على `suggested` واختر `id` من الكتالوج. استخدم `logo-none` لعدم وضع شعار.

```json theme={null}
{ "logoOptions": { "type": "suggested", "id": "logo-instagram", "scalePercent": 25 } }
```

> [accordion] جميع معرّفات الشعارات المقترحة
>
> `logo-none`, `logo-website-3`, `logo-website-4`, `logo-link`, `logo-pdf-1`, `logo-pdf-2`, `logo-pdf-3`, `logo-picture-1`, `logo-picture-2`, `logo-picture-3`, `logo-picture-5`, `logo-picture-7`, `logo-picture-8`, `logo-video-1`, `logo-video-5`, `logo-whatsapp-1`, `logo-whatsapp-2`, `logo-whatsapp`, `logo-wifi-1`, `logo-wifi-2`, `logo-wifi-3`, `logo-wifi`, `logo-airbnb`, `logo-apple`, `logo-binance`, `logo-bitcoin`, `logo-bolt-food`, `logo-booking`, `logo-facebook`, `logo-glovo`, `logo-google`, `logo-google-maps`, `logo-google-play`, `logo-instagram`, `logo-linkedin`, `logo-location`, `logo-mail`, `logo-paypal`, `logo-stripe`, `logo-venmo`, `logo-cashapp`, `logo-braintree`, `logo-square`, `logo-verifone`, `logo-google-pay`, `logo-apple-pay`, `logo-klarna`, `logo-ayden`, `logo-giropay`, `logo-cartes-bancaires`, `logo-restaurant`, `logo-scan-me`, `logo-tripadvisor`, `logo-trustpilot`, `logo-uber-eats`, `logo-youtube`, `logo-spotify`, `logo-spotify-black`

### شعارك الخاص

**1. ارفع الصورة**

سجّلها عبر [الملفات](https://docs.getqr.com/ar/api/endpoints/files.md) باستخدام `"target": "logo"`، ثم ارفع الملف إلى `uploadUrl` المُعاد.

**2. أشِر إلى الملف**

اضبط `type` على `uploaded` و`fileId` على قيمة `fileId` المُعادة. الحقل `fileId` مطلوب، ويجب أن يكون معرّفًا أعادته نقطة النهاية Files.

```json theme={null}
{ "logoOptions": { "type": "uploaded", "fileId": "file_7bQ2xR9mKp", "scalePercent": 35 } }
```

يُرفض الملف غير المعروف، أو الرفع غير المكتمل، أو الملف المرفوع لغرض آخر.

### حجم الشعار

يحدد `scalePercent` حجم الشعار كنسبة مئوية من رمز QR. يأخذ عددًا صحيحًا من 15 إلى 45. القيمة الافتراضية 25. القيم الأخرى، بما فيها النسب مثل `0.25`، تُرجع `422`.

## تحديث التصميم

* **التحديثات الجزئية.** عند [تحديث رمز QR](https://docs.getqr.com/ar/api/endpoints/qr-codes.md#تحديث-رمز-qr)، تُدمج `styles` و`frameOptions` و`logoOptions` في التصميم المحفوظ. لا يغيّر الكائن الجزئي إلا ما يذكره.
* **تغيير الشعار.** اختيار شعار آخر يستبدل الشعار المحفوظ لكنه يحتفظ بقيمة `scalePercent`.
* **القوالب.** عند استخدام `templateId` أثناء الإنشاء، تُدمج الحقول التي ترسلها فوق تصميم القالب. راجع [القوالب](https://docs.getqr.com/ar/api/endpoints/templates.md).
* **التصاميم ذات العلامة التجارية وتصاميم الذكاء الاصطناعي.** رمز QR الذي قيمة `designKind` فيه `branded` أو `ai` أُنشئ في لوحة التحكم. لا تستطيع API تعديل صورته، لكنها تحتفظ بها عند تغيير حقول أخرى.
* **قراءة التصميم.** تُرجع الاستجابات التصميم المحفوظ ضمن `design`، بالبنية نفسها لحقول الطلب، فيمكنك إرساله مرة أخرى.

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

> [accordion] 422 "Error correction is always Q and is not an input"
>
> احذف `styles.qrOptions` من الطلب.

> [accordion] 422 "Frame caption is at most 12 characters"
>
> اختصر `frameOptions.text` إلى 12 حرفًا أو أقل.

> [accordion] 422 "Frame caption color must differ from the frame color"
>
> `textColor` و`color` متطابقان في إطار يعرض تسمية. اختر `textColor` متباينًا.

> [accordion] 422 "Logo scale is a whole number from 15 to 45"
>
> أرسل `scalePercent` كنسبة مئوية صحيحة، مثل `25`، لا `0.25`.

> [accordion] لون الزوايا لا يتغير
>
> تستخدم الزوايا دائمًا `dotsOptions.color`. لا تأثير لـ `cornersSquareOptions.color` و`cornersDotOptions.color`.

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

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

> [card] [القوالب](https://docs.getqr.com/ar/api/endpoints/templates.md)

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

> [card] [نظرة عامة على التصميم](https://docs.getqr.com/ar/design/overview.md)


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