DataDome 解決 API：datadome Cookie を REST で取得

SolveHub API で DataDome チャレンジを解決：チャレンジ URL とプロキシを送信し、タスクをポーリングして datadome Cookie を取得。同じ IP と User-Agent で再利用。フィールド、cURL、エラー。

許可された QA 自動化とブラウザー連携向けです。テスト権限のあるサイトと業務フローでのみ使用してください。

チャレンジが発生したページの websiteURL、完全な DataDome チャレンジ URL captchaUrl、および HTTP プロキシが必須です。captchaUrl はチャレンジページの URL であり、通常の対象ページの URL ではありません。このタイプではカスタムの useragent フィールドは受け付けません。

チャレンジ URL の構築（無料）

POST /v1/datadome/build-url を、有効な SolveHub API Key の tasks 権限と有効なアカウントで呼び出します。同期ツールであり、タスク作成、残高の仮押さえ、課金は行いません。websiteURL と、body（取得した HTML/JSON、最大1 MiB）、location、captchaUrl（後二者は各4096バイト）の少なくとも一つが必要です。指定済みの captchaUrl が優先されます。取得した内容を解析に渡し、その JavaScript をクライアント側で実行しないでください。

curl -sS -X POST 'https://www.tiam.codes/v1/datadome/build-url' \
  -H 'Authorization: Bearer sh_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  --data '{"websiteURL":"https://example.com/login","body":"{\"url\":\"https://geo.captcha-delivery.com/captcha/?cid=EXAMPLE\"}"}'

{"captchaUrl":"https://geo.captcha-delivery.com/captcha/?cid=EXAMPLE","challengeType":"captcha"}

応答は captchaUrl と challengeType（captcha または interstitial）です。URL を変更せず、以下の DataDome 解析タスクへ渡してください。解析タスクのみ現在の価格で仮押さえ・精算されます。同じセッションとプロキシ IP に属する新しいデータを使用してください。互換ルート POST /buildDataDomeUrl は JSON の clientKey に SolveHub Key を指定し、errorId 形式を返します。

ブラウザーの選択

任意の useragent で Chrome/Chromium または Firefox のファミリー、プラットフォーム、メジャーバージョンを選択できます。ノードにないバージョンを指定すると失敗します。省略時は既定のブラウザーを使用します。Cookie を再利用するときは、同じプロキシと実際に返却された solution.useragent を使用してください。

DataDome で useragent を省略すると既定のmacOSデスクトップChromeを使用し、バージョンはノードの更新に従います。

リクエストフィールド

外側の type と task は必須です。以下の task.* パスはすべて task オブジェクト内にあります。フィールド名は大文字と小文字が区別されます。長さの制限は UTF-8 のバイト数で計算されます。

フィールド	型	必須	制限	説明
`type`	文字列	はい	`datadome` 固定	プラットフォームのタスクタイプ。
`task`	JSON オブジェクト	はい	≤ 7 MiB	このタイプのタスクパラメータ。
`task.type`	文字列	いいえ	指定する場合は `datadome` であること	旧リクエスト形式との互換用。新規導入では省略できます。
`task.websiteURL`	HTTP(S) URL	はい	≤ 2048 バイト	解決対象ページの完全な URL。アカウント名やパスワードは含めません。
`task.captchaUrl`	HTTP(S) URL	はい	≤ 4096 バイト	完全なチャレンジページ URL。対象チャレンジのクエリパラメータは保持してください。
`task.useragent`	文字列	いいえ	≤ 512 バイト	ブラウザーの選択。Cookie は返却された `solution.useragent` と共に再利用してください。
`task.proxyType`	文字列	はい	`http` のみ	プロキシプロトコル。指定する場合は `http` である必要があります。
`task.proxyAddress`	文字列	はい	≤ 256 バイト	プロキシの IP またはホスト名。`proxyPort` と同時に指定する必要があります。
`task.proxyPort`	文字列	はい	1–5 バイト、数値 1–65535	プロキシのポート。引用符で囲んだ数字の文字列である必要があります。
`task.proxyLogin`	文字列	いいえ	≤ 256 バイト	プロキシに認証が必要な場合にユーザー名を指定します。アドレスとポートを指定せずに単独で指定することはできません。
`task.proxyPassword`	文字列	いいえ	≤ 256 バイト	プロキシに認証が必要な場合にパスワードを指定します。アドレスとポートを指定せずに単独で指定することはできません。

作成リクエストの例

{
  "type": "datadome",
  "task": {
    "websiteURL": "https://example.com/product",
    "captchaUrl": "https://example.com/captcha/?example=1",
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080"
  }
}

cURL での呼び出し

例に含まれるキー、サイト情報、プロキシを実際の値に置き換えてください。Idempotency-Key は同一の業務リクエストに対して変更しないでください。

curl -sS -X POST 'https://www.tiam.codes/v1/tasks' \
  -H 'Authorization: Bearer sh_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-datadome-0001' \
  --data-binary @- <<'JSON'
{
  "type": "datadome",
  "task": {
    "websiteURL": "https://example.com/product",
    "captchaUrl": "https://example.com/captcha/?example=1",
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080"
  }
}
JSON

作成レスポンスと照会

作成に成功すると HTTP 202 が返され、status の初期値は通常 queued です。taskId を保存し、約 2–3 秒ごとに GET /v1/tasks/{taskId} を呼び出して照会します。このタイプの処理のソフトタイムリミットは 240 秒 です。ソフトタイムリミットを超えると uncertain になる場合があります。受理済みタスクの結果は引き続き確認できるため、クライアントは新しい冪等キーで安易に再作成しないでください。

結果フィールド

solution は status=completed の場合にのみ読み取ってください。下表はよく使われるフィールドを示しています。実際のフィールドは該当タスクのレスポンスを正とします。

フィールド	型	読み取り方法
`solution.cookies`	オブジェクト	対象サイトの Cookie。一般的には `datadome` です。
`solution.useragent`	文字列	後続のリクエストでは、同じプロキシの送信元とあわせて使用する必要があります。

完了後、solution.cookies.datadome から Cookie を取得し、solution.useragent と同じプロキシを使用して対象にアクセスします。結果イメージ：{"cookies":{"datadome":"EXAMPLE_COOKIE"},"useragent":"Mozilla/5.0 ..."}。対象サイトの実際の captchaUrl は、実際のチャレンジフローから取得する必要があります。

失敗とトラブルシューティング

captchaUrl には現在のチャレンジの完全な URL を使用し、セッションのクエリパラメータを削除しないでください。Cookie が無効な場合は、同じプロキシの送信元と User-Agent を確認してください。

作成リクエストでよくあるエラーは 400 INVALID_TASK、402 INSUFFICIENT_BALANCE、429 TASK_LIMIT_EXCEEDED、503 TYPE_UNAVAILABLE です。作成済みタスクが失敗した場合の公開エラーコードは TASK_FAILED または TASK_TIMEOUT で、uncertain には TASK_UNCERTAIN が対応します。詳細はプラットフォーム API リファレンスを参照してください。

処理時間はタスク作成の受理確認後に起算し、待ち行列の時間は差し引きません。ノードの現在のタイムアウトは約210秒、プラットフォームのソフト期限は通信と結果確認を含め240秒です。

対応 User-Agent