Open API v1

API 接入文档

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

认证方式

所有 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 URL	https://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.10"
  }
}

单条查询

POST/open/v1/query/single

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

请求参数

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

请求示例

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 有错误信息

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.10"
  }
}

响应示例（查询失败）

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

批量查询

POST/open/v1/query/batch

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

请求参数

参数	类型	必填	说明
taskName	string	否	任务名称，便于识别
companies	string[]	是	企业名称列表，最多 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 值	含义
PENDING	排队中
PROCESSING	执行中
COMPLETED	全部完成
FAILED	任务失败

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

错误码

HTTP 状态码	code	说明
200	200	成功
401	401	API Key 无效或未传
400	400	请求参数错误
402	402	余额不足，请充值
404	404	任务不存在或无权访问
500	500	服务器内部错误

代码示例

完整示例覆盖单条查询、批量查询、余额查询三个场景，支持 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"