تخطَّ إلى المحتوى

تحميل الملفات

تتم عملية الرفع عبر ثلاث خطوات: طلب عنوان الرفع، إرسال الملف، تأكيد المستند. يمكن كتابة عنوان الرفع مرة واحدة ويظل صالحًا لمدة تصل إلى ساعة واحدة.

POST /api/v1/upload/presign
X-API-Key: sk_your_key
Content-Type: application/json
{
"filename": "report.docx",
"file_size": 45678
}
الحقلالنوعمطلوبالوصف
filenameسلسلة نصية✅اسم الملف؛ يحدد الخادم نوع الملف من الامتداد
file_sizeعدد صحيح✅الحجم الدقيق بالبايتات، أكبر من 0
mime_typeسلسلة نصية—اختياري؛ الخادم لا يستخدمه

الاستجابة:

{
"document_id": "4q8mx2q9z1k7p6ra",
"upload_url": "https://upload.example/...",
"upload_headers": {
"Content-Type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"If-None-Match": "*"
},
"finalize_token": "short_lived_token",
"expires_in": 3600
}

أرسل PUT إلى upload_url مع تضمين بايتات الملف الخام كنص الرسالة، وأرسل كل رأس في upload_headers exactly كما هو موضح.

Terminal window
# UPLOAD_URL and UPLOAD_CONTENT_TYPE come from upload_url and upload_headers["Content-Type"] in the previous response
curl --fail-with-body -X PUT "$UPLOAD_URL" \
-H "Content-Type: $UPLOAD_CONTENT_TYPE" \
-H "If-None-Match: *" \
--upload-file "report.docx"

لا تُرسل مفتاح واجهة برمجة التطبيقات OmniDoc الخاص بك في هذه الخطوة. إذا انتهت صلاحية العنوان أو فشل التحويل، اطلب واحدًا جديدًا.

POST /api/v1/upload/finalize
X-API-Key: sk_your_key
Content-Type: application/json
{"finalize_token":"short_lived_token"}

في حالة النجاح، يتم إرجاع المستند:

{
"document": {
"id": "4q8mx2q9z1k7p6ra",
"basename": "report.docx",
"file_size": 45678,
"mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"created_at": "2026-10-01T12:00:00Z"
}
}

لا يُضاف المستند إلى مكتبة الملفات ويصبح قابلًا للاستخدام في المهام إلا بعد التأكيد.

filename مخصص للعرض فقط؛ لا تستخدمه كمسار أو كمعرّف فريد. يقوم الخادم باستبدال الأحرف غير الصالحة وإنشاء اسم تنزيل آمن للأسماء التي تتجاوز الطول المسموح به.

الحالةالسبب
400اسم الملف أو حجمه غير صالح، أو يختلف الحجم المرفوع عن الحجم المطلوب
401المعرف أو finalize_token غير صالح أو منتهي الصلاحية
403العنصر finalize_token ينتمي إلى حساب آخر
410لم يتم العثور على الملف المرفوع (فشل النقل أو انتهاء صلاحية العنوان)؛ يُرجى طلب عنوان جديد
413يتجاوز الحد الأقصى لحجم الملف الواحد
415تنسيق غير مدعوم، أو أن المحتوى لا يتطابق مع الامتداد
422الملف Office تالف أو غير آمن من الناحية الهيكلية
429عدد كبير جدًا من عمليات الرفع
503خدمة الرفع غير متاحة مؤقتًا؛ يرجى المحاولة مرة أخرى لاحقًا