leaudit-platform-frontend/auth_doc/api_docs(2).md

企查查模块 API 接口文档

概述

企查查模块提供企业工商信息和失信核查查询功能，数据来源于企查查API。

基础信息

项目	说明
基础路径	/api/v2/qichacha
认证方式	Bearer Token（JWT）
数据格式	JSON

费用说明

接口	企查查接口	单价
工商信息	410接口	0.20元/次
失信核查	740接口	0.30元/次
完整查询	410+740	0.50元/次

注意：仅调用企查查API时产生费用，使用数据库记录不产生费用。

权限要求

权限键	说明	分配角色
qichacha:company:query	查询企业信息	市级管理员、省级管理员、普通员工
qichacha:status:read	查看记录状态	市级管理员、省级管理员、普通员工

---

业务逻辑

核心流程

企查查模块的核心设计理念是数据库优先，通过本地数据库存储已查询过的企业信息，减少对企查查API的调用次数，从而节省费用。

查询流程图

┌─────────────────────────────────────────────────────────┐
│                    用户发起查询请求                       │
│              keyword = "腾讯科技" 或 信用代码             │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
              ┌────────────────────────┐
              │   1. 查询数据库          │
              │   （三字段OR匹配）        │
              │   search_key = keyword  │
              │   OR credit_code = keyword │
              │   OR company_name = keyword │
              └────────────────────────┘
                           │
              ┌────────────┴────────────┐
              │                         │
              ▼                         ▼
       ┌──────────┐              ┌──────────┐
       │ 无记录    │              │ 有记录    │
       └──────────┘              └──────────┘
              │                         │
              │                         ▼
              │            ┌─────────────────────────┐
              │            │  2. 检查force_refresh    │
              │            │     参数是否为true?      │
              │            └─────────────────────────┘
              │                    │           │
              │                  true        false
              │                    │           │
              │                    │           ▼
              │                    │   ┌──────────────────┐
              │                    │   │ 3. 检查数据新鲜度  │
              │                    │   │ updated_at距今    │
              │                    │   │ 是否超过30天?     │
              │                    │   └──────────────────┘
              │                    │        │         │
              │                    │      >=30天     <30天
              │                    │        │         │
              ▼                    ▼        ▼         ▼
       ┌─────────────────────────────┐    ┌──────────────┐
       │  4. 调用企查查API            │    │ 5. 直接返回   │
       │  ├─ 410接口(工商) 0.20元     │    │  数据库记录   │
       │  └─ 740接口(失信) 0.30元     │    │              │
       │                             │    │ ✓ 不产生费用  │
       │  5. 写入/更新数据库          │    │ ✓ 响应更快    │
       │  ├─ search_key = keyword    │    └──────────────┘
       │  ├─ credit_code (从API获取) │
       │  ├─ company_name (从API获取)│
       │  ├─ enterprise = JSON      │
       │  └─ dishonesty = JSON      │
       │                             │
       │  6. 返回查询结果             │
       │  ✗ 产生费用: 0.50元/次       │
       └─────────────────────────────┘

数据刷新策略

场景	条件	动作	是否产生费用
首次查询	数据库无此企业记录	调用API → 写入数据库	✓ 0.50元
强制刷新	force_refresh=true	调用API → 更新数据库	✓ 0.50元
数据过期	记录存在但超过30天	调用API → 更新数据库	✓ 0.50元
数据有效	记录存在且未超30天	直接返回数据库记录	✗ 免费

三字段匹配机制

数据库查询使用OR逻辑匹配以下三个字段：

字段	说明	示例
search_key	原始查询关键词	"腾讯科技"
credit_code	统一社会信用代码	"91440300708461136T"
company_name	企业全称（从API获取）	"腾讯科技（深圳）有限公司"

匹配示例：

1. 用户首次用 "腾讯科技" 查询
   • 数据库无记录 → 调用API
   • API返回企业全称和信用代码
   • 写入数据库：search_key="腾讯科技", credit_code="91440300708461136T", company_name="腾讯科技（深圳）有限公司"
