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

# الملفات

> ارفع ملفات PDF والصور ومقاطع الفيديو والشعارات لرموز QR الخاصة بك.

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

تشير رموز QR من نوع PDF والصور والفيديو إلى ملف، والشعار المخصص ملف أيضًا. يتم الرفع على خطوتين: سجّل الملف للحصول على رابط، ثم أرسل بايتات الملف إلى ذلك الرابط.

| الطريقة | المسار | الوصف |
| - | - | - |
| `POST` | `/api/v1/files` | [تسجيل رفع ملف](#تسجيل-رفع-ملف) |

## رفع ملف

**1. سجّل الملف**

استدعِ [تسجيل رفع ملف](#تسجيل-رفع-ملف) مع قيم `target` و`contentType` و`size` للملف. يحدد `target` أنواع المحتوى المقبولة وحد الحجم. ستحصل على `fileId` و`uploadUrl`.

**2. أرسل الملف**

أرسل الملف بطلب `PUT` إلى `uploadUrl`. يجب أن تطابق قيمتا `Content-Type` و`Content-Length` تمامًا قيمتي `contentType` و`size` اللتين سجّلتهما: يُرفض أي شيء آخر. الرابط موقّع مسبقًا، فلا تُضف مفتاح API. تنتهي صلاحيته بعد 10 دقائق.

```bash theme={null}
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @menu.pdf
```

**3. استخدم معرّف الملف**

مرّر `fileId` عند [إنشاء رمز QR](https://docs.getqr.com/ar/api/endpoints/qr-codes.md):

* كقيمة `fileId` لرمز QR من نوع `pdf` أو `image` أو `video`. ارفع الملف بالغرض المطابق.
* كقيمة `fileId` لصورة الملف الشخصي في رمز QR من نوع `vcard` أو `social` أو `multilink` أو `event`. ارفع الملف بالغرض `logo`.
* كقيمة `logoOptions.fileId`، مع ضبط `logoOptions.type` على `uploaded`، لشعار مخصص. ارفع الملف بالغرض `logo`. راجع [التخصيص](https://docs.getqr.com/ar/api/guides/customization.md).

## الحدود

| `target` | أنواع المحتوى المقبولة | الحجم الأقصى |
| - | - | - |
| `pdf` | `application/pdf` | 20 MB (20,971,520 بايت) |
| `image` | `image/*` | 5 MB (5,242,880 بايت) |
| `video` | `video/*` | 50 MB (52,428,800 بايت) |
| `logo` | `image/*` | 5 MB (5,242,880 بايت) |

* **نوع MIME مجرد.** أرسل نوعًا ونوعًا فرعيًا واحدًا بأحرف صغيرة، مثل `image/png`. تُرفض المعاملات مثل `;charset=` والقوائم.
* **لا SVG.** لا تُقبل الأنواع المعتمدة على XML مثل `image/svg+xml`. ارفع صورة نقطية مثل `image/png` أو `image/jpeg`.

## الترويسات

**Authorization** `string` *required*

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

**Content-Type** `string` *required*

`application/json`.

## تسجيل رفع ملف

`POST /api/v1/files`

يسجّل ملفًا ويُرجع رابطًا موقّعًا مسبقًا لرفعه إليه. لا يرفع هذا الاستدعاء الملف نفسه.

**target** `string` *required*

الغرض من الملف: `pdf` أو `image` أو `video` أو `logo`. يحدد أنواع المحتوى المقبولة وحد الحجم. راجع [الحدود](#الحدود).

**contentType** `string` *required*

نوع MIME للملف، مثل `application/pdf`، دون معاملات. يجب أن يرسل طلب الرفع قيمة `Content-Type` هذه بالضبط.

**size** `integer` *required*

الحجم الدقيق للملف بالبايت، عدد صحيح موجب. يُقارن بحد الغرض. يجب أن يرسل طلب الرفع قيمة `Content-Length` هذه بالضبط.

**name** `string`

اسم الملف الأصلي، حتى 255 حرفًا. يُحفظ للعرض في لوحة التحكم. يُرفض المسار الذي يحتوي على `/` أو `\`.

**fileId** `string`

المعرّف الذي تمرّره كقيمة `fileId` أو `logoOptions.fileId`.

**uploadUrl** `string`

رابط موقّع مسبقًا لإرسال الملف إليه بطلب `PUT`.

**expiresIn** `integer`

عدد الثواني حتى تنتهي صلاحية `uploadUrl`: `600`.

**method** `string`

طريقة HTTP للرفع: `PUT`.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/files" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "pdf",
    "contentType": "application/pdf",
    "size": 248000,
    "name": "menu.pdf"
  }'
```

```json 200 theme={null}
{
  "fileId": "file_7bQ2xR9mKp",
  "uploadUrl": "https://storage.getqr.com/qrs-content/pdf/file_7bQ2xR9mKp?X-Amz-...",
  "expiresIn": 600,
  "method": "PUT"
}
```

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

> [accordion] 422 "Content type … is not allowed for target"
>
> نوع المحتوى لا يطابق الغرض. على سبيل المثال، لا يقبل `pdf` إلا `application/pdf`. راجع [الحدود](#الحدود).

> [accordion] 422 "must be a single lowercase type/subtype"
>
> أرسل نوع المحتوى بأحرف صغيرة ودون معاملات: `image/png`، لا `Image/PNG` أو `image/png; charset=utf-8`.

> [accordion] 422 "File is too large for target"
>
> قيمة `size` المُعلنة تتجاوز حد الغرض. اضغط الملف قبل تسجيله.

> [accordion] يفشل الرفع إلى uploadUrl
>
> تنتهي صلاحية الرابط بعد 10 دقائق من تسجيل الملف، ويجب أن يرسل الطلب قيمتي `Content-Type` و`Content-Length` المسجّلتين بالضبط. سجّل الملف مرة أخرى للحصول على رابط جديد.

> [accordion] 422 "is registered but its content was never uploaded" عند إنشاء رمز QR
>
> سجّلت الملف لكن طلب `PUT` إلى `uploadUrl` لم يكتمل. ارفع الملف، ثم أنشئ رمز QR.

> [accordion] 422 "was uploaded to …" عند إنشاء رمز QR
>
> سُجّل الملف بغرض مختلف، مثل ملف `image` مُستخدم لرمز QR من نوع `pdf`. سجّل رفعًا جديدًا بالغرض المطابق.

> [accordion] 404 "File … was not found" عند إنشاء رمز QR
>
> `fileId` غير موجود. خذه من استجابة [تسجيل رفع ملف](#تسجيل-رفع-ملف).

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

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

> [card] [أنواع QR](https://docs.getqr.com/ar/api/guides/qr-types.md)

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

> [card] [الأخطاء](https://docs.getqr.com/ar/api/errors.md)


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