Open API v1

API 接入文档

通过 RESTful API 将中登查询能力集成到您的业务系统，支持单条查询、批量任务、结果导出。

获取 API Key

认证方式

所有 Open API 请求需在 HTTP Header 中携带 X-Api-Key。 API Key 格式为 zdsk_xxxxxxxx...， 在控制台「设置 → 开发者」中创建。

curl -X POST https://api.zdwai.com/api/open/v1/query/single \
  -H "X-Api-Key: zdsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"companyName": "示例科技有限公司"}'
API Key 具有账户完整权限，请勿泄露或提交到代码仓库。如有泄露请立即在控制台删除并重新创建。

基础信息

Base URLhttps://api.zdwai.com/api
协议HTTPS
数据格式JSON (application/json)
字符编码UTF-8
认证方式X-Api-Key Header
并发限制10 个并发请求
建议超时60 秒（单条查询最长约 30 秒）
轮询间隔建议 3 秒

响应格式

所有接口统一返回 JSON，结构如下：

{
  "code": 200,
  "msg": "success",
  "data": { ... }
}

错误响应示例

{
  "code": 401,
  "msg": "API Key 无效或未传",
  "data": null
}

余额查询

GET/open/v1/account/balance

查询当前账户余额、冻结金额及当前计费档位。

curl https://api.zdwai.com/api/open/v1/account/balance \
  -H "X-Api-Key: zdsk_your_api_key_here"

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "balance": "98.50",
    "frozenAmount": "1.50",
    "pricePlan": "标准版",
    "unitPrice": "0.20"
  }
}

单条查询

POST/open/v1/query/single

提交单条企业名称查询，立即返回任务 ID。查询为异步执行，需轮询状态接口获取结果。

请求参数

参数类型必填说明
companyNamestring是企业全称，如"示例科技有限公司"

请求示例

curl -X POST https://api.zdwai.com/api/open/v1/query/single \
  -H "X-Api-Key: zdsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"companyName": "示例科技有限公司"}'
GET/open/v1/query/single/{taskId}

轮询单条查询状态，建议间隔 3 秒。

status 值含义
PENDING排队中
PROCESSING查询中
SUCCESS查询成功，resultData 有数据
FAILED查询失败，errorMsg 有错误信息
WAITING_RETRY等待重试
curl https://api.zdwai.com/api/open/v1/query/single/10086 \
  -H "X-Api-Key: zdsk_your_api_key_here"

响应示例（查询成功）

{
  "code": 200,
  "data": {
    "taskId": 10086,
    "status": "SUCCESS",
    "matchCount": 3,
    "resultData": "[{...}]",
    "cost": "0.20"
  }
}

响应示例（查询失败）

{
  "code": 200,
  "data": {
    "taskId": 10086,
    "status": "FAILED",
    "matchCount": null,
    "cost": "0.00",
    "errorMsg": "未查询到该企业的登记信息"
  }
}

批量查询

POST/open/v1/query/batch

提交批量查询任务，一次最多支持 1000 条企业名称。

请求参数

参数类型必填说明
taskNamestring否任务名称，便于识别
companiesstring[]是企业名称列表，最多 1000 条

请求示例

curl -X POST https://api.zdwai.com/api/open/v1/query/batch \
  -H "X-Api-Key: zdsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "taskName": "2026年2月批次",
    "companies": [
      "示例科技有限公司",
      "测试贸易有限公司"
    ]
  }'

响应示例

{
  "code": 200,
  "data": {
    "id": 2001,
    "taskNo": "BQ20260221001",
    "totalCount": 2,
    "status": "PENDING",
    "frozenAmount": "0.40",
    "createdAt": "2026-02-21T10:00:00"
  }
}
GET/open/v1/query/batch/{taskId}

查询批量任务进度，progress 为 0-100 的整数，100 表示完成。

status 值含义
CREATED已创建，尚未开始处理
PENDING排队中
PROCESSING执行中
COMPLETED全部完成
PARTIAL_FAILED部分成功，failCount > 0
FAILED任务失败
CANCELLED已取消
WAITING_RETRY等待重试
curl https://api.zdwai.com/api/open/v1/query/batch/2001 \
  -H "X-Api-Key: zdsk_your_api_key_here"
