---
title: API 參考
description: Recur REST API 完整文件 - 認證、端點、參數、回應格式
---

# API 參考

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

## Base URL

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

## 認證

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

```bash
Authorization: Bearer sk_test_xxx
```

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

### API Key 類型

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

### 環境

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

## 核心概念

  

## API 端點

  
  
  
  
  
  

## 請求格式

所有 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-reference/error-codes)。

## 分頁

列表類 API 支援分頁：

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

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

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