الملفات

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

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

الطريقة	المسار	الوصف
`POST`	`/api/v1/files`	تسجيل رفع ملف

رفع ملف

سجّل الملف

استدعِ تسجيل رفع ملف مع قيم target وcontentType وsize للملف. يحدد target أنواع المحتوى المقبولة وحد الحجم. ستحصل على fileId وuploadUrl.

أرسل الملف

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

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @menu.pdf

استخدم معرّف الملف

مرّر fileId عند إنشاء رمز QR:

كقيمة fileId لرمز QR من نوع pdf أو image أو video. ارفع الملف بالغرض المطابق.
كقيمة fileId لصورة الملف الشخصي في رمز QR من نوع vcard أو social أو multilink أو event. ارفع الملف بالغرض logo.
كقيمة logoOptions.fileId، مع ضبط logoOptions.type على uploaded، لشعار مخصص. ارفع الملف بالغرض logo. راجع التخصيص.

الحدود

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

الترويسات

string

مطلوب

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

string

مطلوب

application/json.

تسجيل رفع ملف

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

string

مطلوب

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

string

مطلوب

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

integer

مطلوب

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

string

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

string

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

string

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

integer

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

string

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

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

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

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

422 "Content type … is not allowed for target"

نوع المحتوى لا يطابق الغرض. على سبيل المثال، لا يقبل pdf إلا application/pdf. راجع الحدود.

422 "must be a single lowercase type/subtype"

أرسل نوع المحتوى بأحرف صغيرة ودون معاملات: image/png، لا Image/PNG أو image/png; charset=utf-8.

422 "File is too large for target"

قيمة size المُعلنة تتجاوز حد الغرض. اضغط الملف قبل تسجيله.

يفشل الرفع إلى uploadUrl

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

422 "is registered but its content was never uploaded" عند إنشاء رمز QR

سجّلت الملف لكن طلب PUT إلى uploadUrl لم يكتمل. ارفع الملف، ثم أنشئ رمز QR.

422 "was uploaded to …" عند إنشاء رمز QR

سُجّل الملف بغرض مختلف، مثل ملف image مُستخدم لرمز QR من نوع pdf. سجّل رفعًا جديدًا بالغرض المطابق.

404 "File … was not found" عند إنشاء رمز QR

fileId غير موجود. خذه من استجابة تسجيل رفع ملف.

API

رفع ملف

الحدود

الترويسات

تسجيل رفع ملف

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

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

رموز QR

أنواع QR

التخصيص

الأخطاء

​رفع ملف

​الحدود

​الترويسات

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

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

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

رموز QR

أنواع QR

التخصيص

الأخطاء

رفع ملف

الحدود

الترويسات

تسجيل رفع ملف

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

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