跳轉到主要內容
更新訂單端點讓您能夠從外部系統或自動化腳本修改 AgencyHandy 中的現有訂單（專案） — 變更名稱、狀態、預算、時間線、指派的管理員等。此端點也支援檔案附件，這些附件將附加到訂單的系統資料夾。
使用此端點前，請先完成入門指南以取得您的 API 金鑰和公司 ID。
此端點使用 Authorization: Bearer <token>（已登入成員的存取權杖），而非僅使用 x-api-key 標頭。請確保您的呼叫者已驗證為目標公司的已核准成員。未授權的呼叫者將收到 403 PermissionError。

​
前置條件

  • ✅ 已核准工作區成員的有效 Bearer 權杖
  • ✅ 從 GET {{URL}}/accounts/companies 取得的公司 ID
  • ✅ 您要更新的訂單的訂單 ID（專案 ID，pid）

​
端點

PUT {{URL}}/orders?pid=<ORDER_ID>
Content-Type： multipart/form-data — 即使不附加檔案，也請使用此格式以滿足伺服器的 multipart 解析器要求。

​
標頭

標頭必填說明
Authorization是Bearer <ACCESS_TOKEN> — 已登入成員的存取權杖。
companyid是訂單所屬公司的 Mongo ObjectId。
clientid選填即時客戶端 socket ID。提供時，通知將包含它。

​
查詢參數

​
pid
string
必填
要更新的訂單 / 專案 ID。以查詢字串參數形式傳遞。

​
請求主體欄位

​
name
string
更新訂單標題。最少 2 個字元。
​
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
指派至此訂單的專案經理成員 ID 完整清單。新增的 ID 將加入團隊；移除的 ID 將被刪除。每個 ID 必須屬於同一公司內具有 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無效的訂單 ID、被封鎖的狀態轉換或格式錯誤的內容。相關時回應包含 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 通知。
  • 每次成功的更新都會觸發一個帶有更新後訂單文件和附件元資料的 ORDER.UPDATED webhook 事件（如果您有已訂閱該事件的活躍 webhook）。