تحميل الملفات
تتم عملية الرفع عبر ثلاث خطوات: طلب عنوان الرفع، إرسال الملف، تأكيد المستند. يمكن كتابة عنوان الرفع مرة واحدة ويظل صالحًا لمدة تصل إلى ساعة واحدة.
1. اطلب عنوان التحميل
Section titled “1. اطلب عنوان التحميل”POST /api/v1/upload/presignX-API-Key: sk_your_keyContent-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}2. أرسل الملف
Section titled “2. أرسل الملف”أرسل PUT إلى upload_url مع تضمين بايتات الملف الخام كنص الرسالة، وأرسل كل رأس في upload_headers exactly كما هو موضح.
# UPLOAD_URL and UPLOAD_CONTENT_TYPE come from upload_url and upload_headers["Content-Type"] in the previous responsecurl --fail-with-body -X PUT "$UPLOAD_URL" \ -H "Content-Type: $UPLOAD_CONTENT_TYPE" \ -H "If-None-Match: *" \ --upload-file "report.docx"لا تُرسل مفتاح واجهة برمجة التطبيقات OmniDoc الخاص بك في هذه الخطوة. إذا انتهت صلاحية العنوان أو فشل التحويل، اطلب واحدًا جديدًا.
3. تأكيد المستند
Section titled “3. تأكيد المستند”POST /api/v1/upload/finalizeX-API-Key: sk_your_keyContent-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" }}لا يُضاف المستند إلى مكتبة الملفات ويصبح قابلًا للاستخدام في المهام إلا بعد التأكيد.
أسماء الملفات
Section titled “أسماء الملفات”filename مخصص للعرض فقط؛ لا تستخدمه كمسار أو كمعرّف فريد. يقوم الخادم باستبدال الأحرف غير الصالحة وإنشاء اسم تنزيل آمن للأسماء التي تتجاوز الطول المسموح به.
الأخطاء
Section titled “الأخطاء”| الحالة | السبب |
|---|---|
400 | اسم الملف أو حجمه غير صالح، أو يختلف الحجم المرفوع عن الحجم المطلوب |
401 | المعرف أو finalize_token غير صالح أو منتهي الصلاحية |
403 | العنصر finalize_token ينتمي إلى حساب آخر |
410 | لم يتم العثور على الملف المرفوع (فشل النقل أو انتهاء صلاحية العنوان)؛ يُرجى طلب عنوان جديد |
413 | يتجاوز الحد الأقصى لحجم الملف الواحد |
415 | تنسيق غير مدعوم، أو أن المحتوى لا يتطابق مع الامتداد |
422 | الملف Office تالف أو غير آمن من الناحية الهيكلية |
429 | عدد كبير جدًا من عمليات الرفع |
503 | خدمة الرفع غير متاحة مؤقتًا؛ يرجى المحاولة مرة أخرى لاحقًا |