企业名称模糊搜索

1. 接口概述

根据企业名称关键词查询匹配的企业列表。

接口最多返回 10 条企业数据，不提供分页功能。

每次成功调用会扣减调用方所属企业的 1 次工商查询额度。

2. 接入准备

调用接口前，需要向平台申请以下凭证：

注意：

• appid 需要通过请求 Header 发送。
• appsecret 只用于调用方本地生成签名。
• 不得将 appsecret 放入请求 Header、请求体、URL或公开日志中。

3. 请求地址

请求方式：

POST

可用地址：

https://vip.xty123.cn/api/open/enterprise/wildcard

请求数据格式：

application/json; charset=UTF-8

4. 请求鉴权

4.1 鉴权 Header

每次请求需要携带以下 Header：

HTTP Header 名称不区分大小写，但建议严格使用文档中的名称。

4.2 签名规则

按照以下顺序直接拼接：

待签名字符串 = appsecret + nonce + timestamp

对待签名字符串执行 MD5 计算：

signature = MD5(appsecret + nonce + timestamp)

签名结果应为：

• 32 位字符串；
• 小写十六进制；
• 不包含空格；
• 不包含前缀或其他符号。

5. 请求参数

5.1 JSON请求体

参数名称区分大小写，必须使用 companyName。

5.2 请求示例

POST /api/open/enterprise/wildcard HTTP/1.1
Host: vip.xty123.cn
Content-Type: application/json
appid: <平台分配的appid>
nonce: a8f3c2e91b7d4k6m
timestamp: 1789344000
signature: <计算得到的32位小写MD5值>

{
  "companyName": "示例科技"
}

6. 返回结构

6.1 公共响应字段

调用方必须判断响应中的 code，不能只根据 HTTP 状态码判断业务是否成功。

6.2 data 数组字段

7. 成功响应示例

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "companyName": "示例科技有限公司",
      "creditCode": "91310000XXXXXXXXXX",
      "legalName": "张三",
      "establishDate": "2020-01-15"
    },
    {
      "companyName": "上海示例科技有限公司",
      "creditCode": "91310110XXXXXXXXXX",
      "legalName": "李四",
      "establishDate": "2021-06-08"
    }
  ]
}

8. 无匹配结果示例

没有查询到匹配企业时，接口可能返回成功状态和空数组：

{
  "code": 0,
  "msg": "成功",
  "data": []
}

9. 失败响应示例

9.1 公司名称为空

{
  "code": 400,
  "msg": "公司名不能为空",
  "data": null
}

9.2 鉴权失败

{
  "code": 413,
  "msg": "鉴权失败",
  "data": null
}

9.3 工商查询额度不足

{
  "code": 1102,
  "msg": "剩余条数不够",
  "data": null
}

9.4 服务异常

{
  "code": 500,
  "msg": "未知异常，请稍候再试",
  "data": null
}

10. 业务状态码

11. 调用注意事项

1. 本接口不支持分页，最多返回 10 条结果。
2. 不需要传递 page、pageSize、keyword 等参数。
3. 请求参数必须使用 companyName。
4. 建议使用相对完整的企业关键词，避免只传递一个常见汉字。
5. 每次请求建议重新生成 nonce、timestamp 和 signature。
6. 不要把 appsecret 发送到服务端。
7. 每次成功调用会扣减 1 次工商查询额度。
8. 同一个请求重复调用会被当作多次独立查询。
9. 请求超时后不要无限自动重试，因为服务端可能已经完成查询和额度扣减。
10. 调用方应设置合理的连接超时和读取超时时间。
11. 返回字段可能为空，接入方应做好空值兼容。
12. 不要根据企业列表中的顺序判断匹配程度或企业优先级。