①
TaskGo 要做的
新開一把唯讀金鑰,加 3 個查詢:連線檢查、用電話找案子、讀一件案子。
大部分欄位你們現在就有:MCP 的 get_repair_case、公開的「客戶進度查詢」。
②
最重要的規則
電話完整對得上才回這件案子。
不回任何電話、廠商派工單和金額、客人看不到的留言。
1
這支 API 做什麼Purpose
客人在銓治官方 LINE 問「做到哪了?」「什麼時候來施工?」「報價單在哪裡簽?」,FRIDAI 的 AI 客服用這支 API 查這位客人自己的案子,直接回答。系統對系統:FRIDAI 的伺服器直接呼叫,不經過 Claude,也不經過人。
FRIDAI AI 客服
先問電話,再查這位客人的案子
一次對話怎麼呼叫
- 1確認身分:客人還沒給過電話,AI 先問電話。
- 2找案子:用電話呼叫 lookup,拿到這支電話的案子清單。
- 3選一件:只有一件就用它;有好幾件(例如房仲、房東),AI 問客人是哪個地址。
- 4讀內容:用案號+同一支電話呼叫 detail。
- 5回答:照銓治在 FRIDAI 筆記本寫的規定回答,能講到哪由老闆決定;查不到或 API 出錯,就回客人「我請專人確認」,並通知國幀。
一次對話大約呼叫 1 到 3 次。你們現在的客戶進度查詢(POST /api/public/repair-status/…)和 get_repair_case 已經有大部分要的資料,建議從它們改出來。
2
連線和金鑰Basics
網址、欄位名都是建議,TaskGo 可以自己定,定好給我們文件就好。
網址
https://api.dev.taskgo.com.tw/api/fridai/v1
銓治現在的資料在 dev 這台,所以先開在這裡。
方法
連線檢查用 GET;查案子用 POST,電話放在 JSON 內文,不放在網址(網址會留在伺服器和代理的紀錄裡)。POST 只用來查,不會改任何資料。
格式
HTTPS、JSON、UTF-8。時間 2026-11-17T14:30:00+08:00,日期 2026-11-17;沒有資料回 null 或空陣列,不要省略欄位。
金鑰
標頭 X-API-Key: tg_…,不收放在網址裡的金鑰。新開一把專用的:只能讀修繕案件、只回銓治工程的案子、看得到全部案子(不是綁某個員工、只看到自己的)。
金鑰怎麼交
銓治在 TaskGo「AI 助手串接」產生,貼進 FRIDAI 後台;FRIDAI 加密保存,不會出現在聊天、群組或網頁上。外洩就在 TaskGo 撤銷、再產生一把。
速度
一般 1 秒內回。FRIDAI 最多等 10 秒,超過就當作查不到、轉給真人。
版本
網址帶 v1。可以直接加欄位;要改名或拿掉欄位,請先通知我們。
3
怎麼確認是客人本人Verify
任何人都可以在 LINE 打一支電話,所以電話要完整對得上才回。FRIDAI 現在查網店訂單也是這個規則:訂單編號和下單電話都要對得上。
一定要電話
lookup、detail 都要帶 phone,沒帶回 400。
完整比對
只留數字,比最後 9 碼:0912-345-678、+886 912 345 678、886912345678 都算同一支。少於 9 碼回 400,不能只打後 4 碼查。
比哪些電話
聯絡人 contact_phone、屋主 landlord_phone、房客 tenant_phone,任一支對上就算;回 matched_role 說對上的是哪一個。
對不上
案號存在、但電話不對,回的要跟「沒有這個案號」一模一樣(404),不透露案子存在。
不回電話
回傳裡不放任何電話,客人自己的也不放;也不放聯絡人、屋主、房客的姓名。
FRIDAI 這邊
同一個 LINE 帳號短時間內一直換電話試,FRIDAI 會停下來、轉給真人。
順便:現在公開的客戶進度查詢,電話只打後 4 碼就查得到姓名、地址和照片(11/17 實測),銓治也沒開查詢驗證碼。這支 API 不能這樣;公開那支也建議一起改,或請銓治開驗證碼。
4
三個端點Endpoints
路徑接在第 2 段的網址後面。
① GET /me 連線檢查
銓治把金鑰貼進 FRIDAI 後台時呼叫,確認金鑰有效、是哪一家公司的。
{
"success": true,
"data": {
"organization_name": "銓治工程有限公司",
"key_name": "FRIDAI 客服",
"scopes": ["repair_cases:read"]
}
}
② POST /repair-cases/lookup 用電話找案子
回這支電話的案子,新的在前,最多 20 件。已取消的不回;已結案的要回(客人會問保固)。查不到回空陣列,不是錯誤。
送出
{ "phone": "0912345678" }
address_hint
只到路名,不含門牌、樓層,讓 AI 問客人「是範例路那件嗎?」
{
"success": true,
"data": [
{
"case_no": "T202610021",
"intake_id": "…",
"created_at": "2026-10-02T10:00:00+08:00",
"category_name": "一般修繕",
"address_hint": "台北市中山區範例路",
"status_display": "業主確認 · 待業主線上簽名確認",
"closed": false,
"matched_role": "contact"
}
]
}
③ POST /repair-cases/detail 讀一件案子
電話要對得上這一件才回,對不上回 404。只回客人能看的,欄位見第 5 段。沒有案號的舊案,改帶 intake_id。
{ "case_no": "T202610021", "phone": "0912345678" }
5
案子內容回哪些欄位Fields
欄位名大多照你們 get_repair_case 現在用的。FRIDAI 拿到後,能不能講給客人由銓治在筆記本決定;這裡只管「可以給 FRIDAI 的」。
現有TaskGo 現在就有(括號是現在的欄位) 要加現在沒有
case_no
intake_id
內容案號;沒有案號的舊案用 intake_id
TaskGo 現在現有
created_at
內容報修日
TaskGo 現在現有
category_name
內容案件類型名稱,例如「一般修繕」
TaskGo 現在現有
description
內容修繕內容
TaskGo 現在現有
client_org
內容委託方,例如房仲的店名;沒有回 null
TaskGo 現在現有
matched_role
內容對上的是聯絡人、屋主還是房客(contact、landlord、tenant)
TaskGo 現在要加
status
status_display
內容狀態代碼和中文,例如「業主確認 · 待業主線上簽名確認」
TaskGo 現在現有
stage
next_action
內容現在在哪一階段、下一步要做什麼
TaskGo 現在現有
steps[]
內容客戶進度查詢頁那 7 步:派工、場勘、報價、施工、驗收、房東匯款、發票;每步回 status、done_at
TaskGo 現在現有(客戶進度查詢的 steps)
crew_name
內容負責師傅的稱呼,只回名字,不回電話
TaskGo 現在現有(客戶進度查詢的 assigned_staff_name)
planned_survey_at
planned_work_at
內容預計場勘日、預計施工日
TaskGo 現在現有
planned_complete_at
completed_at
內容預計完工日、完工日
TaskGo 現在現有
quotations[]
內容客戶報價單:doc_number、status、amount(含稅總額)、sent_at、signed_at、sign_url(簽名連結)、warranty(保固)。草稿不回
TaskGo 現在現有(documents 裡 customer_quotation 的);sent_at、warranty 要加
payments[]
內容每一期:installment(期別,從 1 起)、name、amount、due_at、received_amount、received_at、status(unpaid、partial、paid、overdue)。客戶報價簽名後才有;第一版 due_at、received_at 回 null
TaskGo 現在現有(PaymentMilestone)。應收日只是佔位、實際收款日還沒穩定寫入,所以先回 null
billings[]
內容請款單:doc_number、amount、sent_at、signed_at、url。跟 detail 一起回,草稿不回;請款單還沒有免登入頁,url 先回 null
TaskGo 現在現有(金額問題 11/2 起已修好)
invoice
內容required(要不要開)、issued_at、number
TaskGo 現在要不要開、發票日期 現有;發票號碼 要加
warranty
內容term(例如「保固一年」)、until(完工日加保固期)
TaskGo 現在要加(報價單上有保固欄位)
photos[]
內容phase、phase_label、url、taken_at;只回客人看得到的,最新 30 張。網址要 https、不用登入就打得開(FRIDAI 要把照片傳進 LINE)
TaskGo 現在現有(work_photos)。施工、場勘照片是公開網址,不會失效;60 分鐘的簽名網址不放進來
messages[]
內容at、text;只回 visible_to_client 是 true 的留言,最新 10 則
TaskGo 現在現有(messages)
progress_url
內容這一案的客戶進度頁連結
TaskGo 現在現有(後台的客戶分享連結)
client_report_url
內容結案報告的公開連結;還沒有就回 null
TaskGo 現在現有
updated_at
內容這一案最後一次更新的時間
TaskGo 現在要加
絕對不能回
- 廠商派工單(vendor_dispatch)、它的金額和廠商名稱
- 成本、利潤
- 客人看不到的留言(visible_to_client 是 false),例如 AI 助手留的內部留言
- 任何電話和 LINE ID,客人自己的也不回;師傅的電話
- 聯絡人、屋主、房客的姓名
- 還是草稿的報價單、請款單
- 別的客人的任何資料
案子內容的回傳範例
{
"success": true,
"data": {
"case_no": "T202610021",
"intake_id": "…",
"created_at": "2026-10-02T10:00:00+08:00",
"category_name": "一般修繕",
"description": "浴室天花板漏水",
"address": "台北市中山區範例路 1 號 3 樓",
"client_org": null,
"matched_role": "contact",
"status": "in_progress",
"status_display": "業主確認 · 待業主線上簽名確認",
"stage": "業主確認",
"next_action": "待業主線上簽名確認",
"steps": [
{ "name": "派工", "status": "done", "done_at": "2026-10-03" },
{ "name": "場勘", "status": "done", "done_at": "2026-10-05" },
{ "name": "報價", "status": "in_progress", "done_at": null },
{ "name": "施工", "status": "pending", "done_at": null },
{ "name": "驗收", "status": "pending", "done_at": null },
{ "name": "房東匯款", "status": "pending", "done_at": null },
{ "name": "發票", "status": "pending", "done_at": null }
],
"crew_name": "王師傅",
"planned_survey_at": "2026-10-05",
"planned_work_at": null,
"planned_complete_at": null,
"completed_at": null,
"quotations": [
{
"doc_number": "T202610021-Q1",
"status": "sent",
"amount": 26250,
"sent_at": "2026-10-06T15:20:00+08:00",
"signed_at": null,
"sign_url": "https://dev.taskgo.com.tw/repair-doc/…",
"warranty": "保固一年"
}
],
"payments": [
{
"installment": 1,
"name": "訂金",
"amount": 7875,
"due_at": null,
"received_amount": 0,
"received_at": null,
"status": "unpaid"
}
],
"billings": [],
"invoice": { "required": true, "issued_at": null, "number": null },
"warranty": { "term": "保固一年", "until": null },
"photos": [
{
"phase": "survey",
"phase_label": "場勘",
"url": "https://…",
"taken_at": "2026-10-05T10:12:00+08:00"
}
],
"messages": [
{ "at": "2026-10-06T15:25:00+08:00", "text": "報價單已傳送,請點連結確認簽名。" }
],
"progress_url": "https://dev.taskgo.com.tw/repair-progress/…",
"client_report_url": null,
"updated_at": "2026-10-06T15:25:00+08:00"
}
}
範例裡的地址、日期、師傅、訂金、留言是範例值;案號、類型、狀態、報價單號和金額是範例案 T202610021 的實際資料。
6
錯誤和用量Errors
錯誤的格式跟你們現在的接口一樣:success、code、error(中文說明)。
{ "success": false, "code": "case_not_found", "error": "查不到這件案子" }
200
code—
什麼時候成功;lookup 查不到也是 200,data 是空陣列
400
codeinvalid_phone
什麼時候沒帶電話,或少於 9 碼
400
codeinvalid_request
什麼時候沒帶案號或 intake_id,或 JSON 格式錯
401
codeinvalid_key
什麼時候沒帶金鑰、金鑰錯、已撤銷
403
codeforbidden
什麼時候金鑰沒有讀修繕案件的權限
404
codecase_not_found
什麼時候沒有這件案子,或電話對不上(兩種回的一模一樣)
429
coderate_limited
什麼時候太頻繁;標頭 Retry-After 寫幾秒後再試
500、503
codeserver_error
什麼時候TaskGo 出錯或維護中;FRIDAI 會轉給真人
用量和紀錄
- 每把金鑰每分鐘 60 次就夠(一次對話 1 到 3 次);超過回 429
- 每次查詢留紀錄:時間、哪把金鑰、哪個端點、哪個案號、電話有沒有對上;電話只記後 3 碼。銓治要查「誰看過什麼」時用得到
- 只收 HTTPS;金鑰只放在標頭
- 這把金鑰不能呼叫任何會改資料的接口,也不能用在 MCP
7
怎麼驗收、TaskGo 的回覆Testing
請給我們:API 文件(像現在的 gpts_openapi.yaml 那樣的檔案也可以)、網址、一把測試金鑰。先用範例案 T202610021 測下面 8 項。
1 金鑰
怎麼測GET /me
應該看到銓治工程有限公司
2 找得到
怎麼測lookup 帶範例案的聯絡電話
應該看到清單裡有 T202610021
3 找不到
怎麼測lookup 帶 0900000000
應該看到200、空陣列
4 擋短號碼
怎麼測lookup 只帶 4 碼
應該看到400 invalid_phone
5 電話不對
怎麼測detail 帶 T202610021+0900000000
應該看到404,跟查一個不存在的案號完全一樣
6 不該回的
怎麼測detail 帶範例案+正確電話
應該看到沒有派工單 T202610021-D1、沒有任何電話、沒有 11/4 AI 助手留的內部測試留言
8 撤銷
怎麼測在 TaskGo 撤銷測試金鑰再打
應該看到401
FRIDAI 這邊會做的
- FRIDAI 後台加 TaskGo 串接:銓治貼上金鑰、按連線檢查
- AI 客服加「查修繕進度」:照第 1 段的流程問電話、查案子、回答
- 銓治在筆記本寫清楚哪些能講、哪些要轉給國幀
- 上線前用範例案跑多輪對話測,確認不會講出不該講的
TaskGo 的回覆(Ben,11/17)
- 1收款、分期存在 PaymentMilestone,客戶報價簽名後才建立,期別從 1 起;payments 從這裡來。應收日只是「簽名日每期加 30 天」的佔位,實際收款日還沒穩定寫入,所以第一版 due_at、received_at 回 null。客戶進度查詢的「房東匯款」只是已收金額加總
- 2照片網址不會失效。施工、場勘照片是公開網址,不用登入;60 分鐘的簽名網址只給內部用,不放進這支 API
- 3請款單跟 detail 一起回,不另開接口;草稿不回。請款單還沒有免登入頁,url 先回 null
- 4時程測試金鑰和第一版這週完成