2. 用户再用 "91440300708461136T" 查询
   • 数据库查询：WHERE search_key='91440300708461136T' OR credit_code='91440300708461136T' OR company_name='91440300708461136T'
   • 命中 credit_code 字段 → 返回已有记录（不调用API）
3. 用户再用 "腾讯科技（深圳）有限公司" 查询
   • 命中 company_name 字段 → 返回已有记录（不调用API）

数据存储结构

数据库表：qcc_company_info

字段	类型	说明
id	SERIAL	主键
search_key	VARCHAR(500)	查询关键词（唯一索引）
credit_code	VARCHAR(50)	统一社会信用代码
company_name	VARCHAR(500)	企业名称
enterprise	JSONB	410接口原始返回（工商信息）
dishonesty	JSONB	740接口原始返回（失信信息）
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间（用于判断数据新鲜度）

API调用说明

企查查接口

接口代码	接口名称	请求路径	单价
410	企业工商信息	/ECIV4/GetBasicDetailsByName	0.20元/次
740	失信核查	/ShixinCheck/GetList	0.30元/次

Token生成规则

Token = MD5(AppKey + Timespan + SecretKey).toUpperCase()

• AppKey: 企查查分配的应用Key
• Timespan: Unix时间戳（秒）
• SecretKey: 企查查分配的密钥

请求头

Header	值
Token	MD5签名（大写）
Timespan	Unix时间戳
Content-Type	application/json

并发处理

查询完整企业信息时，系统会并发调用410和740两个接口：

# 并发请求示例
enterprise_task = client.get_enterprise_info(keyword)  # 410接口
dishonesty_task = client.get_dishonesty_info(keyword)  # 740接口

enterprise_resp, dishonesty_resp = await asyncio.gather(
    enterprise_task,
    dishonesty_task,
    return_exceptions=True
)

优点：

• 减少总响应时间（两个请求并行执行）
• 单个接口失败不影响另一个接口的结果

---

API 接口

1. 查询企业信息

查询企业完整信息（工商信息 + 失信核查）

请求

POST /api/v2/qichacha/company
Content-Type: application/json
Authorization: Bearer <token>

请求参数

字段	类型	必填	说明
keyword	string	是	查询关键词（企业名称或统一社会信用代码），2-200字符
force_refresh	boolean	否	是否强制刷新，默认false

请求示例

{
    "keyword": "腾讯科技（深圳）有限公司",
    "force_refresh": false
}

响应参数

字段	类型	说明
success	boolean	查询是否成功
message	string	响应消息
data	object	企业信息（见下表）
error_code	string	错误码（失败时返回）
error_details	object	错误详情（失败时返回）

data 字段说明

字段	类型	说明
search_key	string	查询关键词
credit_code	string	统一社会信用代码
company_name	string	企业名称
enterprise	object	企业工商信息（410接口原始返回）
dishonesty	object	失信核查信息（740接口原始返回）
has_dishonesty	boolean	是否有失信记录
dishonesty_count	integer	失信记录数量
updated_at	datetime	数据更新时间

enterprise 字段说明（410接口返回）

字段	类型	说明
KeyNo	string	企查查内部KeyNo
Name	string	企业名称
No	string	工商注册号
BelongOrg	string	登记机关
OperId	string	法定代表人ID
OperName	string	法定代表人姓名
DesignatedRepresentativeList	array	指定代表人列表
StartDate	string	成立日期（格式：YYYY-MM-DD HH:mm:ss）
EndDate	string	注销日期（空字符串表示未注销）
Status	string	企业状态（存续、注销、吊销等）
Province	string	省份代码（如JS=江苏）
UpdatedDate	string	数据更新日期
CreditCode	string	统一社会信用代码（部分老企业可能为空）
RegistCapi	string	注册资本（含单位，如"36225万元"）
RegisteredCapital	string	注册资本数值
RegisteredCapitalUnit	string	注册资本单位（如"万"）
RegisteredCapitalCCY	string	注册资本币种（如"CNY"）
EconKind	string	企业类型（如"有限责任公司"、"全民所有制"等）
Address	string	注册地址
Scope	string	经营范围
TermStart	string	营业期限起始日期
TermEnd	string	营业期限终止日期
CheckDate	string	核准日期
OrgNo	string	组织机构代码
IsOnStock	string	是否上市（"0"=否，"1"=是）
StockNumber	string	股票代码（非上市为null）
StockType	string	股票类型（非上市为null）
OriginalName	array	曾用名列表
ImageUrl	string	企业Logo图片URL
EntType	string	企业类型代码
RecCap	string	实缴资本（含单位）
PaidUpCapital	string	实缴资本数值
PaidUpCapitalUnit	string	实缴资本单位
PaidUpCapitalCCY	string	实缴资本币种
RevokeInfo	object	注销/吊销信息
Area	object	地区信息
AreaCode	string	地区代码

