メインコンテンツへスキップ
注文更新エンドポイントを使用すると、AgencyHandy内の既存の注文（プロジェクト）を — 名前、ステータス、予算、タイムライン、割り当てマネージャーなど — 外部システムや自動化スクリプトから変更できます。このエンドポイントはファイル添付もサポートしており、注文のシステムフォルダに追加されます。
このエンドポイントを使用する前に、入門ガイドを完了してAPIキーと会社IDを取得してください。
このエンドポイントはx-api-keyヘッダーだけでなく、Authorization: Bearer <token>（サインイン済みメンバーのアクセストークン）を使用します。呼び出し元が対象会社の承認済みメンバーとして認証されていることを確認してください。未承認の呼び出し元は403 PermissionErrorを受け取ります。

​
前提条件

  • ✅ 承認済みワークスペースメンバーの有効なBearerトークン
  • ✅ GET {{URL}}/accounts/companiesから取得した会社ID
  • ✅ 更新したい注文の注文ID（プロジェクトID、pid）

​
エンドポイント

PUT {{URL}}/orders?pid=<ORDER_ID>
Content-Type: multipart/form-data — ファイルが添付されていない場合でも、サーバーのマルチパートパーサーを満たすためにこれを使用します。

​
ヘッダー

ヘッダー必須説明
AuthorizationはいBearer <ACCESS_TOKEN> — サインイン済みメンバーのアクセストークン。
companyidはい注文が属する会社のMongo ObjectId。
clientid任意リアルタイムクライアントソケット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ペイロード（ファイル送信時はマルチパートフォームエントリに変換）： 
{
  "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通知を送信します。
  • 成功した更新ごとに、そのイベントに登録されたアクティブなWebhookがある場合、更新された注文ドキュメントと添付メタデータを含むORDER.UPDATED Webhookイベントが発行されます。