API 參考
API 參考
Recur REST API 完整文件 - 認證、端點、參數、回應格式
API 參考
Recur 提供完整的 REST API，讓您能夠完全控制訂閱和計費流程。
Base URL
https://api.recur.tw/v1認證
Recur API 使用 API Key 認證。在請求標頭中加入：
Authorization: Bearer sk_test_xxx詳細說明請參考 API 認證。
API Key 類型
| 類型 | 前綴 | 用途 |
|---|---|---|
| Secret Key | sk_xxx | 後端使用，完整權限 |
| Publishable Key | pk_xxx | 前端使用，限制權限 |
環境
| 環境 | Key 前綴 | 說明 |
|---|---|---|
| Sandbox | sk_test_ / pk_test_ | 測試環境 |
| Production | sk_live_ / pk_live_ | 正式環境 |
API 端點
請求格式
所有 API 請求使用 JSON 格式：
curl -X POST https://api.recur.tw/v1/checkout/sessions \
-H "Authorization: Bearer sk_test_xxx" \
-H "Content-Type: application/json" \
-d '{
"productId": "prod_xxx",
"mode": "SUBSCRIPTION",
"successUrl": "https://example.com/success",
"cancelUrl": "https://example.com/cancel"
}'回應格式
成功回應
{
"id": "cs_xxx",
"url": "https://checkout.recur.tw/cs_xxx",
"expiresAt": "2025-01-01T00:30:00Z"
}錯誤回應
{
"error": {
"code": "invalid_request",
"message": "productId is required"
}
}常見錯誤代碼
| HTTP 狀態 | 錯誤代碼 | 說明 |
|---|---|---|
| 400 | invalid_request | 請求參數無效 |
| 401 | unauthorized | API Key 無效或缺失 |
| 403 | forbidden | 無權限執行此操作 |
| 404 | resource_not_found | 資源不存在 |
| 500 | internal_error | 伺服器錯誤 |
分頁
列表類 API 支援分頁：
GET /v1/subscriptions?limit=10&starting_after=sub_xxx| 參數 | 說明 |
|---|---|
limit | 每頁數量（預設 10，最大 100） |
starting_after | 從指定 ID 之後開始 |
Rate Limiting
API 有以下限制：
- 每分鐘 100 次請求（Sandbox）
- 每分鐘 1000 次請求（Production）
超過限制時會返回 429 Too Many Requests。
下一步
- 5 分鐘快速開始 - 建立第一個結帳流程
- Webhook 整合 - 接收即時通知
- SDK 文件 - 使用 React 或 Vanilla JS SDK