انتقل إلى المحتوى
Sursa Developers

POST/v1/uploads

بدء رفع متعدد الأجزاء

create_upload

يفتح جلسة رفع لملف كبير (حتى حد التثبيت للرفع متعدد الأجزاء، 5 غيغابايت افتراضيًا): الاسم، ونوع المحتوى، والحجم، والغرض purpose الذي يحدد ما سيستخدم عملية الرفع: card_file (POST /v1/cards)، أو archive (POST /v1/cards/archive)، أو import_attachment (مرفق مستند لمصدر مخصص). تحتوي الاستجابة على المعرّف id (upl_ يليه 32 حرفًا ست عشريًا)، وحجم الجزء part_size، وعدد الأجزاء part_count. كل جزء ما عدا الأخير حجمه part_size بايت بالضبط (من 5 إلى 100 ميبيبايت)، والجزء الأخير هو الباقي. عملية الرفع غير المكتملة تبقى 24 ساعة (expires_at).

امتداد اسم الملف الذي ليس ضمن صيغ الغرض يعيد 415 uploads.unsupported_format (مرفق الاستيراد يقبل أي امتداد). الملف الأكبر من حد التثبيت أو من إجمالي التخزين المتاح للمؤسسة وفق خطتها يعيد 413 uploads.too_large. عدم كفاية التخزين المتبقي، مع احتساب عمليات الرفع غير المكتملة للمؤسسة، يعيد 402 limits.storage.

تمر الأجزاء عبر Sursa (PUT /v1/uploads/{upload_id}/parts/{n}) وتُشفَّر بمفتاح المؤسسة في تخزين الملفات؛ ولا توجد روابط مباشرة إلى التخزين. لا يرى عملية الرفع ولا يستخدمها إلا مفتاح API أو المستخدم الذي أنشأها. أُضيف في الإصدار 1.62.0.

المصادقة

أرسل مفتاح API في الترويسة Authorization: Authorization: Bearer <key>.

معاملات الترويسة

  • Idempotency-Keystring

    مفتاح لإعادة محاولة عملية كتابة بأمان: من 1 إلى 255 حرفًا من أحرف ASCII القابلة للطباعة؛ يُنصح بقيمة UUID v4 لكل عملية منطقية. إعادة المحاولة بالمفتاح نفسه خلال 24 ساعة لا تنفّذ العملية مرة أخرى، بل تعيد الاستجابة المحفوظة (الحالة والترويسات والنص) مع الترويسة Idempotency-Replayed: true. المفتاح نفسه مع أسلوب أو مسار أو Content-Type أو نص مختلف يعيد 409 api.idempotency_mismatch؛ وما دام الطلب الأول قيد التنفيذ، يعيد 409 api.idempotency_in_progress مع Retry-After: 1. بعد استجابة 5xx أو 429 يُحرَّر المفتاح، وتنفّذ إعادة المحاولة العملية مرة أخرى. نطاق المفتاح هو المؤسسة والجهة المستدعية (مفتاح API أو مستخدم أو مفتاح مصدر مخصص).

    length ≥ 1, length ≤ 255

نص الطلب

application/json

الكائن: UploadCreate

  • filenamestringمطلوب

    اسم الملف مع امتداده؛ يحدد الامتداد الصيغة.

    length ≥ 1, length ≤ 255

  • content_typestring

    نوع المحتوى المعلن (MIME)؛ يُقارَن بتوقيع الملف.

    length ≤ 255

  • sizeinteger (int64)مطلوب

    حجم الملف بالبايت.

    ≥ 1

  • purposeUploadPurposeمطلوب
  • sha256string

    قيمة SHA-256 للملف إن كانت معروفة مسبقًا؛ تقارن الخطوة complete المجموع الاختباري للملف بها.

الاستجابات

201أُنشئت جلسة الرفع.

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

  • Idempotency-Replayed

    القيمة true: أُعيدت الاستجابة المحفوظة لهذا المفتاح Idempotency-Key، ولم تُنفَّذ العملية مرة أخرى.

application/json

