企业档案深度查询API零基础接入与字段详解-平芜编程栈

适用场景

企业档案深度查询接口专为需要单一企业全维度工商数据的场景设计，常用于以下业务环节：

商业尽调：在投资、并购前对目标公司进行基础信息、股东结构、高管背景的普查。
合作方背调：在供应商准入、渠道签约时核验企业的经营状态与风险记录。
风控审查：信贷审核、担保业务中快速获取企业的执行、失信、行政处罚等风险信号。
内部数据补全：需要将企业基础档案与风险标签自动回填到业务系统的场景。

与仅返回关键词列表的接口不同，本接口面向单条企业的深度探底，支持按需组合维度的查询，适合在用户输入公司全称或简称后触发的明细查询。

接口能力边界

请求方式：POST
地址：https://v1.apizero.cn/api/company-profile
QPS 限制：5次/秒，超出后会返回频率限制错误。
数据新鲜度：权威工商数据源，6 小时缓存（非实时库）。若需极实时数据，请自行对接官方实时接口。
查询维度：支持basic（基本信息）、shareholders（股东）、executives（高管）、investments（对外投资）、changes（变更记录）、risk（风险综合）共六个维度的任意组合，用英文逗号分隔。
输入限制：企业名称 2–80 字符，支持模糊简称匹配（如“阿里巴巴”即可命中“阿里巴巴（中国）有限公司”）。
单次响应：只返回一条匹配度最高的企业档案；若多企业重名，可能返回最可能的那个，不保证返回所有同名企业。

鉴权与请求参数

鉴权方式

在 HTTP Header 中传入 API Key，支持两种方式：

Authorization: Bearer <你的 API Key>
X-API-Key: <你的 API Key>（某些客户端旧版本兼容）

推荐使用Authorization标准方式。API Key 需在平台获取，本文不赘述申请流程。

Header 参数

参数名	是否必须	类型	说明
Authorization	是	string	`Bearer <API Key>`
Content-Type	否	string	默认为`application/json`

请求体（JSON）

字段名	是否必须	类型	说明
company	是	string	企业名称，2–80 字符，支持简称/全称模糊搜索；兼容别名`name`
dimension	否	string	查询维度，多维度用逗号分隔（如`basic,shareholders,risk`）

若不传dimension，默认仅返回basic维度（即基础信息）。为获得完整档案，建议至少包含basic,risk两个维度。

请求体示例：

{ "company": "北京字节跳动科技有限公司", "dimension": "basic,shareholders,executives,risk" }

curl 接入示例

以下 curl 命令演示了带维度组合的完整请求：

curl -sS \ -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"company": "华为技术有限公司", "dimension": "basic,shareholders,risk"}' \ "https://v1.apizero.cn/api/company-profile"

执行说明：

请将YOUR_API_KEY替换为实际 API Key。
返回值是 JSON 格式，建议用jq解析：curl ... | jq .
若不传dimension，服务端会按缺省值basic处理。

返回字段解读

响应示例（压缩）：

{ "code": 0, "msg": "成功", "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "data": { "basic": { "company_name": "华为技术有限公司", "credit_code": "91440300279501004G", "legal_person": "赵明路", "establish_date": "1987-09-15", "business_status": "存续", "register_capital": "403.6246 亿元人民币" }, "dimensions": ["basic", "shareholders", "risk"], "extension": { "company_age_years": 37, "register_capital_label": "巨型企业", "vitality_score": 95, "vitality_level": "极高", "summary": "华为技术有限公司成立于1987年，注册资本403.6亿元，存续状态，股东结构清晰，暂无高风险记录。" }, "stats": { "risk_total": 0, "shareholder_count": 2 } } }

顶层字段

字段	类型	说明
code	int	业务状态码，0 表示成功，非 0 表示异常（见错误处理）
msg	string	提示信息
request_id	string	唯一请求 ID，可用于排查问题
data	object	实际数据主体

data 结构

basic：基础信息，仅在请求包含basic维度时返回。
- company_name：企业全称（匹配的官方名称）
- credit_code：统一社会信用代码（脱敏中间部分，如9144...4G）
- legal_person：法定代表人
- establish_date：成立日期
- business_status：经营状态（存续/吊销/注销等）
- register_capital：准备资本（带单位）
dimensions：实际返回的维度列表（与请求中的dimension可能不一致，因为某些维度无数据会被省略）
extension：扩展信息（始终返回，无需在dimension中指定）
- company_age_years：成立年数（计算值）
- register_capital_label：准备资本标签（如“微型企业”“小型企业”“中型企业”“大型企业”“巨型企业”）
- vitality_score：企业活力评分（整数，范围 0–100）
- vitality_level：活力等级（低/中/高/极高）
- summary：自然语言摘要，概括核心信息与风险状况
stats：统计数据（始终返回）
- risk_total：六大类风险总数（如 0）
- shareholder_count：股东人数（若请求包含shareholders维度才有实际值，否则可能为 0）

注意：当请求包含shareholders、executives、investments、changes、risk维度时，data中会额外返回对应数组（如shareholders: [ { shareholder_name: ..., ratio: ... } ]）。请以实际返回为准。

常见错误码与排查

code	msg 示例	可能原因	解决建议
0	成功	—	—
1001	参数缺失：company 不能为空	未传`company`或值为空	检查请求体 JSON 字段名称是否正确
1002	企业名称长度不在 2–80 范围内	输入的`company`太短或太长	修正企业名称
1003	维度参数不合法	`dimension`包含了非定义的维度名称	仅使用预设的六种维度
2001	未找到匹配的企业	输入名称过于模糊或数据库中无该企业	尝试更精确的全称，或检查名称拼写
4001	请求频率超限	每秒 QPS 超过 5 次	增加请求间隔，或使用本地缓存
5001	内部服务错误	服务端异常	稍后重试，或检查请求 ID 提交工单

若返回 HTTP 401，请检查AuthorizationHeader 格式（是否缺少Bearer前缀）及 API Key 是否有效。

工程化注意事项

维度按需选择：不需要的维度不要请求，以减少响应体大小和响应时间。例如仅做风险筛查可只传basic,risk。
缓存策略：数据有 6 小时缓存，对同一个企业同一天的多次请求可直接缓存本地，避免耗光 QPS。
错误重试：对5001和4001错误实现指数退避重试（如 1s、2s、4s）。4001时减小并发。
名称匹配：输入的企业名称可能返回非精确匹配的结果（如“华为”可能匹配“华为技术有限公司”而非“华为云计算技术有限公司”）。建议在前端/业务层增加二次确认步骤。
字段兼容性：basic中的credit_code默认脱敏中间部分；如需明文信用代码，请查阅文档确认是否需额外权限。
日志与监控：记录request_id和code，便于排查调用链路。