使用指南

本文说明 Devnors Data 开放数据 API 的计费规则、接入地址、身份认证、响应约定、超时与限流策略，以及 MCP 客户端接入方式。

计费说明

本服务按成功调用次数计费。单次调用消耗量由响应体字段 units 标明。各接口实时单价请登录后查阅：

定价说明 · 开发者控制台

新注册账户将获赠一定免费调用额度，可用于联调与验证。额度用尽后，须充值方可继续调用。

接入地址

数据查询统一入口为 POST /v1/data/query。生产环境地址如下：

环境	地址	说明
`prod`	`https://data.devnors.com/v1/data/query`	生产环境；请求须携带有效 Bearer API Key

请求体字段及示例见统一查询；各数据域能力说明见侧栏对应页面。

身份认证

调用方须在每一次请求的 HTTP 请求头中携带访问令牌（API Key）。密钥格式为 devnors_sk_live_…，创建时仅完整展示一次，请妥善保管：

Authorization: Bearer devnors_sk_live_xxxxxxxx

请于开发者控制台 · API 令牌创建密钥。尚未登录的用户请先完成登录或注册。

响应与错误处理

调用成功时，HTTP 状态码为 200，业务结果以 JSON 返回（含 hits、units、request_id 等字段）。调用失败时，响应保留顶层字段 detail，并附加下列结构化字段，供调用方程序化处理：

code：机器可读错误码
retryable：是否建议重试
next_action：建议处理步骤
docs_url：相关说明文档地址

成功响应示例

{
  "domain": "legal",
  "type": "case",
  "status": "ok",
  "units": 300,
  "request_id": "8f2c…e1",
  "hits": [ … ]
}

错误响应示例

{
  "detail": "无法验证凭据",
  "code": "unauthorized",
  "retryable": false,
  "next_action": "提供有效的 Authorization: Bearer …",
  "docs_url": "https://data.devnors.com/capabilities.json"
}

完整错误码表见错误码。下列情形不计费：参数错误（HTTP 400）、鉴权失败（HTTP 401）、数据域尚未开放（HTTP 501），以及取数失败后的自动退款。

超时设置

绝大多数请求可在数秒内返回。建议将客户端请求超时时间设置为 120 秒；若业务对时延有更严格要求，亦不应低于 60 秒，以免因短暂网络抖动导致结果未达却被判定为失败。

上述超时建议旨在降低误判与重复请求风险，并不表示接口常态响应达到该时长。

限流与配额

限流按 API Key 执行。超出限额时返回 HTTP 429（code=rate_limited），调用方须依据响应头 Retry-After 退避后重试。正常响应可通过 X-RateLimit-* 响应头查阅当前限额使用情况。

账户余额不足时返回 HTTP 402（insufficient_balance），请前往开发者控制台充值。同一账户下多个 API Key 共享账户余额。

MCP 客户端接入

本平台提供远程 MCP 服务端点，客户端无需安装 Python 运行时。WorkBuddy 等兼容 MCP 的应用，可在其配置文件中声明远程服务后调用数据工具。具体步骤与配置示例见 SDK 与 MCP。

{
  "mcpServers": {
    "devnors-data": {
      "type": "http",
      "url": "https://data.devnors.com/mcp",
      "headers": {
        "Authorization": "Bearer devnors_sk_live_…"
      }
    }
  }
}

技术支持

如遇对接、能力咨询或定制需求，请登录后在控制台 · 反馈意见提交，或通过页脚联系方式联系我们。机器可读能力清单见机器可读。