الانتقال إلى المحتوى الرئيسي
تتيح لك نقطة نهاية تحديث الطلب تعديل طلب (مشروع) موجود في AgencyHandy — تغيير اسمه وحالته وميزانيته والجدول الزمني والمديرين المعيّنين والمزيد — كل ذلك من نظام خارجي أو سكريبت أتمتة. تدعم النقطة النهائية أيضًا مرفقات الملفات، التي تُضاف إلى مجلد النظام الخاص بالطلب.
قبل استخدام هذه النقطة النهائية، أكمل دليل البدء السريع للحصول على مفتاح API ومعرّف الشركة.
تستخدم هذه النقطة النهائية Authorization: Bearer <token> (رمز وصول عضو مسجّل) بدلًا من ترويسة x-api-key فحسب. تأكد من أن المُستدعي مُصادَق عليه كـ عضو معتمد في الشركة المستهدفة. يتلقى المُستدعيون غير المصرح لهم خطأ 403 PermissionError.

​
المتطلبات الأساسية

  • ✅ رمز Bearer صالح لعضو مساحة عمل معتمد
  • ✅ معرّف الشركة المسترد من GET {{URL}}/accounts/companies
  • ✅ معرّف الطلب (معرّف المشروع، pid) للطلب الذي تريد تحديثه

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

PUT {{URL}}/orders?pid=<ORDER_ID>
Content-Type: multipart/form-data — استخدم هذا حتى عند عدم إرفاق ملفات لإرضاء محلل multipart الخاص بالخادم.

​
الترويسات

الترويسةمطلوبةالوصف
AuthorizationنعمBearer <ACCESS_TOKEN> — رمز وصول العضو المسجّل.
companyidنعممعرّف Mongo ObjectId للشركة التي ينتمي إليها الطلب.
clientidاختياريمعرّف مقبس العميل في الوقت الفعلي. عند توفيره، تتضمنه الإشعارات.

​
معاملات الاستعلام

​
pid
string
مطلوب
معرّف الطلب / المشروع المراد تحديثه. مرر هذا كمعامل سلسلة استعلام.

​
حقول نص الطلب

​
name
string
يُحدِّث عنوان الطلب. الحد الأدنى حرفان.
​
status
string
الحالة الجديدة للطلب. يجب أن تكون إحدى: Pending، Ongoing، Review، Completed، Cancelled.الانتقالات المسموح بها:
  • Review لا يمكن أن يتبع إلا Ongoing أو Review أخرى. الانتقال من Pending مباشرةً إلى Review يُعيد 400 ValidationError.
  • الطلبات التي حالتها Completed أو Cancelled بالفعل لا يمكن تحديثها.
  • لا يمكن للعملاء إلغاء طلب تجاوز مرحلة Pending.
​
budget
number
رقم الميزانية الإجمالية. يجب أن يكون ≥ 0. يستخدم العملة الحالية للطلب ما لم يتم توفير currency أيضًا.
​
currency
string
رمز العملة للميزانية. أمثلة: USD، CAD، EUR.
​
quantity
number
عدد الوحدات المشتراة للحزمة. يجب أن يكون ≥ 1.
​
deadline
string
سلسلة تاريخ ISO 8601 لتاريخ استحقاق الطلب. مثال: "2025-12-31T00:00:00.000Z".
​
kickoffDate
string
سلسلة تاريخ ISO 8601 لتاريخ بدء المشروع.
​
notes
string
ملاحظات داخلية مرئية لفريقك.
​
brief
string
موجز العميل أو ملخص المشروع.
​
assignedProjectManagers
array
القائمة الكاملة لمعرّفات أعضاء مديري المشاريع المراد تعيينهم لهذا الطلب. تُضاف المعرّفات الجديدة إلى الفريق؛ وتُحذف المعرّفات المُزالة. يجب أن ينتمي كل معرّف إلى عضو له دور projectManager داخل نفس الشركة.
​
markTasksAsDone
boolean
مطلوب عندما تكون status هي Completed أو Cancelled. عند تعيينه على true، تُحدَّث حالة جميع المهام في الطلب إلى منجزة بعد تغيير الحالة. عند false، تبقى المهام في حالتها الحالية.
​
rejectRequestedTasks
boolean
مسموح به فقط عندما تكون status هي Completed أو Cancelled. عند تعيينه على true، تُرفض جميع مهام العملاء المعلقة بعد تحديث الحالة.
​
repeatCount
number
مطلوب فقط لطلبات الاشتراك عند تغيير تكرار التكرار. اقرنه بـ repeatDuration.
​
repeatDuration
string
مطلوب جنبًا إلى جنب مع repeatCount لطلبات الاشتراك. إحدى: day، week، month، year.
​
billingCycleCount
number
حد اختياري لدورات الفوترة المتكررة. الإعداد الافتراضي 0 (بلا حد).
​
billingCycleEvent
string
كيفية التعامل مع كل دورة فوترة. إحدى: createOrderWithTask، noChange.
​
files
file
صفر أو أكثر من مرفقات الملفات. تُضاف الملفات إلى مجلد النظام الخاص بالطلب؛ ولا تُستبدل الملفات الموجودة أبدًا. استخدم ترميز multipart/form-data وأرفق كل ملف تحت حقل files.

