API 整合

API 整合的技術規範。

1. Base URL

您的端點 URL 顯示在端點詳情頁上。

POST

https://api.chikage.io/api/v1/data/{slug}

GET / PUT / DELETE

https://api.chikage.io/api/v1/data/{slug}/{record_id}

2. 身份認證

在請求頭中包含您的 API 金鑰。

請求頭	描述	是否必填
Authorization	`Bearer tm_test_xxx...` / `Bearer tm_live_xxx...`	Yes
Content-Type	`application/json`	Yes
X-Webhook-Callback	Webhook URL	No
X-Webhook-Auth	認證值（例如 Bearer token）	No
X-Webhook-Auth-Header	認證頭名稱	No

3. 請求格式

Content-Type: 僅支援 application/json
最大大小: 每次請求 100KB
方法: POST / GET / PUT / DELETE

CRUD 端點

每個端點自動支援四種 HTTP 方法：

方法	路徑	描述
`POST`	`/api/v1/data/{slug}`	建立新記錄（非同步，加入佇列）
`GET`	`/api/v1/data/{slug}/{record_id}`	按 ID 查詢記錄
`PUT`	`/api/v1/data/{slug}/{record_id}`	按 ID 替換記錄（非同步，加入佇列）
`DELETE`	`/api/v1/data/{slug}/{record_id}`	按 ID 刪除記錄（非同步，加入佇列）

GET、PUT、DELETE 需要使用之前 POST 回應中返回的記錄 ID。

POST — 建立:

curl -X POST https://api.chikage.io/api/v1/data/{slug} \
  -H "Authorization: Bearer tm_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "ORD-2024-001",
  "amount": 45000,
  "items": ["Item A", "Item B"],
  "paid": true
}'

GET — 讀取:

curl https://api.chikage.io/api/v1/data/{slug}/rec_abc123 \
  -H "Authorization: Bearer tm_test_xxx"

PUT — 更新:

curl -X PUT https://api.chikage.io/api/v1/data/{slug}/rec_abc123 \
  -H "Authorization: Bearer tm_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "ORD-2024-001",
  "amount": 50000,
  "items": ["Item A", "Item B", "Item C"],
  "paid": true
}'

DELETE — 刪除:

curl -X DELETE https://api.chikage.io/api/v1/data/{slug}/rec_abc123 \
  -H "Authorization: Bearer tm_test_xxx"

4. 回應格式

成功回應 (202):

{
  "success": true,
  "id": "rec_abc123",
  "message": "Request queued"
}

錯誤回應示例 (400):

{
  "success": false,
  "error": "Validation failed",
  "details": [
    { "field": "order_id", "error": "Required field is missing" }
  ]
}

錯誤回應:

Code	Status	Description
`400`	請求錯誤	無效的 JSON 或缺少必填欄位
`401`	未授權	缺少或無效的 API 金鑰，或 API 金鑰已被所有者停用
`403`	禁止訪問	端點未啟用或訂閱已過期
`415`	不支援的媒體類型	Content-Type 必須為 application/json
`429`	請求過多	月度請求額度已用完
`5xx`	伺服器錯誤	內部伺服器錯誤（500、502、503 等）

5. 協作者 Webhook

API 協作者可以直接接收處理結果。

重試政策: 失敗後最多重試3次（間隔60秒）

6. 測試工具

上線前在沙箱中測試。

內置測試頁面: 在端點詳情頁點擊測試按鈕即可訪問 — 無需額外工具
cURL: 從命令行測試
Postman: 使用 API 測試工具

7. 正式控制台

部署到正式環境後，端點所有者可以直接從儀表板管理正式資料 — 無需外部 API 工具或程式碼。

訪問方式

前往端點詳情 → 正式標籤頁 → 點擊"開啟控制台"在新標籤頁開啟。

功能

完整 CRUD 支援（POST / GET / PUT / DELETE）操作正式資料
正式環境 API 金鑰已自動設定 — 無需手動輸入
控制台的請求不會觸發 Webhook

僅限所有者

只有端點所有者可以訪問正式控制台。協作者無法使用。