API 節點與 AI 節點的行為說明

API 節點

API 節點會在流程到達時，自動向你設定的 URL 發送請求，無需任何人工操作。

POST 請求的實際內容

除了你透過 bodyMapping 指定的表單欄位（含改名後的 key）之外，系統都會自動附加以下欄位：

欄位	說明
submittedAt	流程建立時間
initiatorId	發起人的 User ID
initiatorName	發起人的顯示名稱
apiRequestAt	本次 API 呼叫的時間
subject	流程的主旨
responseSchema	供外部 AI 服務參考的回傳格式規範（見下方）

有設定 bodyMapping：body 只包含上述系統欄位，加上 bodyMapping 指定的表單欄位。

沒有設定 bodyMapping：body 包含上述系統欄位，加上所有的表單資料。

直接查看實際會送出的 payload

到流程詳情頁的「流程圖」分頁，點 API 節點上的「查看 Payload」，就能看到這個節點實際會送出的 完整請求範例（含網址、body、期待的回應），可以複製後直接交給對接的工程師。

外部服務應如何回應

系統期待外部服務回傳以下 JSON 格式，以決定流程繼續（approve）或退件（reject）：

{
  "action": "approve",
  "comment": "處理完成，相關資料已寫入系統"
}

若回傳的 action 是 reject，流程會退回上一個節點，並顯示你回傳的 comment 作為退件理由。

判斷順序如下，狀態碼優先於 action：

情況	結果	使用者看到的訊息
連不上（網址錯、服務沒開）	退件	API call error: connect ECONNREFUSED ...
非 2xx	退件	API call failed (500)
2xx，action 有值但不是 approve / reject	退件	Unknown action: "denied"
2xx，action 為 reject	退件	你回傳的 comment
2xx 但 responseMapping 對不上	退件	API response mapping failed: ...
2xx 但此節點的必填欄位仍是空的	退件	Required fields not filled: [...]
2xx，action 為 approve 或未提供	繼續	你回傳的 comment

action 的比對不分大小寫、會去掉前後空白，"REJECT" 與 "reject" 等價。

最後一列是給一般 REST API 的：對方不認得本協定、只回 200 OK 也沒關係，body 是純文字甚至空白 都算成功，不需要為了 kikuflow 做任何調整。

非 2xx 時 action 不算數

狀態碼不是 2xx 的話，即使 body 帶了 {"action":"approve"} 也一律視為失敗。要讓流程繼續， 請回 2xx。

action 打錯字會被擋下

{"action":"rejct"}、{"action":"denied"} 這類看不懂的值一律視為失敗，不會被當成批准。 不想使用 action 機制的話，請完全不要放這個欄位，而不是放一個自訂的值。

responseSchema 是什麼？

responseSchema 是系統自動附加在 request body 裡的欄位，用來告知外部 AI 服務應該回傳的 JSON 格式。若你對接的是一般 REST API 而非 AI，可以忽略這個欄位。

若節點設定了 assignedFormFieldIds，responseSchema 也會包含這些欄位的 label、type、required 等資訊，讓外部 AI 知道可以填寫哪些表單欄位。外部服務回傳的 formData 只有 assignedFormFieldIds 中列出的欄位會被寫入，其餘欄位即使回傳也會被忽略。

呼叫失敗時怎麼查

每次 API 呼叫的結果都會記錄在流程的「流程進度」欄位。失敗時會以紅字顯示上表的訊息，下方另有 耗時與「查看回應」，點開可看到對方回傳的完整內容與 Content-Type。

連不上時訊息會帶出故障代碼，用來分辨問題出在哪一端：

• ENOTFOUND — 網域找不到，通常是網址打錯
• ECONNREFUSED — 位址對，但對方服務沒有啟動
• 憑證相關錯誤 — 對方的 HTTPS 憑證有問題

這幾種都代表請求根本沒送達，不是對方拒絕了你的資料。

若對方是回了 2xx 以外的狀態碼，它自己回傳的錯誤說明仍完整保留在「查看回應」裡。

WARNING

2026-08-17 之前產生的紀錄沒有這些資料，只會顯示原本的文字說明。

responseMapping 寫回欄位

若有設定 responseMapping，系統會從 API 回應中取出指定的值，自動寫回對應的表單欄位。只要回應中缺少任何一個設定的 key，流程就會退件（與該欄位是否必填無關）。

但外部服務明確回傳 action: "reject" 時不檢查 responseMapping——你要退件時本來就不會有資料 可回，此時系統直接採用你的 comment 作為退件理由。

---

AI 節點

AI 節點會在流程到達時，由系統內建 AI 自動讀取所有表單資料，根據節點的 instruction 做出判斷。

AI 會收到什麼

• 節點的 instruction（你設定的審核指令）
• 所有目前的表單欄位與其值
• 附件（圖片、PDF、純文字檔）的實際內容

AI 會做什麼

AI 根據 instruction 決定 approve 或 reject，並回傳審核意見。

若節點設定了 assignedFormFieldIds，AI 會嘗試填入這些欄位的值（例如：自動填入分類標籤、緊急程度等）。

如何設計好的 instruction

instruction 是給所有處理此節點的人或 AI 閱讀的說明，內容永遠會放入 POST request body（即使為空字串）。清楚描述判斷標準比描述流程更有效。例如：

• ✅「費用超過 5 萬且未附上三張以上報價單，請駁回並說明原因。」
• ❌「請審核這份費用申請。」