GET/open/v1/query/batch/{taskId}/export

任务完成后下载 Excel 结果文件，响应为二进制流（application/octet-stream）。

curl https://api.zdwai.com/api/open/v1/query/batch/2001/export \
  -H "X-Api-Key: zdsk_your_api_key_here" \
  -o result.xlsx

企业核查

提交企业名称或个人姓名，系统自动访问多个权威网站进行诚信核查， 返回风险判断结果及全页截图，按次计费。支持企业核查和个人核查两种模式。

GET/open/v1/check/sites

获取当前可用的核查站点列表，按分类分组返回。提交核查前可先调用此接口获取有效的 siteKey。

查询参数

参数类型必填说明
queryTypestring否查询类型："company"（企业，默认）或 "person"（个人），返回对应类型支持的站点

请求示例

curl "https://api.zdwai.com/api/open/v1/check/sites?queryType=company" \
  -H "X-Api-Key: zdsk_your_api_key_here"

响应示例

{
  "code": 0,
  "data": [
    {
      "categoryCode": "FZ001",
      "categoryName": "基础诚信核查",
      "sites": [
        { "siteKey": "zhixing", "siteName": "中国执行信息公开网（执行）", "siteUrl": "http://zxgk.court.gov.cn/zhixing/" },
        { "siteKey": "shixin", "siteName": "中国执行信息公开网（失信）", "siteUrl": "http://zxgk.court.gov.cn/shixin/" }
      ]
    },
    {
      "categoryCode": "FZ004",
      "categoryName": "司法诉讼核查",
      "sites": [
        { "siteKey": "wenshu", "siteName": "中国裁判文书网", "siteUrl": "https://wenshu.court.gov.cn/" }
      ]
    }
  ]
}
POST/open/v1/check

提交核查任务，立即返回任务 ID。核查为异步执行，需轮询状态接口获取结果。

请求参数

参数类型必填说明
subjectNamestring是查询主体名称，企业核查填企业全称，个人核查填姓名
queryTypestring是查询类型："company"（企业）或 "person"（个人）
idCardstring否身份证号码，个人核查时必填
siteKeysstring[]是目标网站列表，通过 GET /sites?queryType= 获取可用站点
siteKey网站名称域名
zhixing中国执行信息公开网（执行）zxgk.court.gov.cn
shixin中国执行信息公开网（失信）zxgk.court.gov.cn
wenshu中国裁判文书网wenshu.court.gov.cn
creditchina_fengzheng信用中国creditchina.gov.cn
chinatax国家税务总局chinatax.gov.cn

请求示例

curl -X POST https://api.zdwai.com/api/open/v1/check \
  -H "X-Api-Key: zdsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectName": "示例科技有限公司",
    "queryType": "company",
    "siteKeys": ["zhixing", "shixin", "wenshu", "creditchina_fengzheng"]
  }'

响应示例（提交成功）

{
  "code": 0,
  "data": {
    "id": 3001,
    "subjectName": "示例科技有限公司",
    "queryType": "company",
    "idCard": null,
    "status": "PENDING",
    "amountFrozen": 0.40,
    "amountCharged": null,
    "items": [
      { "id": 1, "siteKey": "zhixing",                "siteName": "中国执行信息公开网（执行）", "status": "PENDING" },
      { "id": 2, "siteKey": "shixin",                 "siteName": "中国执行信息公开网（失信）", "status": "PENDING" },
      { "id": 3, "siteKey": "wenshu",                 "siteName": "裁判文书网",               "status": "PENDING" },
      { "id": 4, "siteKey": "creditchina_fengzheng",  "siteName": "信用中国",                 "status": "PENDING" }
    ],
    "createdAt": "2026-02-22T10:00:00"
  }
}
GET/open/v1/check/{taskId}

轮询核查任务状态，建议间隔 5 秒。

