وثائق API - مرجع API الضغط الكامل

مواصفات OpenAPI 3.0 الكاملة لـ SmartSlim API للضغط، بما في ذلك جميع أوصاف النقاط النهائية وتعريفات المعلمات ومراجع رموز الأخطاء وسياسات تحديد المعدل

المصادقة

يستخدم SmartSlim API للضغط مصادقة Bearer Token

Bearer Token

يتم تمرير API Key عبر رأس طلب HTTP Authorization بالتنسيق Bearer YOUR_API_KEY. يجب أن تتضمن جميع طلبات API هذا الرأس؛ المفاتيح المفقودة أو غير الصالحة ستعيد خطأ 401.

أمن النقل

يتم نقل جميع طلبات API عبر اتصالات HTTPS مشفرة. لا تستخدم بروتوكول HTTP العادي لاستدعاء API، لضمان أمان API Key وبيانات الملفات أثناء النقل.

إدارة API Key

يمكن عرض وإعادة تعيين وتعطيل مفاتيح API في قسم إدارة التطبيقات في وحدة تحكم المطورين. نوصي بإنشاء تطبيقات منفصلة لبيئات مختلفة (التطوير/الاختبار/الإنتاج) لتسهيل العزل والتدقيق.

# مثال على رأس طلب المصادقة
Authorization: Bearer YOUR_API_KEY

قائمة النقاط النهائية

يوفر SmartSlim API للضغط نقاطاً نهائية كاملة لضغط الملفات وإدارة المهام والمعالجة الدفعية وإحصائيات الاستخدام

POST /v1/compress

ضغط الملفات: رفع ملف واحد وإجراء الضغط.

file (مطلوب): الملف المراد ضغطه
quality: جودة الضغط، الخيارات: low / medium / high
format: تنسيق الإخراج
password (اختياري): كلمة مرور التشفير للملفات المضغوطة

GET /v1/tasks/{task_id}

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

إرجاع status: pending / processing / completed / failed

GET /v1/tasks/{task_id}/download

تنزيل الملف المضغوط: بعد اكتمال المهمة، قم بتنزيل ملف نتيجة الضغط عبر هذه النقطة النهائية. إرجاع دفق ملف.

POST /v1/batch/compress

الضغط الدفعي: رفع ملفات متعددة دفعة واحدة لمعالجة الضغط الدفعي.

files[] (مطلوب): مصفوفة الملفات المراد ضغطها
quality: جودة الضغط
format: تنسيق الإخراج
callback_url (اختياري): رابط الاستدعاء لإشعار اكتمال المهمة

GET /v1/usage

الاستعلام عن إحصائيات الاستخدام: استرداد بيانات الاستخدام للحساب الحالي، بما في ذلك عدد استدعاءات API هذا الشهر، وإجمالي حجم الملفات المضغوطة، واستخدام التخزين، والمزيد.

DELETE /v1/tasks/{task_id}

حذف المهمة: حذف مهمة ضغط محددة وملفات نتائجها بواسطة معرف المهمة، وتحرير مساحة التخزين.

مثال على طلب نقطة ضغط الملفات

POST /v1/compress HTTP/1.1
Host: api.uglypear.com
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data; boundary=----FormBoundary

------FormBoundary
Content-Disposition: form-data; name="file"; filename="document.pdf"
Content-Type: application/pdf

(file binary content)
------FormBoundary
Content-Disposition: form-data; name="quality"

high
------FormBoundary
Content-Disposition: form-data; name="format"

pdf
------FormBoundary--

مثال على استجابة الاستعلام عن حالة المهمة

{
  "task_id": "task_8f3c2a1b9e7d4c5f",
  "status": "completed",
  "download_url": "https://api.uglypear.com/v1/tasks/task_8f3c2a1b9e7d4c5f/download",
  "original_size": 5242880,
  "compressed_size": 1572864,
  "compression_ratio": "70.0%",
  "created_at": "2026-08-05T10:00:00Z",
  "completed_at": "2026-08-05T10:00:08Z"
}

مرجع رموز الأخطاء

رموز حالة HTTP ومعانيها التي قد يتم إرجاعها أثناء استدعاءات API، مفيدة لاستكشاف الأخطاء وإصلاحها ومعالجة الاستثناءات

