适用场景：为什么需要单一企业深度查询
在供应链金融、企业合作背调、投资尽调、信贷审核等业务中，常常需要对某一个具体企业进行全方位的工商信息验证。不同于列表式的模糊搜索，深度查询需要返回企业准备信息、股东结构、高管名单、对外投资图谱、历史变更记录，以及被执行、失信被执行、限制高消费、经营异常、严重违法、行政处罚等风险维度。如果每查一个维度就调用一次不同接口，不仅增加网络开销，还容易因数据源不一致导致分析断裂。
企业档案深度查询API正是为解决这一痛点而生：一次请求，按需返回多个维度的结构化数据，并附带企业规模标签、经营状态、成立年限、活力评分与自然语言摘要，极大降低多接口整合的复杂度。
接口能力边界
- 查询主体：单次请求只能查询一个企业（通过
company参数指定名称）。 - 数据范围：覆盖工商基本信息（basic）、股东信息（shareholders）、主要成员（executives）、对外投资（investments）、变更记录（changes）、风险综合（risk）六大维度，且每个维度可独立选择。
- QPS限制：5次/秒，适合中低频次的实时查询或批量离线任务。
- 数据时效：6小时缓存机制。当天变更的数据可能存在延迟，请勿用于需要实时秒级更新的场景（如当日工商变更提醒）。
- 返回量级：每个维度的数据量取决于企业复杂度，单次响应体可能较大（特别是股东或对外投资较多的公司），建议根据实际需要选择维度，避免传输无用字段。
请求参数与鉴权
请求地址
POST https://v1.apizero.cn/api/company-profileHeader参数
| 参数名 | 必需 | 类型 | 说明 |
|---|---|---|---|
| Authorization | 是 | string | Bearer 后跟您的API Key，例如Bearer sk-your-key-here |
| Content-Type | 否 | string | 请求体格式，默认使用application/json，通常不需要显式设置 |
注意：部分旧版本客户端可能使用
X-API-Key头进行鉴权，但请以官方最新文档为准，推荐使用Authorization: Bearer标准方式。
请求体（JSON）
| 字段 | 必需 | 类型 | 说明 |
|---|---|---|---|
| company | 是 | string | 企业名称，2-80个字符，支持中文，模糊匹配（简称/全称均可）；兼容字段名name |
| dimension | 否 | string | 查询维度，多个维度用英文逗号分隔。可选值：basic（基本信息）、shareholders（股东）、executives（高管）、investments（对外投资）、changes（变更记录）、risk（风险综合）。不传默认返回basic |
示例请求体
{ "company": "阿里巴巴", "dimension": "basic,shareholders,risk" }curl 接入示例
以下 curl 命令展示完整调用过程，请将YOUR_API_KEY替换为真实密钥。
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"若使用X-API-Key方式，则改为：
curl -sS \ -X POST \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"company": "阿里巴巴", "dimension": "basic,shareholders,risk"}' \ "https://v1.apizero.cn/api/company-profile"成功响应示例（经格式化）：
{ "code": 0, "msg": "成功", "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "data": { "basic": { "company_name": "阿里巴巴（中国）有限公司", "legal_person": "示例", "register_capital": "1.4 亿美元", "business_status": "存续", "credit_code": "9133...", "establish_date": "2007-03-26" }, "dimensions": ["basic"], "extension": { "company_age_years": 19, "register_capital_label": "巨型企业", "vitality_score": 92, "vitality_level": "极高", "summary": "该企业成立于2007年，注册资本1.4亿美元，主营业务为……" }, "stats": { "risk_total": 0, "shareholder_count": 3 } } }Python 代码接入示例
以下用requests库实现，要求已安装（pip install requests）。
import requests import json API_URL = "https://v1.apizero.cn/api/company-profile" API_KEY = "YOUR_API_KEY" # 请替换 def query_company_profile(company_name, dimensions="basic"): headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } payload = { "company": company_name, "dimension": dimensions } response = requests.post(API_URL, headers=headers, json=payload, timeout=15) response.raise_for_status() return response.json() # 使用示例 result = query_company_profile("阿里巴巴", "basic,risk,shareholders") if result.get("code") == 0: data = result["data"] print("企业名称:", data["basic"]["company_name"]) print("经营状态:", data["basic"]["business_status"]) print("风险总数:", data["stats"]["risk_total"]) print("股东数量:", data["stats"]["shareholder_count"]) if "extension" in data: print("活力评分:", data["extension"]["vitality_score"]) else: print("查询失败:", result.get("msg"))注意：当dimension包含shareholders时，返回的股东列表会嵌套在data.shareholders数组中（素材未展示，实际返回包含shareholder_list等字段）。请根据实际响应体进行解析。
返回字段解读
顶层结构
| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 业务状态码，0表示成功，非0表示失败 |
| msg | string | 状态描述信息 |
| request_id | string | 本次请求唯一标识，可用于日志追踪 |
| data | object | 核心数据对象，内容由请求的dimension决定 |
data 对象
basic（object）：企业工商基本信息，包含公司名、法人、准备资本、经营状态、统一社会信用代码、成立日期等。shareholders（object | array）：当请求维度包含shareholders时返回，包含股东列表、持股比例等。executives（object | array）：高管人员信息。investments（object | array）：对外投资企业列表。changes（object | array）：历史变更记录（按时间倒序）。risk（object | array）：风险综合信息，包含六类风险的数量和详情。dimensions（array）：实际返回的维度名称列表。extension（object）：扩展信息，包括企业成立年限（company_age_years）、准备资本标签（register_capital_label）、活力评分（vitality_score，0-100）、活力等级（vitality_level，极高/高/中/低/极低）以及自然语言摘要（summary）。stats（object）：统计数据，如风险总数（risk_total）、股东数量（shareholder_count）等。
关于风险维度
当请求risk维度时，data.risk对象会包含以下子维度（具体字段名以实际为准，通常为数组）：
executed：被执行信息dishonest：失信被执行信息high_consumption_limit：限制高消费信息business_abnormal：经营异常信息serious_violation：严重违法信息administrative_penalty：行政处罚信息
每个子维度均包含数量（count）和详情列表（list），方便程序化处理。
常见错误与处理
| HTTP状态码 | code值 | 含义 | 处理建议 |
|---|---|---|---|
| 200 | 0 | 成功 | - |
| 200 | 1001 | 企业名称不能为空 | 检查company参数是否缺失或为空字符串 |
| 200 | 1002 | 企业名称长度不合法 | 确保长度在2-80字符之间 |
| 200 | 1003 | 未找到该企业信息 | 输入的企业名称可能不存在或拼写有误，建议更换关键词（如去掉地域名） |
| 401 | - | 鉴权失败 | 检查 Authorization 头是否正确，API Key 是否过期或无效 |
| 429 | - | 请求频率超过限制 | 降速至 5 次/秒以内，或等间隔重试 |
| 500 | - | 服务端内部错误 | 稍后重试，如果持续则联系技术支持 |
幂等性说明：相同请求返回的request_id通常不同，但数据内容在 6 小时缓存期内保持一致。如果需要实时数据，请考虑缓存策略。
工程化注意事项
- 按需选择维度：每多一个维度会增加响应体积和接口处理时间。在批量调用时，建议仅请求业务必要的维度，并设置合理的超时（如15秒）。
- 缓存设计：由于数据有6小时缓存，可以在业务层增加本地缓存（如Redis），TTL设为5-6小时，避免重复请求浪费API配额。同时注意：缓存过期后应主动刷新，而非等到用户查询时再刷新。
- 错误重试策略：对于429和5xx错误，采用指数退避重试（初始1秒，最多3次）；对于4xx业务错误（如1003未找到），无需重试，直接返回给前端。
- 名称模糊匹配：
company支持简称和全称模糊搜索，但极端情况下可能匹配到多个类似企业（返回优先级最高的一个）。如果需要精确匹配，建议先调用企业列表接口获取统一信用代码，再通过company传入精确名称。目前接口并未提供信用代码查询参数，所以请尽量使用完整官方名称。 - 风险数据的判空：当企业无风险记录时，
risk_total为0，但risk对象中的各子维度可能仍然存在（count=0或list=[]），注意代码中做非空判断。 - 数据合规性：该接口返回的工商数据来源于公开渠道，但仍需遵守与接口提供方的使用协议，不可用于违法违规活动或不正当竞争。
参考文档
- 官方文档页：https://apizero.cn/aidocs/company-profile
- 原始文档（Markdown）：https://apizero.cn/aidocs/company-profile/raw.md
以上文档包含详细的返回字段枚举、错误码列表及更新日志，建议在对接前仔细阅读。
)
 agent和组件)