APIリファレンス

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

APIベースURL

https://apiv1.captcha.la

ベース URL は 1 つだけ

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

認証方式

すべての 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
• Go — go get github.com/Captcha-La/captchala-go

ユーザーがフロントエンド CAPTCHA を通過した後、サーバーは SDK が返した token を検証する必要があります。以下はサーバー側の検証エンドポイントです。

サーバー側 Token 検証

フロントエンド SDK が返した pass_token（pt_ プレフィックス）を検証します。X-App-Key と X-App-Secret ヘッダーが必要です。

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 で、追加のリスクチェックに使われます。省略しても問題ありません。

{
  "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 を発行

自社サーバーからのみ呼び出し可能。X-App-Key と X-App-Secret が必要です。レスポンスに sct_ で始まる server_token が返ります。

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

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

オフラインフォールバック用エンドポイント

メイン 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)

{ "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 を利用してください(オフラインフォールバック用エンドポイント)。