数易产 API v1 · 接入文档
快速开始
三个动作即可跑通：拿 Key → 发请求 → 看返回。全部接口走 HTTPS，返回 JSON，统一结构 {"code":0,"data":…,"message":"…"}。
① 查企业主体（把 sk-syc-你的Key 换成你自己的 Key）
curl -s "https://www.shuyichan.com/api/open/v1/entity/list?keyword=重庆&page=1&page_size=3" \
-H "Authorization: Bearer sk-syc-你的Key"
# → {"code":0,"data":{"list":[{"uscc":"91500108MA5U74P286","name":"…"}],"total":1,"page":1,"page_size":3}}② 查三段数据资产漏斗
curl -s "https://www.shuyichan.com/api/open/v1/stats/three-stage" \
-H "Authorization: Bearer sk-syc-你的Key"
# → {"code":0,"data":{"funnel":{"collect":136,"process":…,"commercial":…,"rate_process":…}}}③ Python（官方 SDK 同款调用）
import requests
KEY = "sk-syc-你的Key"
BASE = "https://www.shuyichan.com/api/open/v1"
H = {"Authorization": f"Bearer {KEY}"}
r = requests.get(f"{BASE}/asset/list", headers=H,
params={"page": 1, "page_size": 20}, timeout=15)
# 429 = 超出配额，按响应头 Retry-After 秒数重试
data = r.json()
print(data["data"]["total"], len(data["data"]["list"]))④ TypeScript / Node（零依赖）
const KEY = "sk-syc-你的Key";
const BASE = "https://www.shuyichan.com/api/open/v1";
async function listEntities(keyword = "") {
const url = `${BASE}/entity/list?page=1&page_size=20&keyword=${encodeURIComponent(keyword)}`;
const res = await fetch(url, { headers: { Authorization: `Bearer ${KEY}` } });
if (res.status === 429) throw new Error(`配额超限，${res.headers.get("Retry-After")} 秒后重试`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return res.json();
}返回 code=0 即接通。没有 Key？先到接入申请页申请（AI 数字员工即时审核）。
这是某次真实调用的返回值快照，只用于说明字段形态与量级。要实时数据请申请 Key（接入申请页，AI 数字员工即时审核）。
上面三张卡是 沙箱演示租户的实时数据（不是快照）。想自己建资产、看漏斗变化，点页头「在线试一下」。
鉴权
所有接口统一用 API Key，放在请求头，不要放 URL 参数：
Authorization: Bearer sk-syc-xxxxxxxxxxxxxxxx- Key 前缀固定
sk-syc-，服务端只存哈希，明文只在创建时显示一次。 - Key 绑定企业租户：返回数据受该租户权限约束，跨租户一律不可见（
40300）。 - 泄露或人员变动：联系平台撤销并重发（撤销后旧 Key 立即失效）。
接口清单
v1 契约冻结，改版走 v2 且不破坏存量。所有接口为 GET，基址 https://www.shuyichan.com/api/open/v1。
| 接口 | 路径 | 查询参数 | 用途 |
|---|---|---|---|
| 企业主体 | /entity/list | keyword page page_size | 按名称 / 信用代码模糊查主体，返回工商信息 |
| 资产清单 | /asset/list | category subject_id status keyword page page_size | 查七大类资产台账 |
| 关系图谱 | /graph/relation | root_id root_type（subject / controller / asset） | 实控人 → 主体 → 资产的穿透关系 |
| 三段漏斗 | /stats/three-stage | all（true = 全平台口径） | 采集 → 加工 → 商业化的数量、金额、转化率 |
分页：page 从 1 开始，page_size 默认 20、上限 100；超出范围按默认值处理，不报错。
字段字典
1. 主体对象 data.list[]（/entity/list）
| 字段 | 类型 | 含义 |
|---|---|---|
id | string(uuid) | 主体主键，用于关系图谱 root_id |
uscc | string(18) | 统一社会信用代码（唯一业务键） |
name | string | 企业名称 |
entity_type | string | 企业类型：有限责任公司 / 股份有限公司 / 个人独资企业 / 合伙企业 / 一人公司 / 集团 |
legal_person | string | 法定代表人 |
registered_capital | number | 注册资本（配合 capital_currency） |
established_date | date | 成立日期 |
reg_status | string | 登记状态：存续 / 注销 / 吊销 / 迁出 |
abnormal_status | string | 经营异常名录：无 / 列入 / 移出 |
admin_penalty · judicial_risk | string | 行政处罚 / 司法风险：无 / 有 |
business_scope | string | 经营范围（长文本） |
列表外层：data.total 总数、data.page、data.page_size 回显分页。
2. 资产对象 data.list[]（/asset/list）
| 字段 | 类型 | 含义 |
|---|---|---|
asset_code | string | 资产编码（唯一） |
asset_name | string | 资产名称 |
asset_category | string | 资产大类：有形 / 无形 / 数据 / 数字 / 人力组织 / 要素 / 在途 |
asset_class_code | string | 国标分类码（GB/T 14885-2022、GB/T 47949-2026） |
right_type | string | 权利类型，默认「持有权」 |
cost_value · book_value · market_value | number | 成本价 / 账面价 / 市场价（可能缺省） |
currency | string | 币种，默认 CNY |
lifecycle_stage | string | 生命周期阶段，默认「采集」 |
status | string | 资产状态（如 待采集 / 已确权 / 已入表），可作查询参数 |
subject_id | string(uuid) | 所属主体 |
3. 图谱对象 data（/graph/relation）
| 字段 | 类型 | 含义 |
|---|---|---|
nodes[] | array | 节点：id 主键、type（subject / controller / asset）、name 显示名 |
edges[] | array | 关系边：from、to（形如 subject:<id>）、relation（控股 / 实控 / 归属等） |
root_type · root_id | string | 回显本次根节点 |
hint | string | 该租户尚无主体时返回空图谱 + 引导文案（非错误） |
4. 漏斗对象 data（/stats/three-stage）
| 字段 | 含义 |
|---|---|
collect | 采集段：subjects 主体数、assets 资产数、total |
process | 加工段：confirmed 已确权、registered 已登记、accounted 已入表、elements 数据要素、total；confirmed_untimed / accounted_untimed 为「状态已达但发生时间缺失」的历史行数 |
commercial | 商业化段：pledges 质押、custodies 保管、lawsuits 诉讼、insurances 保险、disposals 处置、total；amount＝质押+处置总额，另有 5 个 *_amount 分项金额 |
funnel | 三段汇总：collect / process / commercial 与 rate_process、rate_commercial 转化率 |
mom | 环比数据（按有时间戳的行统计） |
错误码
非 0 即失败，message 给出原因。下表按「你该做什么」分三类：
| code | 含义 | 你该做什么 |
|---|---|---|
0 | 成功 | — |
40000 | 参数错误 | 对照上方参数表检查名称 / 取值 / 范围 |
40100 | 未授权（缺 Key / Key 无效） | 检查 Authorization: Bearer sk-syc-…；Key 被撤销则重新申请 |
40300 | 禁止访问（跨租户） | 目标数据不属于你的租户 |
40400 | 资源不存在 | 检查 ID / 路径 |
40900 | 冲突（重复提交） | 勿重复提交同一对象 |
42900 | 请求过频（限流） | 降速或按 Retry-After 退避；需更高配额联系平台 |
50000 | 服务端内部错误 | 稍后重试；持续出现请联系平台并附 request id |
已知差异：部分公开申请接口在参数错误时直接返回 HTTP 400（body 结构不变），与 40000 同一语义、两种载体。
限流与配额
默认单 Key 有速率上限；具体档位以开通时告知为准，商用配额与计费按合同约定。
| 档位 | 速率 | 日上限 | 适用 |
|---|---|---|---|
| 个人试用 | 20 次/分 | 2000 次/日 | 体验、原型验证 |
| 企业付费 | 200 次/分 | 5 万次/日 | 生产级接入 |
| 交易所伙伴 | 1000 次/分 | 50 万次/日 | 按合作约定 |
超限统一返回 42900；建议客户端做指数退避，勿紧循环重试。
定价与计费
开放平台按 Key 档位划分配额与计费口径。当前处于「计量不计费」阶段——调用会被计量并写入用量台账，但不扣费（用量页会明确标注）。企业档与伙伴档请联系商务开通。
| 档位 | 适用对象 | 限流（每 Key） | 计费口径 | 如何获得 |
|---|---|---|---|---|
| individual 个人 | 试用 / 个人开发者 | 20 次/分钟 · 2000 次/日 | 计量不计费 | 自助创建即可 |
| enterprise 企业 | 企业系统对接 | 200 次/分钟 · 5 万次/日 | 计量不计费（后续按量计费，单价待发布） | 企业管理员在控制台提交《升企业档申请》，审批通过后可自建 |
| partner 伙伴 | 渠道 / 交易所 / 集成商 | 1000 次/分钟 · 50 万次/日 | 年费 + 分成（商务签署） | 仅平台运营开通，联系商务 |
配额优先级：单 Key 自定义配额 > 档位默认配额；后台可调。超额返回 429 并带 Retry-After。计费一旦开通，会提前 30 天在本页与站内公告同步。
沙箱：14 天免费试用
目标读者：想先跑通再签约的开发者、售前演示、内部技术验证。 沙箱走的是真实接口、真实数据库，数据落在独立租户里，不会碰到任何生产数据；到期自动失效，无需解约。
1. 三分钟接入
① 凭邮箱自助开通（同邮箱 7 天内只发 1 把，Key 有效期 14 天）
curl -s -X POST "https://www.shuyichan.com/api/open/sandbox" \
-H "Content-Type: application/json" \
-d '{"email":"you@example.com","purpose":"技术验证"}'
# → {"code":0,"data":{"api_key":"sk-syc-sbx-…","expires_at":"…","limits":{…}}}
# ⚠️ 明文 Key 只在本次返回，请立即保存② 用 Key 调只读接口（与正式接口完全一致）
curl -s "https://www.shuyichan.com/api/open/v1/asset/list?page=1&page_size=20" \
-H "Authorization: Bearer sk-syc-sbx-你的Key"
# → {"code":0,"data":{"list":[…20 条演示资产…]}}③ 写入自己的数据（一个入口覆盖 8 张表，见下节参数说明）
curl -s -X POST "https://www.shuyichan.com/api/open/sandbox/write" \
-H "Authorization: Bearer sk-syc-sbx-你的Key" \
-H "Content-Type: application/json" \
-d '{"table":"enterprise_asset","op":"insert","data":{"asset_code":"MY-001","asset_name":"我的数据资产","asset_category":"数据","subject_id":"<主体id>","status":"已入表"}}'
# → {"code":0,"data":{"id":"…","affected":1}}2. 接口清单
| 接口 | 方法 | 鉴权 | 用途 |
|---|---|---|---|
/api/open/sandbox | POST | 无 | 凭邮箱自助开通，返回 Key（仅一次） |
/api/open/v1/entity/list | GET | 沙箱 Key | 只读：企业主体列表 |
/api/open/v1/asset/list | GET | 沙箱 Key | 只读：资产列表（page_size ≤ 100） |
/api/open/v1/graph/relation | GET | 沙箱 Key | 只读：主体—资产关系图谱 |
/api/open/v1/stats/three-stage | GET | 沙箱 Key | 只读：三段漏斗统计 |
/api/open/sandbox/write | POST | 沙箱 Key | 写入：8 张表增/改/删（软删） |
/api/open/sandbox/reset | POST | 沙箱 Key | 清空自己写入的数据（保留演示种子） |
/api/open/demo/call | POST | 无 | 官网「在线试一下」用的只读代理，限 3 个 tool |
3. 写入参数说明
| 字段 | 类型 | 说明 |
|---|---|---|
table | string | 必须在白名单内（下表 8 张之一） |
op | string | insert / update / delete（delete 为软删） |
data | object | insert/update 的业务字段；只接受白名单列，其余静默忽略 |
id | uuid | update / delete 必填 |
可写的 8 张表（必填列）：
| 表 | 用途 | 必填列 |
|---|---|---|
enterprise_basic_info | 企业主体 | uscc、name |
enterprise_asset | 资产 | asset_code、asset_name、asset_category、subject_id |
enterprise_data_element | 数据要素 | uscc、name |
enterprise_asset_pledge | 质押 | uscc、pledge_no、pledgee |
enterprise_asset_pledge_item | 质押明细 | uscc、pledge_id、asset_id、asset_type |
enterprise_asset_disposal | 处置 | uscc、asset_id |
enterprise_asset_custody | 托管 | uscc、asset_id |
enterprise_asset_lawsuit | 诉讼 | uscc、case_no |
⚠️ 审核字段不可写：ai_review_* 与 final_review_* 一律不开放（沙箱不能自审自过）。
关联字段（subject_id / asset_id / pledge_id / uscc）会校验是否真实存在于沙箱，不存在直接 400。
4. 沙箱限制（真实值，非"以合同为准"）
| 项 | 上限 | 超限返回 |
|---|---|---|
| Key 有效期 | 14 天 | 401 / 40100 |
| 同邮箱开通 | 7 天 1 把 | 429 / 42900 |
| 读：单页条数 | ≤ 50 | 400 / 40000 |
| 读：日累计 | 200 条 / 日 | 429 / 42900 |
| 写：次数 | 100 次 / 日 | 429 / 42900 |
| 删：次数 | 30 次 / 日 | 429 / 42900 |
| 重置（reset） | 3 次 / 日（按北京时间 00:00 复位） | 429 / 42900 |
5. 沙箱常见错误
| 错误信息 | 原因 | 怎么办 |
|---|---|---|
| 缺少必填字段：asset_code | insert 缺必填列 | 按上表补齐 |
| 字段 loan_amount 不能为负数 | 数值越界 | 传 ≥ 0 的数字 |
| 字段 filing_date 日期格式应为 YYYY-MM-DD | 日期格式错 | 改成 2026-10-19 |
| subject_id 指向的 enterprise_basic_info 不存在于沙箱 | 引用对象不存在 | 先建主体，再用返回的 id |
| uscc=… 在沙箱中不存在，请先创建该主体 | 同上 | 先建主体 |
| 种子演示数据不可修改/删除 | 改到了系统种子 | 只改自己创建的数据 |
| 该表不允许沙箱写入 | 表不在白名单 | 用上表 8 张 |
6. FAQ
Q：沙箱数据会影响生产吗？
A：不会。沙箱是独立租户，读写都带租户隔离（RLS），看不到也无法触碰任何客户数据。
Q：沙箱有演示数据吗？
A：有。开通即有 5 家演示主体 / 20 条演示资产 / 3 条数据要素，可直接看到三段漏斗数字；你自己写入的数据会叠加在上面。
Q：reset 会把演示数据也删掉吗？
A：不会。reset 只清空你自己创建的数据，演示种子会保留，方便反复演示。
Q：能改成生产 Key 吗？
A：沙箱 Key 前缀是 sk-syc-sbx-，只能访问沙箱；要接生产请到接入申请页申请正式 Key。
Q：为什么我不能改审核状态？
A：审核是平台流程，沙箱只开放业务字段，避免"自己审自己"导致演示数据失真。
Q：Key 到期了怎么办？
A：用同邮箱重新开通（7 天限制过后）即可；也可直接申请正式 Key。
常见问题
API Key 怎么保管？丢了怎么办
服务端只存哈希，明文只在创建时显示一次。请存进服务端环境变量（不要提交到代码仓库、不要写进前端）。丢失无法找回，需联系平台撤销重发。
一个 Key 可以多人共用吗
技术上可以，但不建议：Key 绑定企业租户，共用后无法区分调用方。多人协作请各自申请，或按系统分配不同 Key。
调用频率上限是多少
见「限流与配额」：个人试用 20 次/分 · 2000 次/日，企业付费 200 次/分 · 5 万次/日。超出返回 42900。
数据多久更新一次
接口读的是平台台账，台账变更后即时反映；外部工商信息的采集频率以采集任务为准，不承诺固定刷新周期。
可以商用吗
可以。商用配额与计费按合同约定；请勿转售原始数据或用于训练对外发布的模型。
申请多久能通过
AI 数字员工即时审核：资料完整、用途明确的当场放行；转人工的通常当天出结果。
被拒了还能再申请吗
可以。人工拒绝需隔 7 天再申请；AI 拒绝可申诉转人工，不受冷却限制。申诉方式见「申诉与变更」。
支持哪些语言 / 有 SDK 吗
HTTP 接口不限语言，示例给 curl/bash。官方提供 Python / TypeScript SDK 与 MCP Server，可在支持 MCP 的 AI 客户端里直接用。
怎么撤销 Key
联系平台撤销并重发；撤销后旧 Key 立即失效。若怀疑泄露，请先撤销再排查调用来源。
返回的数据包含个人隐私吗
不包含。接口只提供企业主体、资产、关系与统计，个人隐私字段与第三方版权内容不在范围内。
申诉与变更
申诉：AI 审核拒绝后如需人工复核，请用申请时填写的邮箱发信至接入邮箱，注明「申请手机号 + 企业全称 + 复核理由」，附上用途说明；人工复审结果会回信告知。
变更：v1 契约冻结，任何不兼容改动都会走 v2；新增字段属兼容变更，会提前通知到申请邮箱。
联络：接入问题请走接入申请页底部联系方式，或回复开通通知邮件。
本页字段与口径取自平台真实实现（2026-10-18 校核）；如与实际返回不一致，以实际返回为准并请告知我们修正。