任务 status含义
PENDING排队中
PROCESSING核查中
COMPLETED全部完成，items 中有结果
FAILED核查失败，余额已全额解冻
item status含义
PENDING排队中
SUCCESS成功，hasRecords / recordCount / screenshotUrl 有值
FAILED访问失败，errorMsg 有错误信息
CAPTCHA验证码拦截，需重试
TIMEOUT访问超时，需重试
curl https://api.zdwai.com/api/open/v1/check/3001 \
  -H "X-Api-Key: zdsk_your_api_key_here"

响应示例（核查完成）

{
  "code": 0,
  "data": {
    "id": 3001,
    "subjectName": "示例科技有限公司",
    "queryType": "company",
    "idCard": null,
    "status": "COMPLETED",
    "amountFrozen": 0.40,
    "amountCharged": 0.40,
    "items": [
      {
        "id": 1,
        "siteKey": "zhixing",
        "siteName": "中国执行信息公开网（执行）",
        "siteUrl": "http://zxgk.court.gov.cn/zhixing/",
        "status": "SUCCESS",
        "hasRecords": true,
        "recordCount": 2,
        "riskSummary": "发现2条执行记录",
        "screenshotUrl": "/open/v1/check/3001/items/1/screenshot",
        "errorMsg": null
      },
      {
        "id": 2,
        "siteKey": "shixin",
        "siteName": "中国执行信息公开网（失信）",
        "siteUrl": "http://zxgk.court.gov.cn/shixin/",
        "status": "SUCCESS",
        "hasRecords": false,
        "recordCount": 0,
        "riskSummary": "未发现裁判文书",
        "screenshotUrl": "/open/v1/check/3001/items/2/screenshot",
        "errorMsg": null
      }
    ],
    "createdAt": "2026-02-22T10:00:00"
  }
}
GET/open/v1/check/{taskId}/items/{itemId}/screenshot

获取指定网站的全页截图，响应为二进制流（image/png）。 截图 URL 可直接从轮询结果的 screenshotUrl 字段获取。

curl https://api.zdwai.com/api/open/v1/check/3001/items/1/screenshot \
  -H "X-Api-Key: zdsk_your_api_key_here" \
  --output screenshot.png
POST/open/v1/check/{taskId}/items/{itemId}/retry

重试单个失败的核查项。仅当 item 状态为 FAILED、CAPTCHA 或 TIMEOUT 时可调用， 会重新冻结 1 次核查费用并异步重新执行。

路径参数

参数类型必填说明
taskIdnumber是核查任务 ID
itemIdnumber是核查项 ID

请求示例

curl -X POST https://api.zdwai.com/api/open/v1/check/3001/items/1/retry \
  -H "X-Api-Key: zdsk_your_api_key_here"

成功返回 {"code": 0, "data": null}，重试完成后通过轮询接口查看更新后的结果。

错误码

HTTP 状态码code说明
200200成功
401401API Key 无效或未传
400400请求参数错误
402402余额不足，请充值
404404任务不存在或无权访问
500500服务器内部错误

代码示例

完整示例覆盖单条查询、批量查询、余额查询三个场景，支持 curl / Java / Python / Node.js。

单条查询（提交 + 轮询）

# 1. 提交单条查询
curl -X POST https://api.zdwai.com/api/open/v1/query/single \
  -H "X-Api-Key: zdsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"companyName": "示例科技有限公司"}'

# 2. 轮询状态（间隔 3 秒）
curl https://api.zdwai.com/api/open/v1/query/single/10086 \
  -H "X-Api-Key: zdsk_your_api_key_here"

批量查询（提交 + 轮询 + 下载 Excel）

# 1. 提交批量任务
curl -X POST https://api.zdwai.com/api/open/v1/query/batch \
  -H "X-Api-Key: zdsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"taskName":"2026年2月批次","companies":["示例科技有限公司","测试贸易有限公司"]}'

# 2. 轮询进度
curl https://api.zdwai.com/api/open/v1/query/batch/2001 \
  -H "X-Api-Key: zdsk_your_api_key_here"

# 3. 下载 Excel
curl https://api.zdwai.com/api/open/v1/query/batch/2001/export \
  -H "X-Api-Key: zdsk_your_api_key_here" -o result.xlsx

余额查询

curl https://api.zdwai.com/api/open/v1/account/balance \
  -H "X-Api-Key: zdsk_your_api_key_here"