kintone 提供了相當便利的「流程管理」功能。啟用流程管理後，可以設定簽核路徑或業務流程（工作流程），例如設定備品採購應用程式的申請流程，或在訂單管理應用程式中設定作業流程等。

除了透過 kintone 介面手動操作外，kintone 也提供了更新流程狀態的 REST API，讓開發者能以程式方式推進流程。本篇文章將介紹更新流程狀態 API 的使用方式，以及開發者常見的誤解與錯誤情境。

更新單筆記錄的狀態

此 API 可更新單筆記錄的流程狀態，適用於啟用了「流程管理」功能的應用程式。

PUT https://sample.cybozu.com/k/v1/record/status.json

基本結構

範例請求

{
  "app": 4,
  "id": 1,
  "action": "送出申請",
  "assignee": "user2",
  "revision": 1
}

範例回應

{
  "revision": "3"
}

回傳參數 revision 為狀態變更後的記錄版本號。

💡執行流程動作與更新狀態各會產生一次修訂，因此 revision 通常會增加 2。

更新多筆記錄的狀態

若要一次更新多筆記錄的流程狀態，可使用以下 API。
每次呼叫最多可更新 100 筆記錄，超過上限將會發生錯誤。

PUT https://sample.cybozu.com/k/v1/records/status.json

使用 records 陣列指定要更新的多筆記錄，每筆記錄的結構與「更新單筆記錄的狀態」相同。

基本結構

範例請求

{
  "app": 4,
  "records": [
    {
      "id": 1,
      "action": "送出申請",
      "assignee": "user2",
      "revision": 1
    },
    {
      "id": 2,
      "action": "核准"
    }
  ]
}

範例回應

{
  "records": [
    { "id": "1", "revision": "3" },
    { "id": "2", "revision": "9" }
  ]
}

回傳參數中的 records[].id 為記錄號碼， records[].revision 為該記錄的版本號。

呼叫 API 時所需之權限

透過使用者認證執行 API 時：

• 需具備應用程式記錄的閱覽權限。
• 需具備取得值來源記錄／欄位的閱覽權限。
• 記錄未指定執行者，或 API 執行者即為該記錄的執行者。

透過 API token 驗證執行 API 時：

• 需具備應用程式記錄的閱覽權限。
• 需具備取得值來源記錄／欄位的閱覽權限。
• 記錄未指定執行者，或記錄的執行者為「Administrator」。

常見誤區

使用 API Token 時出現 403「無法更新狀態」錯誤

如上所述，使用 API Token 呼叫流程狀態 API 時，相當於以「Administrator」身份執行動作。若該狀態的執行者另有其人，則會發生權限錯誤。

[403] [GAIA_NT02] 無法更新狀態。只有執行者能執行此動作。

👉 解法：
可改用「使用者認證」方式呼叫，或於更新狀態前，先使用「更新記錄上的執行者」API 清除或變更執行者。

誤將 assignee 當作「當前執行者」

assignee 參數的作用是指定「執行動作後，下一階段的執行者」。
許多開發者誤以為此參數可指定當前執行動作的使用者，導致 API 回傳錯誤。

若需在動作執行前修改執行者，請先呼叫「更新記錄上的執行者」API 進行變更，再呼叫更新流程狀態 API。

下一個狀態需指定執行者，卻未正確指定 assignee 參數

若流程動作執行後的下一個狀態，在流程管理中設定為「從以下使用者中選擇執行者」時，必須在 assignee 中指定一使用者代碼。若未指定時，會發生以下錯誤：

[400] [GAIA_SA01] 請指定執行者。

如果指定了選項外的使用者，則會發生以下錯誤：

[400] [GAIA_IS01] 無法將指定的使用者（userCode）設為執行者。應用程式的設定可能已被變更。

輸入錯誤的動作名稱、忽略動作名稱的多語言設定

當輸入的動作名稱不存在時，會發生以下錯誤：

[400] [GAIA_IL03] 狀態變更失敗。其他使用者可能已變更狀態或狀態的設定。

此問題常發生於程式碼完成後，應用程式管理者又在應用程式後台修改了動作名稱，或是忽略了多語言設置的情況。

若應用程式中的動作名稱設有多語言版本，action 參數的值需與「執行 API 身份的語言設定」一致。例如：

• 繁體中文：「送出申請」
• 英文：「Apply」
• 日文：「申請する」

若使用者語言設定為日文，但程式碼中固定傳入中文名稱，也會發生動作不存在的錯誤。
可透過 kintone.getLoginUser() 取得登入使用者語言，動態指定動作名稱：

const applyActionName = {
  'en': 'Apply',
  'ja': '申請する',
  'zh-TW': '送出申請',
}
const lang = kintone.getLoginUser().language
const actionName = applyActionName[lang] || applyActionName['zh-TW']

const body = {
  app: kintone.app.getId(),
  id: recordId,
  action: actionName,
}

await kintone.api(kintone.api.url('/k/v1/record/status.json', true), 'PUT', body)

結語

更新流程狀態的 REST API 是 kintone 中推動自動簽核與批次流程進行的重要工具。
然而，因涉及執行者權限、流程條件與多語言設定等細節，若未充分理解規則，往往會導致「只有執行者能執行此動作」或「狀態變更失敗」等常見錯誤。

開發時建議配合官方文件，特別留意各參數的使用方式與執行 API 所需的權限設定。
此外，kintone 的彈性設定雖然方便，但在有客製化開發的應用中，任意調整流程設定往往是造成程式報錯的主因之一。
因此，建議在開發文件或應用管理規範中，明確記錄簽核流程設計與對應的程式邏輯，確保未來流程調整時，能同步檢視並更新相關的客製化程式碼，維持系統整體穩定性與一致性。