الكائن: Upload

  • idstringمطلوب

    معرّف عملية الرفع (upl_ يليه 32 حرفًا ست عشريًا).

  • purposeUploadPurposeمطلوب
  • filenamestringمطلوب

    اسم الملف (بلا مجلدات).

  • content_typestringمطلوب

    نوع المحتوى المعلن؛ فارغ إن لم يُعلَن.

  • sizeinteger (int64)مطلوب

    حجم الملف بالبايت.

  • sha256string | nullمطلوب

    قيمة SHA-256 للملف، المعلنة عند الإنشاء أو في الخطوة complete؛ والقيمة null إن لم تكن معروفة بعد.

  • statusUploadStatusمطلوب
  • part_sizeinteger (int64)مطلوب

    حجم كل جزء عدا الأخير (من 5 إلى 100 ميبيبايت).

  • part_countintegerمطلوب

    عدد الأجزاء.

    ≥ 1, ≤ 1000

  • parts_receivedintegerمطلوب

    عدد الأجزاء المستلمة.

    ≥ 0

  • partsarray of UploadPartمطلوب

    الأجزاء المستلمة حسب الرقم (فارغ في استجابة POST /v1/uploads).

  • reject_reasonstring | nullمطلوب

    سبب الرفض (rejected): checksum_mismatch، وtype_mismatch، وunsupported_format، وinfected، وscan_unavailable، وunsafe_content. قد يتوسع التعداد؛ والقيمة null إن لم تُرفض عملية الرفع.

  • reject_detailsobject | nullمطلوب

    تفاصيل الرفض (الامتداد، والصيغة المعلنة والمكتشفة، والمجاميع الاختبارية)؛ والقيمة null إن لم تُرفض عملية الرفع.

  • created_atstring (date-time)مطلوب

    وقت إنشاء عملية الرفع.

  • expires_atstring (date-time)مطلوب

    الموعد النهائي لإكمال عملية الرفع، ثم لاستخدامها بعد أن تصبح جاهزة.

  • completed_atstring (date-time) | nullمطلوب

    وقت انتهاء الفحص (ready أو rejected).

  • consumed_atstring (date-time) | nullمطلوب

    وقت استخدام عملية الرفع (لبطاقة أو أرشيف أو استيراد).

401لم تُرسَل بيانات اعتماد (لا ملف تعريف ارتباط للجلسة ولا مفتاح API)، أو لم يُعثر على المفتاح.

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

402بلغت المؤسسة حدًّا من حدود خطتها (البطاقات أو التخزين أو المستخدمون). يحتوي الحقل `error.details` على `kind` و`limit` و`used`.

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

403الإجراء غير مسموح: الدور غير كافٍ، أو لا وصول إلى المجموعة أو البطاقة، أو يعمل الطلب في وضع «View as»، أو المؤسسة معلّقة أو محذوفة (الحقل `detail` كائن فيه `code: org_suspended | org_deleted`).

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

413نص الطلب يتجاوز الحجم المسموح به.

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

415صيغة الملف غير مدعومة.

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

422خطأ في صحة البيانات: نص الطلب أو المعاملات لا تطابق المخطط (الحقل `detail` قائمة بأخطاء صحة البيانات)، أو قيمة معامل خارج النطاق المسموح (الحقل `detail` رسالة نصية).

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

429طلبات كثيرة جدًا (`api.rate_limited`)، أو استُنفدت حصة المؤسسة للدقيقة أو اليوم أو الشهر (`api.quota_exceeded`؛ يحتوي الحقل `error.details` على `quota` و`limit` و`reset_at`)، أو بلغت المؤسسة حدها، أو خدمة الإجابات مشغولة (`answers.engine_busy`). انتظر المدة المذكورة في الترويسة `Retry-After`.

ترويسات الاستجابة

  • Retry-After

    عدد الثواني التي تنتظرها قبل إعادة محاولة الطلب.

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

رموز الأخطاء

الرموز التي قد تعيدها نقطة النهاية هذه في error.code، إضافةً إلى الرموز العامة لكل طلب.

إعادة المحاولة بأمان

أرسل الترويسة Idempotency-Key (قيمة UUID مثلًا) مع كل طلب POST وPATCH. إعادة المحاولة بالمفتاح نفسه خلال 24 ساعة تعيد الاستجابة المحفوظة بدل تنفيذ الطلب مرة أخرى.

حدود المعدل

تحمل الاستجابات الترويستين RateLimit وRateLimit-Policy، والترويسات الأقدم X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset. وفي الاستجابة 429 الترويسة Retry-After بالثواني: انتظر ثم أعد المحاولة.

← uploads · مرجع API