enterprise.DesignatedRepresentativeList[] 指定代表人

字段	类型	说明
PartnerName	string	股东名称
DelegatedName	string	委派代表姓名

enterprise.OriginalName[] 曾用名

字段	类型	说明
Name	string	曾用名称
ChangeDate	string	变更日期

enterprise.RevokeInfo 注销/吊销信息

字段	类型	说明
CancelDate	string	注销日期
CancelReason	string	注销原因
RevokeDate	string	吊销日期
RevokeReason	string	吊销原因

enterprise.Area 地区信息

字段	类型	说明
Province	string	省份
City	string	城市
County	string	区县

dishonesty 字段说明（740接口返回）

字段	类型	说明
VerifyResult	integer	核查结果：0-无失信记录，1-有失信记录
Data	array	失信记录列表（VerifyResult=0时为null或空数组）

dishonesty.Data[] 失信记录字段说明

字段	类型	说明
Id	string	记录唯一标识
Liandate	string	立案日期（格式：YYYY-MM-DD）
Anno	string	案号
Executegov	string	执行法院
Executestatus	string	执行情况（全部未履行/部分履行/全部履行）
Publicdate	string	发布日期（格式：YYYY-MM-DD）
Executeno	string	执行依据文号
ActionRemark	string	失信被执行人行为具体情形
Amount	string	执行标的金额（元）

响应示例（成功）

{
    "success": true,
    "message": "查询成功",
    "data": {
        "search_key": "腾讯科技（深圳）有限公司",
        "credit_code": "91440300708461136T",
        "company_name": "腾讯科技（深圳）有限公司",
        "enterprise": {
            "KeyNo": "p5ef6e1c39f4817d33dfb4e9",
            "Name": "腾讯科技（深圳）有限公司",
            "No": "440301103206221",
            "BelongOrg": "深圳市市场监督管理局",
            "OperId": "p5ef6e1c39f4817d33dfb4e9op",
            "OperName": "马化腾",
            "DesignatedRepresentativeList": [],
            "StartDate": "2000-02-24 00:00:00",
            "EndDate": "",
            "Status": "存续",
            "Province": "GD",
            "UpdatedDate": "2024-12-10 15:30:00",
            "CreditCode": "91440300708461136T",
            "RegistCapi": "65000万人民币",
            "RegisteredCapital": "65000",
            "RegisteredCapitalUnit": "万",
            "RegisteredCapitalCCY": "CNY",
            "EconKind": "有限责任公司",
            "Address": "深圳市南山区粤海街道科技中一路腾讯大厦35层",
            "Scope": "从事计算机软硬件及周边设备、通讯设备、数码产品、网络设备的技术开发、销售及相关的技术咨询、技术服务；经营进出口业务；从事广告业务；物业管理",
            "TermStart": "2000-02-24 00:00:00",
            "TermEnd": "2050-02-24 00:00:00",
            "CheckDate": "2023-08-15 00:00:00",
            "OrgNo": "708461136",
            "IsOnStock": "1",
            "StockNumber": "00700.HK",
            "StockType": "港股",
            "OriginalName": [
                {
                    "Name": "深圳市腾讯计算机系统有限公司",
                    "ChangeDate": "2000-06-01"
                }
            ],
            "ImageUrl": "https://img.qichacha.com/xxx.png",
            "EntType": "1",
            "RecCap": "65000万人民币",
            "PaidUpCapital": "65000",
            "PaidUpCapitalUnit": "万",
            "PaidUpCapitalCCY": "CNY",
            "RevokeInfo": {
                "CancelDate": "",
                "CancelReason": "",
                "RevokeDate": "",
                "RevokeReason": ""
            },
            "Area": {
                "Province": "广东省",
                "City": "深圳市",
                "County": "南山区"
            },
            "AreaCode": "440305"
        },
        "dishonesty": {
            "VerifyResult": 0,
            "Data": null
        },
        "has_dishonesty": false,
        "dishonesty_count": 0,
        "updated_at": "2024-12-12T10:30:00+08:00"
    }
}

