toko

API 串接基礎

toko 提供 API 與 CLI,讓報表排程、內部系統或 AI agent 直接讀寫公司資料。它們與後台走同一套業務規則、權限與稽核。

誰需要讀這篇

  • 管理者:決定要不要開通、替程式建立 API 金鑰、日後撤銷。讀「開通」與「憑證」兩節即可。
  • 工程師或 agent 使用者:實際寫程式或下指令。整篇都要讀,細節在各節的收合區。

只想在自己的官網顯示行程,不需要這篇,改讀自建前台 API。

API 與後台的範圍

API 能做的事,後台都能做;後台能做的事,不一定都開放給 API。公開範圍以 API 參考與 CLI 參考為準。

  • API 呼叫與後台操作套用同一組業務規則,結果也同樣寫進稽核日誌。
  • CLI 是 API 的命令列版本,每個命令都對應一個 API 端點。
  • 有些操作刻意只留在後台,例如護照辨識的人工確認、銀行對帳單匯入、旅客待辦勾稽。會員本人的資料匯出只能由本人登入操作。完整界線見營運自動化。

開通

API 與 CLI 屬於進階套組的「API 與自動化」模組,由平台開通,租戶不能自行打開。

  1. 到後台 →「公司設定」→「方案模組」,確認「API 與自動化模組」顯示「已開通」。
  2. 未開通時,請洽平台。

開通不會增加任何帳號的權限,也不會連帶開通其他業務模組。模組停用後,既有的金鑰與 CLI 登入都會立即失效。模組清單見模組與串接選擇。

認證與租戶

每個旅行社(租戶)有自己的網址與資料,彼此完全隔離。你連到哪家公司的網址,就只能操作那家公司的資料;一家公司的憑證不能存取另一家公司。

程式呼叫 API 時要帶憑證。憑證有兩種:

憑證適合誰怎麼取得有效期
CLI 登入人在終端機或 agent 裡操作執行登入指令,再用後台帳號在瀏覽器核准7 天,到期要重新登入
API 金鑰無人值守的排程、腳本與系統管理員到後台「開發者」分頁建立建立時選 90 天、180 天、1 年或永不到期

兩種憑證都代表某一位員工。它能做的事不會超過該員工角色的權限,詳見權限與角色。

建立 API 金鑰

目前只有內建「管理員」角色能建立 API 金鑰。

  1. 到後台 →「公司設定」→「開發者」,在「API 金鑰」按「建立金鑰」。
  2. 重新驗證身分(輸入密碼與兩步驟驗證碼,或使用 passkey)。
  3. 填「名稱(用途)」,例如「報表排程」。清單與稽核日誌用這個名稱辨識來源。
  4. 選「到期」。建議設定到期日並定期輪替。
  5. 選權限:沿用你的完整角色權限,或逐項縮小。每個資料類別可選「無」「唯讀」「讀寫」;涉及個資的動作要另外逐項勾選,選「唯讀」不會自動包含它們。
  6. 按「建立金鑰」,立即複製完整金鑰。完整金鑰只顯示這一次。

金鑰的管理規則:

  • 金鑰綁定建立者。建立者被凍結、移除或改角色時,名下的金鑰一併失效。
  • 有「建立與撤銷 API 金鑰」權限的人看得到全公司的金鑰,其他人只看得到自己的。
  • 按「撤銷」立即生效,無法復原。使用這把金鑰的程式會開始被拒絕。
  • 清單顯示每把金鑰的最後使用時間,可用來找出不再使用的金鑰。

CLI 登入

  1. 在終端機執行登入指令(見 CLI 參考)。畫面會印出核准網址與裝置代碼。
  2. 在已登入後台的瀏覽器開啟網址,重新驗證身分,再按「授權」。驗證後 5 分鐘內要完成授權。
  3. 回到終端機,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。
bash
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 回應都是統一信封。成功:

json
{
  "ok": true,
  "data": {/* … */}
}

失敗:

json
{
  "ok": false,
  "error": {
    "code": "validation",
    "message": "…",
    "issues": [/* … */]
  }
}
codeHTTP意義
invalid_json400body 不是合法 JSON
unsupported_media_type415非空 body 沒有使用 application/json
unauthorized401無效、過期、已撤銷或缺少憑證
forbidden403角色或金鑰沒有所需權限
invalid_origin403Cookie 寫入請求缺少同源 Origin
two_factor_required403帳號尚未完成必要的兩步驟驗證
module_disabled403所需模組未開通
not_found404資源不存在,或不在你的可見範圍
conflict / invariant409狀態衝突(如重複、座位不足、資料已過期)
validation422輸入未通過驗證(附 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

下一步

Command Palette

Search for a command to run...