Scarnox · Blog

captcha解決APIの仕組みと呼び出し方

captcha解決APIは、HTTPで呼び出すWebサービスです。captchaの詳細、つまりタスクの種類、ページのサイトキー、ページURLを送ると、対象のサイトが「チャレンジを通過した」証明として受け入れるトークンを返します。Scarnoxのエンドポイントはこの仕組みで、同期型です。1回のリクエストで答えが返ります。

このガイドでは、リクエスト、レスポンス、エラーの形式、そして本番環境で統合を安定させる詳細を扱います。まず実行できるスクリプトが必要なら、PythonでPopularCaptchaを解く方法から始めてください。

APIができることとできないこと

コードはページ上のcaptchaを見つけ、そのサイトキーを読み取ってソルバーに送ります。ソルバーはトークンを返します。コードはそのトークンをサイトが期待するフォームのフィールドに書き込み、フォームを送信します。

ソルバーはページを読み込まず、何もクリックせず、フォームを送信しません。トークンを生成するだけです。この境界を意識すると、統合全体が理解しやすくなります。セッション、Cookie、リクエストのタイミングは、すべてあなたのコードの側にあります。

現在ライブのタスクの種類は、PopularCaptcha（プロキシなし）のPopularCaptchaTaskProxylessのみです。他のcaptchaの種類は今後の予定です。どれがどれかはcaptchaの種類のガイドにまとめています。

エンドポイント

次のURLにPOSTリクエストを送ります。

POST https://api.scarnox.com/api/tasks/create
Authorization: Bearer scarnox_YOURAPIKEY
Content-Type: application/json

ボディでタスクを記述します。

{
  "captcha_type": "PopularCaptchaTaskProxyless",
  "site_key": "10000000-ffff-ffff-ffff-000000000001",
  "site_url": "https://example.com/signup"
}

必須フィールドは3つです。

任意のフィールドは3つあります。proxyはhttp://user:pass@host:portの形式の値を取り、プロキシのタスクの種類で使います。rqdataとis_invisibleは特定のウィジェットのバリエーション向けです。タスクの種類とフィールドの詳細な一覧はAPIリファレンスにあります。

同期型なのでポーリングは不要

呼び出しはトークンの準備ができるまでブロックされます。ポーリングは不要で、このフローに「結果を取得する」の2回目のリクエストはありません。HTTPクライアントのタイムアウトは約185秒に設定し、解決が遅くてもネットワークの失敗と誤認しないようにしてください。

Pythonのrequestsライブラリでは、次のようになります。

import requests

r = requests.post(
    "https://api.scarnox.com/api/tasks/create",
    headers={"Authorization": "Bearer scarnox_YOURAPIKEY"},
    json={
        "captcha_type": "PopularCaptchaTaskProxyless",
        "site_key": "10000000-ffff-ffff-ffff-000000000001",
        "site_url": "https://example.com/signup",
    },
    timeout=185,
)
data = r.json()

APIキーはスクリプトに直接書かず、環境変数から読み込んでください。ソースコードを読める人が、あなたの残高を使えてしまうべきではありません。

レスポンスの読み方

解決に成功すると、errorIdが0になり、solutionの中にトークン、そしてcostフィールドが返ります。

{"errorId": 0, "solution": {"token": "..."}, "cost": ...}

解決に失敗すると、errorIdは0以外になり、機械が読めるerrorCodeと人が読めるerrorDescriptionが付きます。

{"errorId": 1, "errorCode": "...", "errorDescription": "..."}

すべての呼び出しで、ボディのerrorIdを確認してください。HTTPリクエストが完了したからといって、トークンが得られたとは限りません。最も重要なルールは次のとおりです。課金されるのはerrorIdが0のときだけです。失敗した解決は無料です。現在の料金は料金ページを参照してください。

トークンの有効期限

PopularCaptchaのトークンは約2分で期限切れになります。トークンを受け取ったらすぐに送信してください。後で使うためにトークンをキャッシュしたり、フォームを送信するより前に解決したりしないでください。トークンを受け取ってからフォームを投稿するまでに複数の手順があるなら、解決は最後のタイミングに移してください。

トークンをフォームに入れる

多くのサイトは、PopularCaptchaのレスポンスをh-captcha-responseというフォームのフィールドから読み取ります。g-recaptcha-responseに同じ値を入れても受け付けるサイトも多いので、両方を送るのが一般的で安全な選択です。

requests.post("https://example.com/signup", data={
    "email": "you@example.com",
    "h-captcha-response": token,
    "g-recaptcha-response": token,
})

フォームがトークンを受け付けない場合、原因の多くは、サイトキーまたはページURLがウィジェットの実際のページと一致していないことです。ソルバーのせいにする前に、値を再確認してください。

エラー処理

本番環境で使う統合には、次の習慣が必要です。

より詳しい内容はcaptcha解決のエラー処理ガイドにあります。

はじめ方

アカウントを作成すると、無料のトライアルクレジットで始められます。カード登録は不要です。そのうえで、上のリクエストをテスト用の自分のページに対して実行し、フォームがトークンを受け付けることを確認してから、重要なものに接続してください。

次のステップ