---
title: APIリファレンス
---

# APIリファレンス

CaptchaLaはRESTful APIインターフェースを提供し、すべての機能のサーバー側呼び出しをサポートします。

## APIベースURL

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

## 認証方式

すべての API リクエストには認証ヘッダーが必要です:

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

ユーザーがフロントエンド CAPTCHA を通過した後、サーバーは 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
Validate `data.valid === true` **and** that `data.action` matches the scene you expected
(reject if a token from a `pay` flow is presented at `/login`). Tokens are single-use.
:::

## サーバー発行チャレンジトークン {#server-token}

バックエンドから短寿命の server_token を発行し、ブラウザが初期化時にそれを送信することで、リクエストが信頼できるサーバー由来であることを証明します。

### server_token を発行

自社サーバーからのみ呼び出し可能。X-App-Key と X-App-Secret が必要です。レスポンスに sct_ で始まる server_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` | トークン有効期間（秒）。デフォルト 300、最大 900。 |
| `max_uses` | 最大消費回数。デフォルト 10。 |
| `bind_ip` | 指定の IP にトークンを紐付け。 |
| `bind_device_id` | 指定のデバイス ID に紐付け。 |
| `bind_fingerprint` | 指定のブラウザ指紋に紐付け。 |

### チャレンジ初期化

SDK がチャレンジ開始時に呼び出します。/v1/server/challenge/issue で発行された server_token を任意で受け付けます。

| フィールド | 説明 |
| --- | --- |
| `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 の有効期限切れ |
| `challenge_not_found` | Challenge が見つかりません |
| `invalid_answer` | 不正な回答 |
| `token_expired` | Token の有効期限切れ |
| `token_already_used` | Token はすでに使用済みです |
| `token_not_found` | Token が見つかりません |
| `quota_exceeded` | クォータ超過 |
| `rate_limited` | レート制限 |
| `rate_limit_exceeded` | このアプリへの発行リクエストが多すぎます。時間を空けて再試行してください。 |