API 文件 · 客戶使用指南

API 一覽

這裡整理面向客戶的 API 主要能力與使用流程。

統一資料查詢

對外開放給你的客戶使用，一律以 X-Api-Key 作為鑑權，後端會依 provider / endpoint 自動路由。

• /api/v1/{provider}/{endpoint} GET · 例如 /api/v1/taobao/item-detail-v9?itemId=1016077086716
• /api/v1/taobao/product-search-v1 GET · 必填 keyword；支援可選參數（如 sort=_sale）。

開始使用

透過 3 個步驟即可上手。

• 步驟 1 註冊後到 Dashboard 取得 API Key。
• 步驟 2 選擇平台與 endpoint，使用 X-Api-Key 發送請求。
• 步驟 3 查看用量並依需求升級方案。

計費與 credits

你可在帳戶中心直接管理 credits 與訂閱。

• Credits 每次請求會依 endpoint 規則消耗 credits。
• 儲值 可隨時透過安全付款方式補充 credits。
• 訂閱 各類別方案列明每月套餐所含 credits；可選月繳、半年、年繳以降低平均成本。

常見錯誤與處理方式

• 401 Unauthorized - API Key 缺失或無效，請檢查 X-Api-Key。
• 403 Forbidden - 你的金鑰目前無此 endpoint 權限，或帳戶狀態受限。
• 429 Too Many Requests - 請求過於頻繁，請等待 2-5 秒後重試。
• 5xx Server Error - 平台暫時性錯誤，稍後重試；若持續發生請聯絡支援。

名詞解釋

• Provider URL 路徑中的資料來源分類。
• Endpoint 某個 provider 底下的具體查詢能力。
• Credits 每次請求會消耗的用量單位。
• X-Api-Key API 鑑權使用的 HTTP Header。

最小成功請求模板

• - 必填: 有效的 X-Api-Key
• - 必填: URL 路徑中的 provider 與 endpoint
• - 必填: 該 endpoint 的必要查詢參數（如 itemId / keyword）
• - 建議: 非 ASCII 參數先做 URL 編碼

curl -X GET "https://your-domain.com/api/v1/taobao/product-search-v1?keyword=shoes" \
  -H "X-Api-Key: YOUR_API_KEY"

{
  "data": { "...": "..." },
  "fromCache": false,
  "remainingBalance": 1234
}