API 串接基礎
誰需要讀這篇
- 管理者:決定要不要開通、替程式建立 API 金鑰、日後撤銷。讀「開通」與「憑證」兩節即可。
- 工程師或 agent 使用者:實際寫程式或下指令。整篇都要讀,細節在各節的收合區。
只想在自己的官網顯示行程,不需要這篇,改讀自建前台 API。
API 與後台的範圍
API 能做的事,後台都能做;後台能做的事,不一定都開放給 API。公開範圍以 API 參考與 CLI 參考為準。
- API 呼叫與後台操作套用同一組業務規則,結果也同樣寫進稽核日誌。
- CLI 是 API 的命令列版本,每個命令都對應一個 API 端點。
- 有些操作刻意只留在後台,例如護照辨識的人工確認、銀行對帳單匯入、旅客待辦勾稽。會員本人的資料匯出只能由本人登入操作。完整界線見營運自動化。
開通
API 與 CLI 屬於進階套組的「API 與自動化」模組,由平台開通,租戶不能自行打開。
- 到後台 →「公司設定」→「方案模組」,確認「API 與自動化模組」顯示「已開通」。
- 未開通時,請洽平台。
開通不會增加任何帳號的權限,也不會連帶開通其他業務模組。模組停用後,既有的金鑰與 CLI 登入都會立即失效。模組清單見模組與串接選擇。
認證與租戶
每個旅行社(租戶)有自己的網址與資料,彼此完全隔離。你連到哪家公司的網址,就只能操作那家公司的資料;一家公司的憑證不能存取另一家公司。
程式呼叫 API 時要帶憑證。憑證有兩種:
| 憑證 | 適合誰 | 怎麼取得 | 有效期 |
|---|---|---|---|
| CLI 登入 | 人在終端機或 agent 裡操作 | 執行登入指令,再用後台帳號在瀏覽器核准 | 7 天,到期要重新登入 |
| API 金鑰 | 無人值守的排程、腳本與系統 | 管理員到後台「開發者」分頁建立 | 建立時選 90 天、180 天、1 年或永不到期 |
兩種憑證都代表某一位員工。它能做的事不會超過該員工角色的權限,詳見權限與角色。
建立 API 金鑰
目前只有內建「管理員」角色能建立 API 金鑰。
- 到後台 →「公司設定」→「開發者」,在「API 金鑰」按「建立金鑰」。
- 重新驗證身分(輸入密碼與兩步驟驗證碼,或使用 passkey)。
- 填「名稱(用途)」,例如「報表排程」。清單與稽核日誌用這個名稱辨識來源。
- 選「到期」。建議設定到期日並定期輪替。
- 選權限:沿用你的完整角色權限,或逐項縮小。每個資料類別可選「無」「唯讀」「讀寫」;涉及個資的動作要另外逐項勾選,選「唯讀」不會自動包含它們。
- 按「建立金鑰」,立即複製完整金鑰。完整金鑰只顯示這一次。
金鑰要像密碼一樣保管:不要寫進前端程式,也不要提交進版本控制。外洩時立即撤銷,再建一把新的。
金鑰的管理規則:
- 金鑰綁定建立者。建立者被凍結、移除或改角色時,名下的金鑰一併失效。
- 有「建立與撤銷 API 金鑰」權限的人看得到全公司的金鑰,其他人只看得到自己的。
- 按「撤銷」立即生效,無法復原。使用這把金鑰的程式會開始被拒絕。
- 清單顯示每把金鑰的最後使用時間,可用來找出不再使用的金鑰。
CLI 登入
- 在終端機執行登入指令(見 CLI 參考)。畫面會印出核准網址與裝置代碼。
- 在已登入後台的瀏覽器開啟網址,重新驗證身分,再按「授權」。驗證後 5 分鐘內要完成授權。
- 回到終端機,CLI 會自動完成登入。
只有後台員工帳號能授權 CLI;會員與嚮導帳號不能。不是你本人剛剛發起的登入,請按「拒絕」。
到後台 →「公司設定」→「開發者」→「CLI 登入」,可查看並撤銷你核准過的裝置。撤銷後,該裝置要重新登入。
›憑證格式與請求標頭
- 每個請求帶
Authorization: Bearer <token>。API 金鑰以toko_sk_開頭;CLI 登入憑證由 CLI 自動保存與帶上。 /api/v1只接受員工憑證。前台金鑰(toko_sfk_)只能呼叫/api/storefront/v1,兩者不能互換。- 傳送非空 JSON body 時,帶
Content-Type: application/json。 - 不帶 Cookie 的 bearer 請求不需要 Origin。帶 Cookie 的寫入請求(GET、HEAD、OPTIONS 以外)必須帶同源 Origin,即使同時帶 bearer 也一樣。
- 金鑰只選「唯讀」的資料類別,呼叫該類別的寫入端點會回
403 forbidden。 - CLI 登入的有效期在登入時寫進本機設定,CLI 呼叫前先在本機判斷;到期後不送出請求,直接回
cli_error。
curl https://your-tenant.example.com/api/v1/orders \
-H "Authorization: Bearer $TOKO_TOKEN"用 GET /whoami 確認憑證代表哪個帳號與角色。
權限與角色
憑證能呼叫哪些端點,由它代表的員工角色決定。業務等角色只看得到自己負責的訂單;超出範圍的資料,API 會當作不存在。角色設定、訂單資料範圍與自訂角色,見權限與角色。
模組
API 參考文件以 & 連接同時需要的模組。例如 accounting & tour 表示會計與行程模組都必須開通。缺少任一模組時,端點回 403 module_disabled。
需要特定模組的功能,例如訂房、進階會計、登山與海外,未開通時一律拒絕,與角色權限無關。各模組涵蓋的功能見模組與串接選擇。
錯誤格式
每個 API 回應都告訴你成功或失敗。失敗時附一個固定的錯誤碼與一段給人看的說明。程式請判斷錯誤碼,不要比對說明文字。
›回應信封與常見錯誤碼
所有 /api/v1 回應都是統一信封。成功:
{
"ok": true,
"data": {/* … */}
}失敗:
{
"ok": false,
"error": {
"code": "validation",
"message": "…",
"issues": [/* … */]
}
}| code | HTTP | 意義 |
|---|---|---|
invalid_json | 400 | body 不是合法 JSON |
unsupported_media_type | 415 | 非空 body 沒有使用 application/json |
unauthorized | 401 | 無效、過期、已撤銷或缺少憑證 |
forbidden | 403 | 角色或金鑰沒有所需權限 |
invalid_origin | 403 | Cookie 寫入請求缺少同源 Origin |
two_factor_required | 403 | 帳號尚未完成必要的兩步驟驗證 |
module_disabled | 403 | 所需模組未開通 |
not_found | 404 | 資源不存在,或不在你的可見範圍 |
conflict / invariant | 409 | 狀態衝突(如重複、座位不足、資料已過期) |
validation | 422 | 輸入未通過驗證(附 issues[] 逐欄說明) |
旅客更新遇到資料版本過期或並行操作時回 409 conflict,不會部分寫入。重新讀取最新資料後再重試。詳見旅客與個資。
API 資源一覽
| 領域 | 資源 |
|---|---|
| 銷售與出團 | trips、departures、orders |
| 客戶與名單 | members、travelers(在 orders 底下)、agencies |
| 金流 | payments、payment-requests、payouts |
| 出團作業 | guides、guide-roster、equipment |
| 財務會計 | pnl、internal-external-ledger、reconciliation |
| 設定與帳號 | settings、roles、staff、audit |