企业档案深度查询接口：参数逐项剖析与业务集成注意点
在做合作方准入、投资尽调或工商穿透时，我们往往不满足于“这家企业存在”这个结论，而是需要快速拿到工商基本信息、股东结构、主要成员、对外投资、历史变更，同时还要看它有没有被执行、失信、限高等风险记录。逐项调用多个接口固然可行，但请求次数和联调维护复杂度都会上升。本文要解析的企业档案深度查询接口，就是面向“单一企业的多维度深度核查”场景设计的，一个 POST 请求内通过 dimension 参数组合维度，把名录校验升级为档案级核对。
接口能力边界与本接口适用场景
先明确该接口不是关键词列表检索工具，而是聚焦单一企业的深度查询。输入参数只有两个：企业名称和查询维度，输出则按维度返回对应的工商档案信息块，并附加企业规模标签、成立年限、活力评分与自然语言摘要。
典型适用场景包括：
- 商业尽调：了解目标公司的基础工商信息，并为后续分支核验提供线索。
- 合作方背调：筛选供应商或渠道伙伴时，核查其是否面临经营异常或行政处罚，避免合作中段踩雷。
- 风控审查：对存量对公客户做批量穿透时，将本接口作为“按维度变更分析”的基础数据源。
- 数据清洗补全：当业务侧只有企业简称时，先用该接口尝试模糊匹配后做归一化。
接口能力边界需要特别注意：文档标明数据来自权威工商数据库，并带有6 小时缓存；每天高频调用时，同一企业的数据不会实时变化。这意味着如果需要秒级新鲜度的工商变更信息，不能把本接口作为唯一的变更订阅通道，而应结合权威数据源的同步机制进行二次确认。
请求参数与鉴权方式
鉴权配置
接口的 Header 参数定义如下：
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| Authorization | 是 | string | Bearer <你的 API Key> |
| Content-Type | 否 | string | 请求体格式 |
在官方文档提供的 curl 示例里，使用X-API-Key: $APIZERO_API_KEY作为鉴权头，这与参数表的Authorization并不一致。实际接入时，建议以文档页的最新说明为准，在代码层面对两种 Header 都做好兼容，尤其是调试阶段遇到 401 权限错误时，应首先对比 Header 名称和取值前缀是否符合要求。部分 SDK 或网关会强制改写 Header，如果重复传递Authorization可能会被网关拦截，建议在自己可控的客户端环境里先做最小化验证。
请求体字段逐个拆解
请求体是一个 JSON 对象，具体字段如下：
| 字段名 | 必填 | 类型 | 约束与说明 |
|---|---|---|---|
| company | 是 | string | 2-80 字，含中文，支持简称/全称模糊搜索；兼容别名name |
| dimension | 否 | string | 逗号分隔，可选值：basic、shareholders、executives、investments、changes、risk |
company字段虽然有模糊搜索能力，但面对“阿里巴巴”这类重名率较高的简称时，返回结果可能不是你预期的那家公司。比如“阿里巴巴”可能对应杭州、北京、上海等多地的不同主体。若要提高精确度，建议先通过关键词列表检索拿到标准全称或统一社会信用代码后，再回填本接口。dimension字段的默认值在素材中未说明，因此业务代码里不要依赖隐式默认，而应显式声明自己需要的维度，避免平台侧调整默认值导致响应体积或耗时变化。
维度含义罗列如下：
basic：工商基本信息，如企业名称、统一社会信用代码、法定代表人、准备资本、成立日期、经营状态。shareholders：股东结构及持股比例。executives：主要成员或高管列表。investments：对外投资情况。changes：历史变更记录。risk：六大类风险信息汇总。
实际请求中，最少只传company也能得到基础档案，但会额外返回risk_total等统计值，因此建议按业务需要关闭不需要的维度，缩短响应体并降低解析负担。
curl 与代码接入示例
curl 示例
复制以下命令时，把$APIZERO_API_KEY替换为你自己的 Key。如果平台要求使用Authorization头，则替换示例中的 Header 即可：
curl -sS \ -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"company": "阿里巴巴", "dimension": "basic,shareholders,risk"}' \ "https://v1.apizero.cn/api/company-profile"Python requests 接入示例
import requests API_URL = "https://v1.apizero.cn/api/company-profile" API_KEY = "your-api-key-here" payload = { "company": "阿里巴巴", "dimension": "basic,shareholders,risk" } headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } try: resp = requests.post(API_URL, json=payload, headers=headers, timeout=5) resp.raise_for_status() body = resp.json() if body.get("code") == 0: data = body.get("data", {}) basic = data.get("basic", {}) print("企业名称:", basic.get("company_name")) print("经营状态:", basic.get("business_status")) print("风险总数:", data.get("stats", {}).get("risk_total")) else: print("业务错误:", body.get("msg")) print("request_id:", body.get("request_id")) except requests.Timeout: print("请求超时，建议增加超时时间或重试") except requests.ConnectionError: print("网络连接异常")注意，上面代码里的your-api-key-here是占位符。若你的网关要求使用X-API-Key，把headers改为{"X-API-Key": API_KEY}即可。
响应结构与字段解读
成功响应是标准三层结构：code、msg、data，并附带request_id用于链路追踪。
{ "code": 0, "msg": "成功", "request_id": "...", "data": { "dimensions": ["basic"], "basic": { "business_status": "存续", "company_name": "阿里巴巴（中国）有限公司", "credit_code": "9133...", "establish_date": "2007-03-26", "legal_person": "示例", "register_capital": "1.4 亿美元" }, "extension": { "company_age_years": 19, "register_capital_label": "巨型企业", "vitality_score": 92, "vitality_level": "极高", "summary": "……" }, "stats": { "risk_total": 0, "shareholder_count": 3 } } }核心字段说明
code：业务状态码，0表示成功，非 0 时需要联查msg。data.dimensions：本次实际返回的维度列表，可用于确认平台是否忽略了未支持的维度名。data.basic：工商基本信息。其中credit_code在示例中被脱敏为9133...，真实场景下是完整统一社会信用代码。data.extension：由平台加工后的附加判断字段，包括企业成立年限、准备资本规模标签、活力评分和自然语言摘要。这类字段可以作为人工审核页面的参考，但不建议直接写入合同审批判定逻辑，因为封装口径对调用方不透明。data.stats：按维度聚合的统计信息。risk_total只有请求中携带risk维度时才具有参考意义；若本查询未包含risk，该字段可能为 0 或缺失，不应把“0”理解为企业无风险。
维度组合后的响应差异
当请求dimension包含shareholders时，data下会出现shareholders节点；包含executives时会出现对应节点。因此，响应体字段组合是动态的。在解析层，建议使用data.get("shareholders") or []这类安全读取方式，避免因维度未返回而触发 KeyError。
常见错误与排查切入点
HTTP 层常见状态码
| 状态码 | 可能原因 | 排查切入点 |
|---|---|---|
| 401 | API Key 缺失、非法或 Header 名称不对 | 确认是Authorization: Bearer还是X-API-Key，检查 Key 前后是否带空格或换行 |
| 400 | 请求体不是合法 JSON，或company为空/超长 | 打印原始请求体，确认未将对象数组错传为字符串 |
| 429 | 触发 QPS 限流 | 本接口 QPS 为 5/s，需要把并发降下来，并增加退避重试 |
| 502/504 | 网关或上游服务异常 | 记录request_id，等待数秒后重试 |
业务层常见错误
业务错误码通常在code字段中体现。遇到code非 0 时，优先读取msg判断是参数错误还是无数据。需要注意：
- 模糊搜索得到多条企业时，接口只返回一个结果，若返回的企业与期望不一致，请改用更完整的全称或统一社会信用代码进行精确匹配。
dimension中如果拼写了不存在的维度词，平台可能在dimensions数组中过滤掉该值，但不会显式报错。因此拿到响应后应核对dimensions是否包含你请求的全部维度，避免静默缺维度。- 对
risk维度返回的 0 项要保留一定警惕，它代表当前缓存数据中未检索到风险记录，不等同于该企业绝对零风险。
工程化注意事项
QPS 与并发控制
接口限制为 5 QPS，也就是单密钥每秒最多 5 次请求。如果业务侧需要批量核验，建议引入本地队列或信号量控制并发，而不是依赖代码里的循环裸调。压测时也要注意，当超过 QPS 后触发 429，如果继续无限重试，可能加剧限流。
本地缓存设计
因为数据有 6 小时缓存周期，可以在业务侧再叠加一层短缓存。比如对同一企业的尽调结果缓存 1 小时，既能降低接口压力，也能在平台出现短暂抖动时提供降级数据。对于风险类字段，可在缓存值里额外保存last_fetch_time，如果数据超过 6 小时则强制刷新。
名称归一化与匹配策略
调用前统一清理企业名称中的括号（全角/半角）、空格、公司后缀，避免因字符编码差异导致匹配不到预期主体。若平台允许传name作为company的别名，建议在配置层将旧字段映射到新字段，防止代码升级时忽略兼容性。
动态响应字段的前向兼容
随着平台能力扩展，data下可能增加新的维度节点，例如历史沿革或资质信息。解析代码应基于“节点存在才读取”的模型，不要用强类型 DTO 把响应固定死。同时，把dimensions作为判断依据，当平台新增维度而业务代码未更新时，至少不会因解析异常导致链路中断。
日志与可观测性
建议在每个调用日志中记录company、dimension、request_id、HTTP 状态码和耗时。这样在业务反馈“某企业数据查不到”或“响应变慢”时，可以快速锁定是平台侧问题还是调用参数问题。
参考文档
- 接口文档页：https://apizero.cn/aidocs/company-profile
- 原始 Markdown 文档：https://apizero.cn/aidocs/company-profile/raw.md