企业信息模糊查询 API：一个关键词带回信用代码、企业类型与法定代表人

供应商准入、客户建档、开票信息核对，第一道坎往往是「手里只有一个不完整的公司名」：「某某能源」「某某物流」这类简称，或者一张名单 Excel 里几百个名字需要补全统一社会信用代码。人工去查字号 iget 一个个搜，慢且容易串；更麻烦的是同名近似企业（「重庆某某能源有限公司」和「重庆某某新能源有限公司」），选错主体后面全是错的。enterprise.query 把这件事做成一个 GET 接口：传入关键词，返回命中的企业列表，每条给出名称、工商注册号、统一社会信用代码、企业类型、成立日期、法定代表人，用信用代码做主键就可以直接入库去重。

一个必须提前讲清楚的计费口径：本接口查不到结果不收费。关键词为空、少于 2 个字符、上游不可用，或者压根没匹配到企业，都直接返回失败且不扣费、不写扣费流水、不累加调用次数——脏关键词不会吃掉预算。详见第九节。

• api.xujian.tech
• V：xujian_cq

接口速览

一、哪些场景会用到它

模糊查询的定位是入口型接口：它只返回定位所需的最小字段集，拿到信用代码之后再按需组合 enterprise.profile、enterprise.dishonesty 等接口，比一上来就拉全量详情便宜得多。

二、请求参数

2.1 请求头

2.2 业务参数（Query String）

三、返回字段

3.1 顶层字段

3.2 data 字段

3.3 list[] 元素字段

未取到的字段一律返回空字符串，不返回 null，调用方不需要逐字段判空。上游的主键、匹配权重等内部字段一概不返回——返回体里的七个字段就是全部。

四、调用示例

4.1 curl

curl -s -G "https://api.xujian.tech/openapi/enterprise/query" \
  --data-urlencode "keyword=某某能源" \
  --data-urlencode "limit=10" \
  -H "X-API-Key: 你的APIKey"

4.2 Java（JDK 11+ HttpClient）

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class EnterpriseQueryClient {
   

    private static final String API_URL = "https://api.xujian.tech/openapi/enterprise/query";

    public String query(String apiKey, String keyword, Integer limit) throws Exception {
   
        StringBuilder url = new StringBuilder(API_URL)
                .append("?keyword=").append(URLEncoder.encode(keyword, StandardCharsets.UTF_8));
        if (limit != null && limit > 0) {
   
            url.append("&limit=").append(limit);
        }

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url.toString()))
                .header("X-API-Key", apiKey)
                .timeout(Duration.ofSeconds(15))
                .GET()
                .build();

        return HttpClient.newHttpClient()
                .send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8))
                .body();
    }
}

4.3 Python

import requests


def query_enterprise(api_key: str, keyword: str, limit: int | None = None) -> list[dict]:
    """模糊查询企业，返回企业列表；查不到返回空列表（且不扣费）"""
    params = {
   "keyword": keyword}
    if limit:
        params["limit"] = limit

    resp = requests.get(
        "https://api.xujian.tech/openapi/enterprise/query",
        params=params,
        headers={
   "X-API-Key": api_key},
        timeout=15,
    )
    result = resp.json()
    if result.get("code") != 0:
        print("查询失败（不收费）：", result.get("msg"))
        return []
    return result["data"]["list"]


if __name__ == "__main__":
    for ent in query_enterprise("你的APIKey", "某某能源"):
        print(ent["name"], ent["creditNo"], ent["typeName"], ent["startDate"])

4.4 JavaScript（浏览器 / Node 18+）

const url = new URL("https://api.xujian.tech/openapi/enterprise/query");
url.searchParams.set("keyword", "某某能源");
url.searchParams.set("limit", "10");

const {
    code, msg, data } = await fetch(url, {
   
  headers: {
    "X-API-Key": API_KEY },
}).then((r) => r.json());

if (code === 0) {
   
  data.list.forEach((e) => console.log(e.name, e.creditNo, e.operName));
} else {
   
  console.warn("查询失败（不收费）：", msg);
}

五、返回示例

{
   
  "code": 0,
  "msg": "success",
  "data": {
   
    "keyword": "某某能源",
    "total": 2,
    "list": [
      {
   
        "name": "重庆某某能源有限公司",
        "regNo": "5001100XXXXXXXX",
        "creditNo": "91500110MAXXXXXXX",
        "type": "0",
        "typeName": "企业",
        "startDate": "2021-08-31",
        "operName": "张某某"
      },
      {
   
        "name": "重庆某某新能源科技有限公司",
        "regNo": "5001100XXXXXXXX",
        "creditNo": "91500112MAYYYYYYY",
        "type": "0",
        "typeName": "企业",
        "startDate": "2023-04-17",
        "operName": "李某某"
      }
    ],
    "apiCode": "enterprise.query",
    "apiName": "企业信息模糊查询",
    "chargeType": "PER_CALL",
    "balance": 99.9900,
    "costMs": 860
  }
}

