# API 參考 (/api)





API 參考 [#api-參考]

Recur 提供完整的 REST API，讓您能夠完全控制訂閱和計費流程。

Base URL [#base-url]

```
https://api.recur.tw/v1
```

認證 [#認證]

Recur API 使用 API Key 認證。在請求標頭中加入：

```bash
Authorization: Bearer sk_test_xxx
```

詳細說明請參考 [API 認證](/getting-started/authentication)。

API Key 類型 [#api-key-類型]

| 類型              | 前綴       | 用途        |
| --------------- | -------- | --------- |
| Secret Key      | `sk_xxx` | 後端使用，完整權限 |
| Publishable Key | `pk_xxx` | 前端使用，限制權限 |

環境 [#環境]

| 環境         | Key 前綴                  | 說明   |
| ---------- | ----------------------- | ---- |
| Sandbox    | `sk_test_` / `pk_test_` | 測試環境 |
| Production | `sk_live_` / `pk_live_` | 正式環境 |

核心概念 [#核心概念]

<Cards>
  <Card title="冪等性" description="理解冪等性的重要性，避免重複扣款等災難" href="/api/idempotency" />
</Cards>

API 端點 [#api-端點]

<Cards>
  <Card title="Checkout Sessions" description="建立和管理託管結帳會話" href="/api/checkout-sessions" />

  <Card title="Products" description="查詢可用的產品（訂閱方案、一次性付款等）" href="/api/products" />

  <Card title="Customers" description="客戶資料查詢與管理" href="/api/customers" />

  <Card title="Subscriptions" description="訂閱狀態查詢與管理" href="/api/subscriptions" />

  <Card title="付款連結 Payment Links" description="建立與管理可分享的付款連結" href="/api/payment-links" />

  <Card title="Webhooks" description="接收支付和訂閱事件通知" href="/api/webhooks" />
</Cards>

請求格式 [#請求格式]

所有 API 請求使用 JSON 格式：

```bash
curl -X POST https://api.recur.tw/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_xxx",
    "mode": "SUBSCRIPTION",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel",
    "promotion_code": "SAVE100"
  }'
```

回應格式 [#回應格式]

成功回應 [#成功回應]

```json
{
  "id": "cs_xxx",
  "url": "https://checkout.recur.tw/cs_xxx",
  "expires_at": "2025-01-01T00:30:00Z"
}
```

錯誤回應 [#錯誤回應]

```json
{
  "error": {
    "code": "conflict",
    "message": "Customer already has an active subscription to this product",
    "doc_url": "https://docs.recur.tw/api/error-codes#conflict",
    "details": [
      {
        "existing_subscription_id": "sub_xxxxx",
        "status": "ACTIVE"
      }
    ]
  }
}
```

常見錯誤代碼 [#常見錯誤代碼]

| HTTP 狀態 | 錯誤碼                     | 說明            |
| ------- | ----------------------- | ------------- |
| 400     | `bad_request`           | 請求參數無效        |
| 401     | `unauthorized`          | API Key 無效或缺失 |
| 402     | `payment_required`      | 付款失敗          |
| 403     | `forbidden`             | 無權限執行此操作      |
| 404     | `not_found`             | 資源不存在         |
| 409     | `conflict`              | 資源衝突（如重複訂閱）   |
| 422     | `validation_error`      | 驗證失敗          |
| 429     | `rate_limit_exceeded`   | 請求過於頻繁        |
| 500     | `internal_server_error` | 伺服器錯誤         |

完整錯誤碼說明請參考 [錯誤碼參考](/api/error-codes)。

分頁 [#分頁]

列表類 API 支援分頁：

```bash
GET /subscriptions?limit=10&starting_after=sub_xxx
```

| 參數               | 說明                 |
| ---------------- | ------------------ |
| `limit`          | 每頁數量（預設 10，最大 100） |
| `starting_after` | 從指定 ID 之後開始        |

Rate Limiting [#rate-limiting]

所有 API 端點皆有 per API key 的速率限制：

| 環境         | 通用限制     | 優惠碼驗證（額外限制）                                    |
| ---------- | -------- | ---------------------------------------------- |
| Sandbox    | 120 次/分鐘 | Publishable: 5/min per IP + 10/hr per customer |
| Production | 600 次/分鐘 | Secret: 60/min per API key                     |

超過限制時會返回 `429 Too Many Requests`，並附帶以下 headers：

| Header                  | 說明                      |
| ----------------------- | ----------------------- |
| `X-RateLimit-Limit`     | 該時間窗口的請求上限              |
| `X-RateLimit-Remaining` | 剩餘可用次數                  |
| `X-RateLimit-Reset`     | 限制重置的 Unix timestamp（秒） |

下一步 [#下一步]

* [5 分鐘快速開始](/getting-started/quick-start) - 建立第一個結帳流程
* [Webhook 整合](/guides/webhooks) - 接收即時通知
* [SDK 文件](/sdk) - 使用 React 或 Vanilla JS SDK