---
title: API 參考
---

# API 參考

CaptchaLa 提供 RESTful API 介面，支援所有功能的伺服器端呼叫。

## API 位址

```
https://apiv1.captcha.la
```

## 認證方式

所有 API 請求都需要攜帶認證標頭：

```
X-App-Key:    YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
```

::: warning
`X-App-Secret` 僅限伺服器端使用，切勿暴露於瀏覽器、行動 App 或公開的程式碼倉庫中。
:::

## 伺服器端驗證 API

> 💡 **用伺服器端 SDK 省去 boilerplate。** 封裝端點 + 重試 + 型別化錯誤:
> - **PHP** — [`Captcha-La/captchala-php`](https://github.com/Captcha-La/captchala-php)
> - **Go** — `go get github.com/Captcha-La/captchala-go`

使用者通過前端驗證碼後，您的伺服器需要驗證 SDK 返回的 Token。以下是伺服器端驗證介面。

### 伺服器端驗證 Token

驗證前端 SDK 返回的 pass_token（前綴為 pt_）。需要攜帶 X-App-Key 和 X-App-Secret 標頭。

```bash
POST /v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "pt_xxx", "client_ip": "1.2.3.4" }
```

`client_ip` 為選填但建議帶上 — 終端使用者在您後端請求中的來源 IP，用於額外的風險檢查；省略亦可。

```json
{
  "code": 0,
  "data": {
    "valid": true,
    "challenge_id": "ch_xxx",
    "action": "login",
    "uid": null,
    "captcha_args": {
      "platform": "web",
      "user_ip": "1.2.3.4",
      "referer": "https://your-site.com/login",
      "pkg": null,
      "solved_at": 1750000000,
      "risk_score": 12
    }
  }
}
```

`captcha_args` 為資訊性欄位（供您記錄與風控使用）：`platform`、`user_ip`、`referer`、`pkg`、`solved_at`、`risk_score`。

::: tip
請同時驗證 `data.valid === true` **以及** `data.action` 與您預期的場景一致
（若一張 `pay` 流程簽發的 token 被送到 `/login`，應予以拒絕）。Token 為單次使用。
:::

## 伺服器端簽發驗證 Token {#server-token}

由您的伺服器端簽發短時效 server_token，再由瀏覽器在初始化挑戰時攜帶該 Token，以證明請求來自受信任的伺服器。

### 簽發 server_token

僅允許從您的伺服器端呼叫。需要 X-App-Key + X-App-Secret。回應回傳 server_token（前綴 sct_），前端需在 驗證初始化 時帶上。

```bash
POST /v1/server/challenge/issue
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/x-www-form-urlencoded

action=login&ttl=300&max_uses=1&bind_ip=1.2.3.4
```

```json
{
  "code": 0,
  "data": {
    "server_token": "sct_xxxxxxxxxxxx",
    "expires_in": 300,
    "issued_at": 1713600000
  }
}
```

#### 請求體參數（form-urlencoded）

| 欄位 | 說明 |
| --- | --- |
| `action` | 業務場景，如 login、register、pay。需與後續 驗證初始化 使用的 action 一致。 |
| `ttl` | Token 有效期（秒）。預設 300，最大 900。 |
| `max_uses` | Token 最大可用次數。預設 10。 |
| `bind_ip` | 將 Token 綁定到指定用戶端 IP，來自其他 IP 的初始化請求將被拒絕。 |
| `bind_device_id` | 將 Token 綁定到指定裝置 ID。 |
| `bind_fingerprint` | 將 Token 綁定到指定瀏覽器指紋。 |

### 初始化挑戰

由 SDK 呼叫以開始一次驗證碼挑戰。可選參數 server_token 由 /v1/server/challenge/issue 簽發。

| 欄位 | 說明 |
| --- | --- |
| `app_key` | 您的公開 App Key。 |
| `action` | 業務場景，需與簽發 server_token 時使用的 action 一致。 |
| `server_token` | 可選；當應用開啟 server_token_required = true 時必填。 |

::: info
如在控制台為該應用啟用了 server_token_required，驗證初始化 將拒絕所有未攜帶有效 server_token 的請求。
:::

## 錯誤碼

| 錯誤碼 | 說明 |
| --- | --- |
| `invalid_app_key` | App Key 無效 |
| `invalid_app_secret` | App Secret 無效 |
| `challenge_expired` | 驗證碼已過期 |
| `challenge_not_found` | 驗證碼不存在 |
| `invalid_answer` | 答案錯誤 |
| `token_expired` | Token 已過期 |
| `token_already_used` | Token 已被使用 |
| `token_not_found` | Token 不存在 |
| `quota_exceeded` | 配額已用盡 |
| `rate_limited` | 請求頻率超限 |
| `rate_limit_exceeded` | 該應用的簽發請求過於頻繁，請稍後再試。 |