查不到时的返回（不计费）：

{
   
  "code": 500,
  "msg": "未查询到匹配的企业信息，请更换更完整的企业名称 / 注册号 / 统一社会信用代码后重试；本次调用不计费",
  "data": null
}

这里有个容易被忽略的设计点：「查不到」走的是失败返回而不是空 list。好处是扣费语义清晰（成功就等于有数据），代价是调用方必须区分「业务失败」和「真的没有这家公司」——判断依据就是上面这条 msg。

六、落地实践

6.1 名录批量补全：先定位，再详情

from concurrent.futures import ThreadPoolExecutor, as_completed


def enrich_roster(api_key: str, names: list[str]) -> list[dict]:
    """把简称名单补全为标准工商主体"""
    result = {
   }
    with ThreadPoolExecutor(max_workers=4) as pool:
        futures = {
   pool.submit(query_enterprise, api_key, n): n for n in names}
        for fu in as_completed(futures):
            name = futures[fu]
            hit = fu.result()
            # 命中多条时用信用代码作为唯一主键落库，留待人审选择
            result[name] = hit
    return [{
   "原始名称": k, "命中": v} for k, v in result.items()]

6.2 用信用代码做去重主键

public class EnterpriseArchive {
   
    /**
     * 名录合并：以统一社会信用代码为主键，避免同名不同主体被合并
     */
    public void merge(List<EnterpriseRow> rows) {
   
        Map<String, EnterpriseRow> index = new HashMap<>();
        for (EnterpriseRow row : rows) {
   
            if (StrUtil.isBlank(row.getCreditNo())) {
   
                continue;   // 模糊查询没拿到信用代码的行，留到人工处理
            }
            index.merge(row.getCreditNo(), row, (oldVal, newVal) ->
                    // 同一信用代码出现多次时保留信息更完整的一条
                    completeness(oldVal) >= completeness(newVal) ? oldVal : newVal);
        }
    }
}

6.3 与其他企业接口组合

名单里的简称
   ↓ enterprise.query   （0.01 元/次）定位主体、拿到信用代码
   ↓ 用 creditNo 作为后续接口的 keyword，避免同名错查
   ├─ enterprise.profile     （0.20 元/次）33 项工商照面：状态、注册资本、经营范围
   ├─ enterprise.dishonesty  （0.20 元/次）失信被执行人
   ├─ enterprise.abnormal    （0.20 元/次）经营异常名录
   └─ enterprise.detail      （0.52 元/次）照面 + 股东 + 变更 + 社保一次拿全

七、提高命中率的几条建议

1. 关键词至少 4 个字符。低于 2 个字符直接参数错误；2 ~ 3 个字符虽然合法，但命中结果往往过多甚至查不到有用的。
2. 优先用信用代码或注册号。整串传入可以精确定位，几乎不会命中错主体。
3. 用注册名片段而不是口语简称。例如用「某某能源」而不是「某能源公司」，去掉「市」「有限公司」等冗余词反而更稳。
4. 同名命中多条时不要自动取第一条。把 list 全部展示给用户选择，或用成立日期、法定代表人做二次比对。
5. limit 不用白填。上限就是 20 条，需要更大范围请拆关键词分批查。
6. 查不到的分支要单独处理。这类返回不计费，适合直接落到「待人工核对」队列，而不是重试。

八、错误码与排查

九、计费与接入

接入流程：注册开发者账号 → 控制台创建 API Key → 请求头带上 X-API-Key 即可调用，无需签名或加密。控制台可查看调用量、扣费流水与余额。

服务站点：api.xujian.tech（纯文本域名，不做跳转）。接口试用、数据与充值咨询可在控制台提交工单，或联系 Vxujian_cq。

边界说明：本接口返回的是工商登记公示口径的主体信息，用于定位与核验；不包含经营状况、风险、财务等深度数据，需要的话请用 enterprise.profile / enterprise.detail 等接口。

十、小结

企业名录类需求的核心不是「查得到」，而是「别查错主体」。用信用代码做主键、把模糊查询当作定位入口而不是数据终点，能省掉后面大量的返工。

使用时要记住：

• 查不到不收费：脏关键词不会消耗预算，失败分支可以直接转人工队列；
• 最多 20 条：需要更宽范围就拆关键词分批查；
• 七个字段足够做主键与去重：creditNo 定位、name 展示、startDate / operName 做同名二次比对；
• 再用信用代码去调详情接口，比拿名称去查稳得多。

配套接口：enterprise.profile（0.20 元/次）拿 33 项工商照面，enterprise.detail（0.52 元/次）一次取回照面 + 股东 + 变更 + 社保，enterprise.dishonesty / enterprise.abnormal（各 0.20 元/次）做风险排查。