---
title: "API 全景與認證"
category: "api-and-integration"
canonical: "https://www.ai-go.app/zh-TW/docs/guide/api-overview"
locale: "zh-TW"
last_updated: "2026-08-10"
source: "AI GO 開發者文件（https://www.ai-go.app）"
---

# API 全景與認證

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

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

---

## 認證方式一覽

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

| 身分 | 帶法 | 誰用 | 存取範圍 |
|---|---|---|---|
| **API Key** | `X-API-Key: sk_live_...` | 第三方系統（Self-Built） | 該整合已發布的引用範圍 |
| 主站 JWT | `Authorization: Bearer ...` | 管理端操作（建整合、設引用） | 依使用者角色 |
| App Token | 由平台注入 | Custom App 執行期 | 該應用的引用 ＋ Scope |
| 匿名 | 無 | 公開唯讀端點 | 公開資料 |

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

---

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

### 步驟 1：建立整合

```
POST /api/v1/integrations
```

| 欄位 | 必填 | 說明 |
|---|---|---|
| `name` | 必填 | 整合名稱（1–100 字） |
| `subdomain` | 選填 | 自訂子網域，規則同應用程式命名 |

需要主站 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
```

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

```json
[
  { "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}
```

```json
{
  "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 所屬組織做列級隔離

### 簡單查詢

```bash
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
```

```json
{
  "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
}
```

**過濾運算子**：

| 運算子 | 意義 | value |
|---|---|---|
| `eq` / `ne` | 等於／不等於 | 任意 |
| `gt` / `gte` / `lt` / `lte` | 大小比較 | 數值或字串 |
| `like` / `ilike` | 模糊匹配（後者不分大小寫） | 字串 |
| `is_null` / `is_not_null` | 為空／不為空 | 不需要 |
| `in` | 包含於清單 | 陣列 |

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

- 多個 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` 由系統自動處理，不需提供。

### 自動型別轉換

| 輸入 | 轉成 |
|---|---|
| `YYYY-MM-DD`（正好 10 字元） | 日期 |
| 含 `T` 的 ISO 字串 | 時間戳 |
| JSON 物件或陣列 | JSONB |

---

## 三套 Proxy 的差別

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

| | Internal Proxy | External Proxy | Open Proxy |
|---|---|---|---|
| 前綴 | `/api/v1/proxy/{app_id}/` | `/api/v1/ext/proxy/` | `/api/v1/open/proxy/` |
| 認證 | 組織成員 JWT | App Token | **API Key** |
| 路徑需 `app_id` | 是 | （Token 自帶） | （Key 自帶） |
| 引用版本 | 即時 | 即時 | **已發布快照** |
| `limit` 上限 | 500 | 1000 | **1000** |
| 進階查詢 | 是 | 是 | 是 |

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
```

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

---

## 錯誤處理

| 狀態碼 | 常見原因 |
|---|---|
| `401` | API Key 無效或已撤銷 |
| `403` | 該整合未被授權存取此表，或缺少對應的操作權限 |
| `404` | 資源不存在，**或存在但不屬於您的組織**（刻意不區分） |
| `409` | 唯一性衝突，或發布前置條件未滿足 |
| `422` | 參數格式不符 |
| `429` | 超過配額或速率限制 |

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

---

## 安全建議

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

---

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

| 情境 | 建議 |
|---|---|
| 既有系統要讀寫 AI GO 資料 | **API**（Self-Built 整合） |
| 排程同步、批次處理 | **API** 或 Custom App 排程 |
| 要給人操作的介面 | **Custom App** |
| 需要用平台的 ERP 業務引擎 | **Custom App**（`ctx.erp` 只在 Action 中提供） |
| 需要簽核與 AI 檢索 | **Custom App**（SDK 較完整） |

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