响应示例（有失信记录）

{
    "success": true,
    "message": "查询成功",
    "data": {
        "search_key": "某某建设工程有限公司",
        "credit_code": "91440106MA5CXXXX12",
        "company_name": "某某建设工程有限公司",
        "enterprise": {
            "KeyNo": "abc123def456ghi789jkl",
            "Name": "某某建设工程有限公司",
            "No": "440106000123456",
            "BelongOrg": "广州市天河区市场监督管理局",
            "OperId": "abc123def456ghi789jklop",
            "OperName": "张三",
            "DesignatedRepresentativeList": [],
            "StartDate": "2018-05-10 00:00:00",
            "EndDate": "",
            "Status": "存续",
            "Province": "GD",
            "UpdatedDate": "2024-12-01 09:00:00",
            "CreditCode": "91440106MA5CXXXX12",
            "RegistCapi": "5000万人民币",
            "RegisteredCapital": "5000",
            "RegisteredCapitalUnit": "万",
            "RegisteredCapitalCCY": "CNY",
            "EconKind": "有限责任公司(自然人投资或控股)",
            "Address": "广州市天河区某某路123号",
            "Scope": "建筑工程施工；市政公用工程施工；房屋建筑工程施工；建筑装饰、装修工程施工；园林绿化工程施工",
            "TermStart": "2018-05-10 00:00:00",
            "TermEnd": "2048-05-09 00:00:00",
            "CheckDate": "2023-06-20 00:00:00",
            "OrgNo": "MA5CXXXX1",
            "IsOnStock": "0",
            "StockNumber": null,
            "StockType": null,
            "OriginalName": [],
            "ImageUrl": "",
            "EntType": "1",
            "RecCap": "1000万人民币",
            "PaidUpCapital": "1000",
            "PaidUpCapitalUnit": "万",
            "PaidUpCapitalCCY": "CNY",
            "RevokeInfo": {
                "CancelDate": "",
                "CancelReason": "",
                "RevokeDate": "",
                "RevokeReason": ""
            },
            "Area": {
                "Province": "广东省",
                "City": "广州市",
                "County": "天河区"
            },
            "AreaCode": "440106"
        },
        "dishonesty": {
            "VerifyResult": 1,
            "Data": [
                {
                    "Id": "c2edc410f8ceed3ed256055baa8df1432",
                    "Liandate": "2021-08-10",
                    "Anno": "（2021）粤0106执34224号",
                    "Executegov": "广州市天河区人民法院",
                    "Executestatus": "全部未履行",
                    "Publicdate": "2022-01-07",
                    "Executeno": "（2020）粤0106民初12345号",
                    "ActionRemark": "有履行能力而拒不履行生效法律文书确定义务",
                    "Amount": "1098000"
                }
            ]
        },
        "has_dishonesty": true,
        "dishonesty_count": 1,
        "updated_at": "2024-12-12T10:30:00+08:00"
    }
}

响应示例（失败）

{
    "success": false,
    "message": "当前KEY已欠费",
    "data": null,
    "error_code": "102",
    "error_details": {
        "order_number": "20241212103000123",
        "is_charged": false,
        "is_valid_request": false
    }
}

---

2. 仅查询工商信息

仅查询企业工商信息（410接口），费用 0.20元/次

请求

POST /api/v2/qichacha/enterprise
Content-Type: application/json
Authorization: Bearer <token>

请求参数

同 查询企业信息

响应参数

同 查询企业信息，但 dishonesty 字段为 null

---

3. 仅查询失信信息

仅查询企业失信信息（740接口），费用 0.30元/次

请求