​
مثال على الطلب

curl --request PUT "https://api.agencyhandy.com/orders?pid=ORDER_ID_HERE" \
  --header "Authorization: Bearer <ACCESS_TOKEN>" \
  --header "companyid: <COMPANY_ID>" \
  --form "name=Website Redesign" \
  --form "status=Review" \
  --form "budget=12000" \
  --form "currency=USD" \
  --form "quantity=1" \
  --form "assignedProjectManagers[]=PROJECT_MANAGER_ID" \
  --form "notes=Scope finalized with client." \
  --form "brief=Launch-ready design refresh."
حمولة JSON المكافئة (حوّلها إلى إدخالات نموذج multipart عند إرسال الملفات): 
{
  "name": "Website Redesign",
  "status": "Review",
  "budget": 12000,
  "currency": "USD",
  "quantity": 1,
  "assignedProjectManagers": ["{{PROJECT_MANAGER_ID}}"],
  "repeatCount": 3,
  "repeatDuration": "month",
  "billingCycleEvent": "createOrderWithTask",
  "notes": "Scope finalized with client.",
  "brief": "Launch-ready design refresh."
}

​
الاستجابات

حالة HTTPالوصف
200 OKنجح التحديث.
400 ValidationErrorمعرّف طلب غير صالح، أو انتقال حالة محظور، أو حمولة مشوهة. تتضمن الاستجابة fieldName عند الاقتضاء.
403 PermissionErrorالمُستدعي ليس عضوًا معتمدًا، أو يفتقر إلى دور الشركة، أو انتهت صلاحية اشتراك مساحة العمل، أو حاول عميل إلغاءً محظورًا.
500 Internal Server Errorاستثناء غير معالج — تحقق من سجلات الخادم.

​
استجابة النجاح

{
  "message": "Project has been updated"
}

​
قواعد العمل والتأثيرات الجانبية

  • انتقالات الحالة مقيّدة. Review لا يمكن أن يتبع إلا Ongoing أو Review أخرى. محاولة Pending → Review تُعيد 400 ValidationError.
  • نقل الحالة من Pending إلى Ongoing أو Review أو Completed يُفعِّل مجلد ملفات الطلب حتى تصبح الملفات المرفوعة متاحة لفريق المشروع.
  • تعيين status إلى Completed أو Cancelled يتطلب تعيين markTasksAsDone صراحةً إلى true أو false.
  • تغييرات الحالة إلى Review أو Completed أو Cancelled تُشغّل تلقائيًا إشعارات العميل:
    • Review — يُخطر العميل بأن المراجعة مطلوبة.
    • Completed — يرسل إشعار orderCompletion للعميل.
    • Cancelled — يرسل إشعار orderCancellation للعميل.
  • كل تحديث ناجح يُشغّل حدث webhook ORDER.UPDATED مع وثيقة الطلب المحدّثة وبيانات تعريف المرفق، إذا كان لديك webhook نشط مشترك في ذلك الحدث.