DataDome 识别 API：获取 datadome Cookie

通过 SolveHub API 解决 DataDome 验证：提交挑战 URL 与代理，轮询任务获得 datadome Cookie，配合相同 IP 与 User-Agent 使用。字段、cURL 与错误码。

适用于授权自动化测试、风控 QA 与浏览器集成。请仅在有权测试的站点和业务流程中使用。

必填触发挑战的页面 websiteURL、完整的 DataDome 挑战地址 captchaUrl 和 HTTP 代理。captchaUrl 是挑战页 URL，不是普通目标页面 URL；本类型不接受自定义 useragent 字段。

构建挑战 URL（免费）

使用 POST /v1/datadome/build-url，携带具有 tasks 权限的有效 SolveHub API Key。账户须处于可用状态；该工具不创建任务、不预占余额、不扣费。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 的浏览器家族、平台及具体主版本。目标节点没有指定版本时任务会失败；省略时使用默认浏览器。后续访问应使用相同代理及结果中的 solution.useragent，不要仅按传入字符串重放 Cookie。

省略 useragent 时，DataDome 使用默认 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 调用

把示例中的 Key、站点信息与代理替换为你的实际值；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，有已受理任务的结果可继续核对，客户端不要用新幂等键盲目重建。

结果字段

只在 status=completed 时读取 solution；下表列出常用字段，实际字段以该任务响应为准。

字段	类型	读取方式
`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

DataDome 识别 API：获取 datadome Cookie

构建挑战 URL（免费）

浏览器选择

请求字段

创建请求示例

cURL 调用

创建响应与查询

结果字段

失败与排查

相关文档