---
title: API 参考
---

# API 参考

CaptchaLa 提供 RESTful API 接口，支持所有功能的服务端调用。

## API 地址

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

## 认证方式

所有 API 请求需要在 Header 中携带认证信息：

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

::: warning
`X-App-Secret` is server-side only. Never expose it to browsers, mobile apps, or public repos.
:::

## 服务端验证 API

> 💡 **用服务端 SDK 省去 boilerplate。** 封装端点 + 重试 + 类型化错误:
> - **PHP** — [`Captcha-La/captchala-php`](https://github.com/Captcha-La/captchala-php)
> - **Go** — `go get github.com/Captcha-La/captchala-go` · [README](https://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
    }
  }
}
```

::: tip
校验 `data.valid === true` **并且** `data.action` 与你期望的场景一致(`pay` 流程的
token 出现在 `/login` 应拒绝)。Token 单次有效。
:::

::: info captcha_args
`captcha_args` 回显解题**当时**记录的上下文,供日志 / 你自己的二次风控:

- `platform` — `web` / `android` / `ios` / `flutter` / `windows` / …
- `user_ip` — 解题时看到的终端用户 IP
- `referer` — 解题页面 URL(web);native 为 `null`
- `pkg` — app 包名 / bundle id(native);web 为 `null`
- `solved_at` — 解题完成时间(unix 秒)
- `risk_score` — 解题时风险分(0-100,越高越可疑)
:::

## 服务端签发验证 Token {#server-token}

由您的服务端签发短时效 server_token，再由浏览器在初始化挑战时携带该 Token，从而证明请求来自受信任的服务端。

### 签发 server_token

仅允许从您的服务端调用。需要 X-App-Key + X-App-Secret。响应返回 server_token（前缀 sct_），前端需在 验证初始化 时带上该 Token。

```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` | 该应用的签发请求过于频繁，请稍后重试。 |