رمز حالة HTTP	الاسم	الوصف
200	نجاح	تمت معالجة الطلب بنجاح، وإرجاع بيانات النتيجة المتوقعة.
400	طلب غير صالح	معلمات الطلب مفقودة أو منسقة بشكل خاطئ أو تتجاوز الحدود. يرجى التحقق من هيكل الطلب والمعلمات.
401	غير مصرح	رأس التفويض مفقود، أو API Key غير صالح أو منتهي الصلاحية. يرجى الحصول على مفتاح صالح.
403	ممنوع	لا يمتلك API Key الحالي صلاحية الوصول إلى المورد أو إجراء العملية. يرجى التحقق من أذونات الخطة وملكية المورد.
429	طلبات كثيرة جداً	تكرار الطلبات يتجاوز حد تحديد المعدل للخطة الحالية. يرجى تقليل تكرار الاستدعاء أو ترقية الخطة.
500	خطأ داخلي في الخادم	حدث استثناء أثناء المعالجة من جانب الخادم. يرجى إعادة المحاولة لاحقاً أو الاتصال بالدعم الفني.
503	الخدمة غير متاحة	الخدمة قيد الصيانة أو محملة بشكل مؤقت. يرجى إعادة المحاولة لاحقاً.

مثال على استجابة الخطأ

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded, current plan limit is 60 requests/minute",
    "request_id": "req_a1b2c3d4e5f6"
  }
}

سياسة تحديد المعدل

تختلف خطط مختلفة في حدود تكرار الطلبات. التجاوز يعيد خطأ 429. يرجى اختيار خطة تناسب حجم أعمالك

10

الخطة المجانية
طلب/دقيقة

60

الخطة الأساسية
طلب/دقيقة

300

الخطة الاحترافية
طلب/دقيقة

غير محدود

خطة المؤسسات
قابلة للتكوين حسب الطلب

يتم قياس تحديد المعدل لكل API Key باستخدام خوارزمية النافذة المنزلقة لحساب الطلبات في الدقيقة. عند تحديد المعدل، تتضمن رؤوس الاستجابة حقول X-RateLimit-Limit و X-RateLimit-Remaining و X-RateLimit-Reset لمساعدة العملاء على تنفيذ استراتيجيات التراجع وإعادة المحاولة.

تنسيقات الملفات المدعومة

يغطي SmartSlim API للضغط تنسيقات ملفات المستندات والصور والفيديو والصوت لتلبية احتياجات الضغط المتنوعة

تنسيقات المستندات

PDF, OFD, DOCX, XLSX, PPTX

تنسيقات الصور

JPG, PNG, TIFF, GIF, BMP

تنسيقات الفيديو

MP4, AVI, MOV

تنسيقات الصوت

MP3, WAV

قد تختلف جودة الضغط المدعومة وخيارات الإخراج وحدود حجم الملف حسب التنسيق. يرجى الرجوع إلى وحدة التحكم واستجابات API الفعلية للحصول على التفاصيل. لطلب دعم تنسيقات إضافية، يرجى الاتصال بفريق المبيعات لمناقشة الحلول المخصصة.

المصحح عبر الإنترنت

أداة تصحيح API عبر الإنترنت تعتمد على Swagger UI، قريباً

التصحيح المرئي

يوفر المصحح عبر الإنترنت واجهة مرئية لملء معلمات النقطة النهائية وإرسال الطلبات، مما يسمح لك بالتحقق بسرعة من سلوك النقطة النهائية وهيكل الاستجابة دون كتابة الكود.

مواصفات OpenAPI 3.0

متوافق تماماً مع مواصفات OpenAPI 3.0، يدعم تصدير ملف المواصفات. يمكنك استيراده مباشرة إلى أدوات مثل Postman أو Apifox للتصحيح المحلي.

قريباً

مصحح Swagger UI عبر الإنترنت قيد التطوير. بعد إطلاقه، ستتمكن من تجربة سير عمل تصحيح API الكامل مباشرة في متصفحك. في غضون ذلك، يرجى الرجوع إلى أمثلة الكود في دليل البدء السريع.

عرض دليل البدء السريع

ابدأ في استخدام API الآن

سجل حساباً للحصول على API Key ودمج قدرات ضغط SmartSlim بسرعة في تطبيقك

دليل البدء السريع تعرف على خدمة API تواصل مع المبيعات

صفحات ذات صلة

دليل البدء السريع تحميل SDK أمثلة الكود سجل التغييرات