API 全景與認證

您不需要透過主控台介面操作 AI GO。這一章說明如何以純 API 的方式使用平台——建立整合、授權資料、讀寫 ERP 表與自建表、執行簽核。

適合的情境：把 AI GO 接進既有系統、寫自動化腳本、做資料同步、或由外部團隊開發前端而以 AI GO 作為後端。

認證方式一覽

平台有四種認證身分，用途不重疊：

本章聚焦 API Key 路徑，因為那是「不需要任何人登入」的方式。

從零到讀取資料：五個步驟

步驟 1：建立整合

POST /api/v1/integrations

需要主站 JWT 與 builder.access 權限。回應含 id 與 slug。

步驟 2：產生 API Key

POST /api/v1/integrations/{app_id}/api-keys

回應中的 api_key 欄位（sk_live_ + 64 字元）只會出現這一次，請立即保存。

同一個整合可以建立多把 Key（正式／測試分離），並可個別撤銷：

GET    /api/v1/integrations/{app_id}/api-keys      # 列出（只回前綴）
DELETE /api/v1/integrations/{app_id}/api-keys/{id} # 撤銷

步驟 3：查可引用的表與欄位

GET /api/v1/refs/available-tables
GET /api/v1/refs/tables/{table_name}/columns

欄位查詢會回傳型別、是否可為空、是否為外鍵及其指向：

[
  { "name": "name", "type": "VARCHAR", "nullable": false, "is_system": false },
  { "name": "customer_id", "type": "UUID", "nullable": true,
    "is_fk": true, "fk_target": "customers.id" }
]

這是規劃資料流時的權威來源——比任何靜態文件清單都準確。

步驟 4：建立引用

POST /api/v1/refs/apps/{app_id}

{
  "table_name": "customers",
  "columns": ["id", "name", "email", "phone", "custom_data"],
  "permissions": ["read", "create", "update"]
}

引用可以用 PATCH /api/v1/refs/{ref_id} 調整、DELETE 移除。

步驟 5：發布

POST /api/v1/integrations/{app_id}/publish

Self-Built 整合的引用需要發布才會在 Open Proxy 生效。 這是它與 Internal／External App 的關鍵差異——後兩者的引用即時生效。

有 builder.publish 權限會直接發布；沒有則建立待審核申請。

發布後即可用 API Key 存取資料。

讀寫 ERP 表：Open Proxy

前綴 /api/v1/open/proxy，認證 X-API-Key，自動以 Key 所屬組織做列級隔離

簡單查詢

curl -H "X-API-Key: sk_live_xxx" \
  "https://api.ai-go.app/api/v1/open/proxy/customers?limit=100&offset=0"

進階查詢

POST /api/v1/open/proxy/{table_name}/query

{
  "filters": [
    { "column": "state", "op": "eq", "value": "sale" },
    { "column": "amount_total", "op": "gte", "value": 1000 }
  ],
  "order_by": [{ "column": "created_at", "direction": "desc" }],
  "search": "關鍵字",
  "search_columns": ["name", "email"],
  "select_columns": ["id", "name", "amount_total"],
  "limit": 50,
  "offset": 0,
  "count_only": false
}

過濾運算子：

組合邏輯的限制（重要）：

• 多個 filter 之間一律以 AND 連接
• 不支援 OR 組合（例外：search 在多個搜尋欄之間使用 OR）
• 不支援巢狀分組（如 (A AND B) OR (C AND D)）
• 需要 BETWEEN 效果請組合 gte + lte

count_only：設為 true 時只回傳符合條件的總筆數 {"total": 42}，filters 與 search 均生效。適合分頁與統計。

寫入

POST   /api/v1/open/proxy/{table_name}            # 新增
PATCH  /api/v1/open/proxy/{table_name}/{row_id}   # 更新
DELETE /api/v1/open/proxy/{table_name}/{row_id}   # 刪除

tenant_id、id、created_at、updated_at 由系統自動處理，不需提供。

自動型別轉換

三套 Proxy 的差別

同一個查詢引擎，三種認證：

Open Proxy 完整支援進階查詢——不是只有 limit / offset。

簽核 API

GET  /api/v1/approvals/record/{res_model}/{res_id}    # 查簽核狀態
POST /api/v1/approvals/{request_line_id}/approve      # 核准
POST /api/v1/approvals/{request_line_id}/reject       # 駁回
POST /api/v1/approvals/{request_id}/retry             # 回調手動重試

查詢會回傳每一關卡的狀態、審核人、簽核意見與時間。核准與駁回會驗證呼叫者是否為該關卡的合格審核人；最後一關核准時自動執行被攔截的原操作。

詳見第 13 章。

公開唯讀端點

GET /api/v1/pub/templates

匿名可存取，回傳平台上架的應用模板目錄。用於在自家網站或工具中呈現可用模板。

錯誤處理

404 的語意值得注意：跨組織存取一律回報「不存在」，不會告訴您資源是否真的存在。這是刻意的設計，避免以錯誤碼探測他人資料。

安全建議

• API Key 存放於環境變數或密鑰管理服務，不要寫進程式碼或提交進版控
• 正式與測試環境使用不同的 Key
• 定期輪換（建新 Key → 切換 → 撤銷舊 Key）
• 引用只宣告實際會用到的欄位與操作——最小權限
• 一般整合不要授予 delete

什麼時候該用 API，什麼時候該用 Custom App

簡單的判準：要資料，用 API；要能力，用 Custom App。