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

# APIリファレンス

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

## APIベースURL

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

::: warning ベース URL は 1 つだけ
このページのすべてのエンドポイントは `apiv1.captcha.la` にあります。スタンバイ用ホスト(`bypass.*` / `fallbackapiv1.*`)は障害時に SDK が自動で切り替えるフェイルオーバー先です。連携先をそこに向けると [`service_online`](#offline-fallback) が返ります。
:::

## 認証方式

すべての 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 を持たないリクエストを拒否します。
:::

## オフラインフォールバック用エンドポイント {#offline-fallback}

メイン API に到達できない間も検証を継続できるよう、CaptchaLa は別ホスト上でスタンバイサービスを運用しています。

| ホスト | 呼び出し元 | 役割 |
| --- | --- | --- |
| `bypass.captchala.com` · `bypass.captcha-cdn.net` | Web / ネイティブ SDK(エンドユーザー側) | メイン API 停止中にオフライン検証を行い `offline_` pass token を発行 |
| `fallbackapiv1.captchala.com` · `fallbackapiv1.captcha-cdn.net` | サーバー SDK | `offline_` トークンの検証(`POST /api/validate`) |

**これらはフェイルオーバー先であり、代替 API ではありません。** SDK はメイン API が実際に失敗した後にのみ自動で切り替え、復旧すれば自動で戻ります。お客様の設定がこれらのホストを指すことはありません。

### `service_online`(HTTP 503)

```json
{ "code": -1, "error": "service_online", "message": "Main API is online, please use main API" }
```

メイン API が正常なうちはこのエラーになります。スタンバイサービスは障害中しか動きません。リクエストが `https://apiv1.captcha.la` ではなく `bypass.*` に届いているので、URL を直してください(再試行しても解決しません)。

よくある原因:

| 原因 | 対処 |
| --- | --- |
| SDK の `apiServer` に bypass ホストを指定している | `https://apiv1.captcha.la` に戻すか、オプション自体を外して SDK に選ばせる |
| `bypassServers` を手動で上書きしている | 指定を受けていない限り上書きを外す |
| 自作 HTTP クライアントが bypass URL をコピーしている(障害時に devtools から等) | `https://apiv1.captcha.la` を呼び、フェイルオーバーは SDK に任せる。スタンバイは通常のチャレンジ通信を受け付けません |
| ロードバランサー / プロキシ / DNS が API ホストを書き換えている | アップストリームを `apiv1.captcha.la` に戻す |

::: tip
サーバー側検証でもフォールバックホストは不要です。`apiv1.captcha.la` の `POST /v1/validate` を呼べばよく、`offline_` トークンは PHP / Go のサーバー SDK が自動でバックアップ API に問い合わせます。
:::

## エラーコード

| コード | 説明 |
| --- | --- |
| `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` | このアプリへの発行リクエストが多すぎます。時間を空けて再試行してください。 |
| `service_online` | メイン API が稼働中にオフラインフォールバックサービスへリクエストが届いた。`https://apiv1.captcha.la` を利用してください([オフラインフォールバック用エンドポイント](#offline-fallback))。 |