POST /api/v2/qichacha/dishonesty
Content-Type: application/json
Authorization: Bearer <token>

请求参数

同 查询企业信息

响应参数

同 查询企业信息，但 enterprise 字段为 null

---

4. 批量查询企业信息

批量查询多个企业信息，单次最多10个

请求

POST /api/v2/qichacha/batch
Content-Type: application/json
Authorization: Bearer <token>

请求参数

字段	类型	必填	说明
keywords	array[string]	是	查询关键词列表，1-10个
force_refresh	boolean	否	是否强制刷新，默认false

请求示例

{
    "keywords": ["腾讯科技", "阿里巴巴", "华为技术"],
    "force_refresh": false
}

响应参数

字段	类型	说明
success	boolean	是否全部成功
total	integer	总查询数
success_count	integer	成功数
failed_count	integer	失败数
results	array	查询结果列表（每个元素同单个查询响应）

响应示例

注：results 数组中每个元素的 data 结构与单个查询响应的 data 字段完全一致，包含完整的 enterprise 和 dishonesty 对象。

{
    "success": true,
    "total": 3,
    "success_count": 3,
    "failed_count": 0,
    "results": [
        {
            "success": true,
            "message": "查询成功",
            "data": {
                "search_key": "腾讯科技",
                "credit_code": "91440300708461136T",
                "company_name": "腾讯科技（深圳）有限公司",
                "enterprise": {
                    "KeyNo": "p5ef6e1c39f4817d33dfb4e9",
                    "Name": "腾讯科技（深圳）有限公司",
                    "No": "440301103206221",
                    "BelongOrg": "深圳市市场监督管理局",
                    "OperId": "p5ef6e1c39f4817d33dfb4e9op",
                    "OperName": "马化腾",
                    "DesignatedRepresentativeList": [],
                    "StartDate": "2000-02-24 00:00:00",
                    "EndDate": "",
                    "Status": "存续",
                    "Province": "GD",
                    "UpdatedDate": "2024-12-10 15:30:00",
                    "CreditCode": "91440300708461136T",
                    "RegistCapi": "65000万人民币",
                    "RegisteredCapital": "65000",
                    "RegisteredCapitalUnit": "万",
                    "RegisteredCapitalCCY": "CNY",
                    "EconKind": "有限责任公司",
                    "Address": "深圳市南山区粤海街道科技中一路腾讯大厦35层",
                    "Scope": "从事计算机软硬件及周边设备、通讯设备、数码产品、网络设备的技术开发、销售及相关的技术咨询、技术服务；经营进出口业务；从事广告业务；物业管理",
                    "TermStart": "2000-02-24 00:00:00",
                    "TermEnd": "2050-02-24 00:00:00",
                    "CheckDate": "2023-08-15 00:00:00",
                    "OrgNo": "708461136",
                    "IsOnStock": "1",
                    "StockNumber": "00700.HK",
                    "StockType": "港股",
                    "OriginalName": [],
                    "ImageUrl": "https://img.qichacha.com/xxx.png",
                    "EntType": "1",
                    "RecCap": "65000万人民币",
                    "PaidUpCapital": "65000",
                    "PaidUpCapitalUnit": "万",
                    "PaidUpCapitalCCY": "CNY",
                    "RevokeInfo": {
                        "CancelDate": "",
                        "CancelReason": "",
                        "RevokeDate": "",
                        "RevokeReason": ""
                    },
                    "Area": {
                        "Province": "广东省",
                        "City": "深圳市",
                        "County": "南山区"
                    },
                    "AreaCode": "440305"
                },
                "dishonesty": {
                    "VerifyResult": 0,
                    "Data": null
                },
                "has_dishonesty": false,
                "dishonesty_count": 0,
                "updated_at": "2024-12-12T10:30:00+08:00"
            }
        },
        {
            "success": true,
            "message": "查询成功",
            "data": {
                "search_key": "阿里巴巴",
                "credit_code": "91330100799655058B",
                "company_name": "阿里巴巴（中国）有限公司",
                "enterprise": { "/* 完整enterprise对象，结构同上 */" : "..." },
                "dishonesty": { "VerifyResult": 0, "Data": null },
                "has_dishonesty": false,
                "dishonesty_count": 0,
                "updated_at": "2024-12-12T10:31:00+08:00"
            }
        },
        {
            "success": true,
            "message": "查询成功",
            "data": {
                "search_key": "华为技术",
                "credit_code": "914403006194776951",
                "company_name": "华为技术有限公司",
                "enterprise": { "/* 完整enterprise对象，结构同上 */" : "..." },
                "dishonesty": { "VerifyResult": 0, "Data": null },
                "has_dishonesty": false,
                "dishonesty_count": 0,
                "updated_at": "2024-12-12T10:32:00+08:00"
            }
        }
    ]
}

