接口概述
一句话说明
enterprise.profile 是核实企业身份最省钱的接口:只要工商照面 33 项,
不含股东、变更、社保等扩展维度(需要全景数据请用 enterprise.detail)。
适用于开票信息补全、供应商身份核实、CRM 建档补资料等只需要「确认这家企业是谁」的场景。
| 请求地址 | https://api.xujian.tech/openapi/enterprise/profile |
|---|---|
| 请求方式 | GET(keyword 放 Query String) |
| 鉴权方式 | 请求头 X-API-Key(不做签名与加密) |
| 接口编码 | enterprise.profile |
| 收费类型 | PER_CALL(按次计费,0.2000 元/次) |
| 计费特殊规则 | 查得计费:关键词非法、上游不可用、查不到该企业时返回失败且不扣费 |
| 响应格式 | JSON,Content-Type: application/json;charset=UTF-8 |
| 是否需要授权 | 否(无需授权,API Key 有效且余额充足即可调用) |
| 关键词长度 | 2 ~ 50 个字符 |
| 返回字段 | 工商照面 33 项 |
快速开始
curl -s -G "https://api.xujian.tech/openapi/enterprise/profile" \
--data-urlencode "keyword=重庆可乐家装饰工程有限公司" \
-H "X-API-Key: 你的APIKey"
两个最常用字段
开票 / 建档场景最常用的其实是这两个字段:name(工商登记全称)
与 creditNo(统一社会信用代码)。把接口的返回值直接回填到表单里,
比让用户手打要可靠得多。
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
X-API-Key | String | 是 | 开发者 API Key |
| 参数名 | 类型 | 必填 | 示例 | 说明 |
|---|---|---|---|---|
keyword | String | 是 | 重庆可乐家装饰工程有限公司 |
企业全称 / 注册号 / 统一社会信用代码,长度 2 ~ 50 个字符。
为空或超长返回失败,不计费。名称不确定时先用
enterprise.query 模糊查询校正
|
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 0 成功,非 0 失败 |
msg | String | 结果描述 |
data | Object | 业务数据,失败时为 null |
| 字段 | 类型 | 说明 |
|---|---|---|
keyword | String | 本次查询关键词原文 |
basicInfo | Object | 工商照面 33 项(见下表) |
apiCode | String | 接口编码 enterprise.profile |
apiName | String | 接口名称 |
chargeType | String | 计费类型 |
balance | BigDecimal | 调用完成后(已扣费)的账户余额(元) |
costMs | Long | 本次调用耗时(毫秒) |
basicInfo(工商照面 33 项)
| 字段 | 类型 | 示例 | 说明 |
|---|---|---|---|
name | String | 重庆可乐家装饰工程有限公司 | 企业名称 |
formatName | String | 重庆可乐家装饰工程有限公司 | 标准企业名称(清洗后) |
creditNo | String | 91500113MAABRA7D0H | 统一社会信用代码 |
regNo | String | 500113014353471 | 企业注册号 |
orgNo | String | 91500113MAABRA7D0H | 组织机构号 |
status | String | 存续(在营、开业、在册) | 经营状态(工商公示原文) |
newStatus | String | 存续 | 经营状态(清洗后):存续 / 注销 / 吊销 / 撤销 / 迁出 / 设立中 / 清算中 / 停业 / 其他 / 歇业 / 责令关闭 |
operName | String | 李伦智 | 法定代表人姓名 |
title | String | 法定代表人 | 公司代表人职务 |
operType | String | P | 法定代表人类型:P-个人,C-公司 |
registCapi | String | 100 万人民币 | 注册资本 |
actualCapi | String | - | 实缴资本 |
currencyUnit | String | CNY | 货币单位 |
startDate | String | 2021-06-02 | 成立日期 |
termStart | String | 2021-06-02 | 营业开始日期 |
termEnd | String | - | 营业结束日期,「-」表示长期 |
endDate | String | - | 注销日期 |
checkDate | String | 2021-06-02 | 核准日期 |
revokeDate | String | - | 吊销日期 |
revokeReason | String | - | 吊销原因 |
logoutReason | String | - | 注销原因 |
econKind | String | 有限责任公司 | 企业类型 |
econKindCode | String | 1100 | 企业类型代码 |
typeNew | String | 01 | 企业大类:01 大陆企业 / 02 社会组织 / 03 机关及事业单位 / 04 港澳台及国外企业 / 05 律所及其他 |
categoryNew | String | 0115601 | 二级分类:0115601 企业 / 0115602 个体 / 0115603 农民专业合作社 |
domain | String | D4511 | 四级行业代码(国民经济行业分类) |
address | String | 重庆市巴南区…… | 企业注册地址 |
belongOrg | String | 重庆市巴南区市场监督管理局 | 登记机关 / 所属工商局 |
districtCode | String | 500110 | 所属行政区划代码 |
scope | String | 许可项目:住宅室内装饰装修…… | 经营范围(工商登记完整文本) |
tags | Array | [] | 企业标签:1 新三板 / 6 主板上市 / 9 香港上市 / 17 高新企业 / 40 暂停上市 / 41 终止上市 |
historyNames | Array | [] | 历史名称变更记录 |
fenname | String | - | 企业英文名 |
响应示例
成功(code = 0)
{
"code": 0,
"msg": "success",
"data": {
"keyword": "重庆可乐家装饰工程有限公司",
"basicInfo": {
"name": "重庆可乐家装饰工程有限公司",
"formatName": "重庆可乐家装饰工程有限公司",
"creditNo": "91500113MAABRA7D0H",
"regNo": "500113014353471",
"orgNo": "91500113MAABRA7D0H",
"status": "存续(在营、开业、在册)",
"newStatus": "存续",
"operName": "李伦智",
"title": "法定代表人",
"operType": "P",
"registCapi": "100 万人民币",
"actualCapi": "-",
"currencyUnit": "CNY",
"startDate": "2021-06-02",
"termStart": "2021-06-02",
"termEnd": "-",
"endDate": "-",
"checkDate": "2021-06-02",
"revokeDate": "-",
"revokeReason": "-",
"logoutReason": "-",
"econKind": "有限责任公司",
"econKindCode": "1100",
"typeNew": "01",
"categoryNew": "0115601",
"domain": "D4511",
"address": "重庆市巴南区龙洲湾街道龙洲大道255号17-1",
"belongOrg": "重庆市巴南区市场监督管理局",
"districtCode": "500110",
"scope": "许可项目:住宅室内装饰装修(依法须经批准的项目,经相关部门批准后方可开展经营活动)",
"tags": [],
"historyNames": [],
"fenname": "-"
},
"apiCode": "enterprise.profile",
"apiName": "企业工商照面信息查询",
"chargeType": "PER_CALL",
"balance": 99.8000,
"costMs": 480
}
}
失败(查不到该企业)—— 不收费
{
"code": 500,
"msg": "未查询到该企业的工商照面信息,请核对企业名称或统一社会信用代码后重试;本次调用不计费",
"data": null
}
错误码与常见失败原因
| code | msg(示例) | 处理建议 |
|---|---|---|
| 0 | success | 调用成功 |
| 500 | 缺少请求头 X-API-Key | 补充 X-API-Key |
| 500 | API Key 无效 / API Key 已停用 | 检查 Key 或重新启用 |
| 500 | 客户不存在或已停用 | 联系平台(可联系微信xujian_cq) |
| 500 | 接口不存在或已停用 | 确认 enterprise.profile 当前是否维护中 |
| 500 | 余额不足,请先充值。可联系微信xujian_cq | 充值后重试,余额不足不扣费 |
| 500 | keyword 不能为空 | 补充 keyword;不计费 |
| 500 | keyword 至少需要 2 个字符(建议使用企业全称或统一社会信用代码) | 换更准确的关键词;不计费 |
| 500 | keyword 长度不能超过 50 个字符 | 缩短关键词;不计费 |
| 500 | 未查询到该企业的工商照面信息…… | 用 enterprise.query 校正全称;不计费 |
| 500 | 数据服务暂时不可用(请求上游超时或网络异常),本次调用不计费 | 稍后重试;不计费 |
多语言代码示例
Java(Hutool)
String body = HttpRequest.get("https://api.xujian.tech/openapi/enterprise/profile")
.form("keyword", "重庆可乐家装饰工程有限公司")
.header("X-API-Key", apiKey)
.timeout(15000)
.execute()
.body();
JSONObject json = JSONUtil.parseObj(body);
if (json.getInt("code") != 0) {
System.out.println("查询失败(不收费):" + json.getStr("msg"));
return;
}
JSONObject basic = json.getJSONObject("data").getJSONObject("basicInfo");
System.out.println(basic.getStr("name") + " / " + basic.getStr("creditNo")
+ " / " + basic.getStr("newStatus"));
Python
import requests
def query_profile(api_key: str, keyword: str):
"""查询工商照面 33 项;查不到返回 None 且不扣费"""
resp = requests.get(
"https://api.xujian.tech/openapi/enterprise/profile",
params={"keyword": keyword},
headers={"X-API-Key": api_key},
timeout=20,
)
result = resp.json()
if result.get("code") != 0:
print("查询失败(不收费):", result.get("msg"))
return None
return result["data"]["basicInfo"]
if __name__ == "__main__":
basic = query_profile("你的APIKey", "重庆可乐家装饰工程有限公司")
if basic:
print(basic["name"], basic["creditNo"], basic["operName"], basic["startDate"])
JavaScript(浏览器 / Node 18+)
const resp = await fetch(
"https://api.xujian.tech/openapi/enterprise/profile?keyword=" + encodeURIComponent("重庆可乐家装饰工程有限公司"),
{ headers: { "X-API-Key": API_KEY } }
);
const { code, msg, data } = await resp.json();
if (code === 0) {
const b = data.basicInfo;
console.log(b.name, b.creditNo, b.newStatus, b.scope);
} else {
console.warn("查询失败(不收费):", msg);
}
常见问题(FAQ)
enterprise.profile 接口怎么收费?
enterprise.profile 的收费类型为 PER_CALL(按次计费),当前单价 0.2000 元/次,调用前校验余额,余额不足返回「余额不足,请先充值。可联系微信xujian_cq」且不扣费;充值可可联系微信xujian_cq。扣费金额、交易前后余额均记录于交易流水中。
查不到这家企业怎么办?
先确认使用的是工商登记全称(不要带简称、括号不要打错)。
由于本接口按「查得计费」设计,查不到时不收费,可以放心重试。
名称不确定时建议先用 enterprise.query 模糊查询拿到准确全称再查照面。
status 和 new_status 有什么区别?
status 是工商公示原文(如「存续(在营、开业、在册)」),不便程序判断;
newStatus 是清洗后的标准值(存续 / 注销 / 吊销 / 撤销 / 迁出 / 设立中 /
清算中 / 停业 / 其他 / 歇业 / 责令关闭)。做风控与准入规则请用 newStatus。
注册资本怎么解析成数字?
registCapi 是「金额 + 空格 + 万 + 货币单位」的字符串(如「1200 万人民币」),
actualCapi 同口径。数值比较先提取数字,注意单位一般是万元。
统一社会信用代码能直接当开票税号吗?
三证合一后多数企业一致,但仍有历史企业不同。开票场景建议以 creditNo 为准,
并在首次使用时做一次人工核验。
和 enterprise.detail 怎么选?
只要「确认企业身份」(名称 / 信用代码 / 法人 / 经营范围)用 profile;
还需要股东结构、变更历史、社保参保时用 detail,一次调用全返回,避免多次付费。
调用需要签名或加密吗?
不需要。XAPI 的接口仅校验请求头 X-API-Key,不做签名、时间戳或加密。