Intake API（外部 → FLOD）

給 OA 廠商、行銷 CRM、自建系統 使用：將預約意圖送入 FLOD 待安排 佇列，由櫃台排入日曆後才成為正式預約。

開始前

Intake 適用於 排程確認在 FLOD 的情境。若預約主檔在外部 PRM，請先讀 適用情境與整合方式。

前置條件

1. 診所管理員在 設定 → CRM 整合 產生 API 金鑰
2. 取得 Intake API 端點（設定頁唯讀欄位）

端點

POST {FLOD 網域}/api/integrations/intake/reservations/{location_id}
Authorization: Bearer {API 金鑰}
Content-Type: application/json

location_id 為診所 ID，設定頁 Intake API 端點 會顯示完整網址（含目前診所）。API 金鑰必須屬於該診所，否則回傳 401。

Request body

欄位	必填	說明
phone	✓	顧客手機（用於比對或建立顧客）
name	✓	顧客姓名
date_reserve	✓	希望預約時間（字串，與 FLOD 預約格式一致）
external_id	✓	本次預約意圖的唯一 ID（用於去重；不是顧客主檔編號）
external_patient_id		外部系統的顧客主檔編號；有填時請與之後 webhook 對人用同一個值
treatment_names		療程名稱陣列（選填，供櫃台參考）
note		備註
source		來源標記（例如 crm、line-oa）

external_id 與 external_patient_id 差在哪？

欄位	用途
external_id	這一筆「待安排」意圖去重（同一個 lead／訂單重送不會變兩筆）
external_patient_id	這位顧客在 CRM 裡的編號；寫入 FLOD 顧客的「外部顧客編號」，之後行銷事件會帶回

顧客怎麼對上？

1. 有帶 external_patient_id → 先用它找既有顧客
2. 找不到 → 再用手機號碼找
3. 都沒有 → 新建顧客（顧客編號先留空；有帶 external_patient_id 會一併寫入）
4. 用手機找到既有顧客、且對方尚未有外部顧客編號 → 會補上這次傳入的 external_patient_id（已有外部編號則不覆蓋）

範例

{
  "phone": "0912345678",
  "name": "王小明",
  "date_reserve": "2026-09-01 14:00",
  "external_id": "crm-lead-998877",
  "external_patient_id": "crm-contact-12345",
  "treatment_names": ["皮秒雷射"],
  "note": "CRM 活動預約",
  "source": "crm"
}

Response

成功（新建）：

{
  "reservation_id": "…",
  "flod_id": "FLOD 顧客內部 ID",
  "patient_id": "診所顧客編號（可能為空字串）",
  "external_patient_id": "外部顧客編號（可能為空字串）",
  "created": true,
  "status": "pending"
}

同一 external_id 重送（去重）：

{
  "reservation_id": "…",
  "flod_id": "…",
  "patient_id": "…",
  "external_patient_id": "…",
  "created": false,
  "status": "pending"
}

欄位	說明
flod_id	FLOD 顧客主鍵（系統用）
patient_id	診所「顧客編號」；Intake 新建時通常為空，除非櫃台之後有填
external_patient_id	外部系統顧客編號

HTTP 狀態：201（新建）或 200（已存在）。

回應欄位更名

請以 flod_id 作為 FLOD 顧客 ID。patient_id 只代表診所顧客編號，不是 Mongo／系統主鍵。

錯誤

HTTP	說明
401	缺少或無效的 Bearer token
400	必填欄位缺失、電話格式無效、欄位超過長度限制等
413	Request body 超過大小上限
415	Content-Type 不是 application/json
429	請求過於頻繁，或診所待安排佇列已滿（見下方限制）
500	伺服器錯誤

429 回應含 Retry-After（秒）。錯誤代碼範例：rate_limit_exceeded、pending_queue_full。

平台限制（統一預設）

以下為 FLOD 平台預設，所有診所共用；整合方請在應用端做好重試與退避。

項目	限制
請求頻率（每 API 金鑰）	60 次／分鐘
請求頻率（每診所）	60 次／分鐘
未授權嘗試（每 IP）	20 次／分鐘
Request body 大小	16 KB
待安排佇列（每診所同時 pending）	200 筆
external_id	最長 128 字；允許 A–Z a–z 0–9 ._:/@+-
external_patient_id	最長 128 字；字元規則同 external_id
name	最長 100 字
note	最長 500 字
source	最長 50 字
treatment_names	最多 10 項，每項最長 100 字
date_reserve	最長 50 字

待安排佇列已滿時：新的 external_id 會回 429（pending_queue_full），請先請櫃台處理或 promote 既有 pending。同一 external_id 重送（冪等）不受此限，仍回 200／201。

僅支援 POST；其他 HTTP 方法回 405。

櫃台後續操作

1. 開啟 預約 → 待安排
2. 選擇 pending 預約，排入日曆（指定醫師／診間）
3. 完成後狀態變為 已排程，並建立到訪流程

Pending 預約不佔日曆時段、不建立 Flow，直到櫃台 promote。

安全建議

• API 金鑰僅在產生當下顯示一次；遺失請在設定頁 重新產生（舊金鑰立即失效）。
• 請以 HTTPS 呼叫；勿將金鑰寫入前端公開程式碼。
• 收到 429 時請依 Retry-After 延遲重試；勿在迴圈中連續重送。
• 整合端應保存 external_id（預約去重）與 external_patient_id（顧客對人），以便重送與對帳。