---

5. 查询数据库记录状态

查询企业在数据库中的记录状态（不调用企查查API，不产生费用）

请求

GET /api/v2/qichacha/status?keyword=腾讯科技
Authorization: Bearer <token>

请求参数

字段	类型	必填	说明
keyword	string	是	查询关键词，最少2字符

响应参数

字段	类型	说明
exists	boolean	记录是否存在
keyword	string	查询关键词
search_key	string	数据库中的search_key
credit_code	string	统一社会信用代码
company_name	string	企业名称
has_enterprise	boolean	是否有工商信息
has_dishonesty	boolean	是否有失信信息
updated_at	datetime	数据更新时间
age_days	integer	数据已存在天数
refresh_threshold_days	integer	刷新阈值（默认30天）
need_refresh	boolean	是否需要刷新

响应示例（有记录）

{
    "exists": true,
    "keyword": "腾讯科技",
    "search_key": "腾讯科技（深圳）有限公司",
    "credit_code": "91440300708461136T",
    "company_name": "腾讯科技（深圳）有限公司",
    "has_enterprise": true,
    "has_dishonesty": true,
    "updated_at": "2024-12-01T10:30:00+08:00",
    "age_days": 11,
    "refresh_threshold_days": 30,
    "need_refresh": false
}

响应示例（无记录）

{
    "exists": false,
    "keyword": "某某不存在的公司"
}

---

错误码

企查查API状态码

有效请求（会计费）

状态码	说明
200	查询成功
201	查询无结果
202	查询参数错误
205	等待处理中
207	请求数据条目数超过上限
208	此接口不支持此公司类型查询
209	企业数量超过上限
213	参数长度不能小于2
215	不支持的查询关键字

无效请求（不计费）

状态码	说明
101	当前的KEY无效或还未生效
102	当前KEY已欠费
103	当前KEY被暂停使用
107	被禁止的IP或签名错误
111	接口权限未开通
112	账号剩余使用量不足或已过期

HTTP状态码

状态码	说明
200	成功
401	未认证（Token无效或过期）
403	无权限（缺少qichacha:company:query权限）
500	服务器内部错误

---

配置说明

在环境配置文件中添加：

# 企查查API配置
QCC_APP_KEY=你的AppKey
QCC_SECRET_KEY=你的SecretKey

# 可选配置
QCC_BASE_URL=https://api.qichacha.com
QCC_TIMEOUT=30
QCC_CACHE_DAYS=30

---

使用示例

cURL

# 查询企业信息
curl -X POST "http://localhost:8000/api/v2/qichacha/company" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_token>" \
  -d '{"keyword": "腾讯科技", "force_refresh": false}'

# 批量查询
curl -X POST "http://localhost:8000/api/v2/qichacha/batch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_token>" \
  -d '{"keywords": ["腾讯", "阿里", "华为"]}'

# 查询记录状态
curl -X GET "http://localhost:8000/api/v2/qichacha/status?keyword=腾讯" \
  -H "Authorization: Bearer <your_token>"

Python

import httpx

async def query_company(keyword: str, token: str):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "http://localhost:8000/api/v2/qichacha/company",
            json={"keyword": keyword, "force_refresh": False},
            headers={"Authorization": f"Bearer {token}"}
        )
        return response.json()

JavaScript

async function queryCompany(keyword, token) {
    const response = await fetch('/api/v2/qichacha/company', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${token}`
        },
        body: JSON.stringify({
            keyword: keyword,
            force_refresh: false
        })
    });
    return await response.json();
}