文档版本：2026.08.28 API 版本：v1 面向对象：获得 GlobalCheck API Key 的客户及合作方

GlobalCheck API 提供企业检索、企业身份解析、企业详情、股权关系、财务数据和批量导出能力。本文档描述当前面向客户开放的 API Key 接口。

1. 接入信息

1.1 服务地址

https://api.globalcheck.cn

本文所有接口和示例均使用上述正式服务地址。除健康检查和公开统计接口外，请求均须携带 API Key。

Swagger 与 OpenAPI 定义仅展示当前面向客户开放的接口，不包含账户、管理后台或内部子系统接口。

1.2 获取 API Key

请联系 support@globalcheck.cn 申请 API Key、接口权限和调用额度。API Key 的典型格式为：

ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

调用频率、每日额度及可访问的数据模块按客户服务方案配置，不同 API Key 可能不同。

1.3 认证方式

在每个受保护请求的 Header 中传入：

X-API-Key: ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

快速验证：

curl "https://api.globalcheck.cn/api/v1/companies/search?q=China%20Mobile&country=HK&limit=5" \
  -H "X-API-Key: $GLOBALCHECK_API_KEY"

API Key 必须只保存在服务端，不应写入浏览器代码、移动端安装包、公开仓库或日志。

2. 基本约定

2.1 请求与响应

• JSON 请求使用 Content-Type: application/json。
• JSON 响应使用 UTF-8 编码。
• 国家/地区参数使用 ISO 3166-1 alpha-2 代码，例如 CN、HK、US。
• 日期优先使用 ISO 8601 格式；部分源数据会保留原始日期格式，调用方应按实际字段定义解析。
• 金额、币种、比例和单位以响应中的原始字段为准，不应仅依据字段名称推断单位。
• 企业数据具有稀疏性。没有数据的模块可能返回空数组 []、空对象 {} 或 null，不代表请求失败。

2.2 Apex ID

company_id 是 GlobalCheck 的企业主键，也称 Apex ID，例如：

HK-HK1-2MN77ST0ORX6-3

调用方应将 Apex ID 视为不透明、稳定的字符串，不要自行解析或拼接。名称搜索获得候选企业后，使用返回的 Apex ID 查询详情。注册号、LEI、SWIFT/BIC、税号等识别码应调用 IDR 接口解析为 Apex ID。

2.3 名称搜索与识别码解析

不要把注册号或 LEI 放入普通名称搜索框中代替 IDR 调用。

2.4 分页

企业搜索使用偏移量分页：

• skip：跳过的记录数，默认 0。
• limit：每页记录数，默认 20，最大 100。
• has_more：是否还有下一页。

下一页的 skip 可按 skip + limit 计算。

3. 接口总览

3.1 企业检索与详情

3.2 身份解析、股权和财务

3.3 批量导出

3.4 公开接口

4. 企业名称搜索

GET /api/v1/companies/search

按企业名称搜索候选企业，可附加国家、城市、邮编、行业和状态条件。

请求示例：

curl --get "https://api.globalcheck.cn/api/v1/companies/search" \
  -H "X-API-Key: $GLOBALCHECK_API_KEY" \
  --data-urlencode "q=China Mobile" \
  --data-urlencode "country=HK" \
  --data-urlencode "limit=10"

响应示例，字段仅作示意，实际字段取决于数据可用性：

{
  "items": [
    {
      "company_id": "HK-HK1-2MN77ST0ORX6-3",
      "company_name": "CHINA MOBILE LIMITED",
      "company_name_en": "CHINA MOBILE LIMITED",
      "primary_city": "HONG KONG",
      "primary_country": "香港特区，中国",
      "primary_country_iso_code": "HK",
      "standardized_country": "Hong Kong",
      "status": ["Active"],
      "date_of_incorporation": "09/03/1997",
      "type_of_entity": "Corporate"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10,
  "has_more": false
}

total 表示本次搜索路径返回的候选总量。对于超大候选集，服务可能采用查询保护策略；需要全量批处理时请联系 GlobalCheck 确认交付方式。

5. 企业身份解析 IDR

POST /api/v1/idr/resolve

IDR 用于把客户输入的企业名称或识别码解析为 GlobalCheck Apex ID，并返回匹配置信度、候选和证据。该接口只读，不会修改企业数据库。

5.1 请求字段

至少应提供一个有意义的名称或识别码。只提供企业名称时，建议同时提供 country；强识别码优先于名称进行匹配。

5.2 按 LEI 解析

curl "https://api.globalcheck.cn/api/v1/idr/resolve" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GLOBALCHECK_API_KEY" \
  -d '{
    "country": "HK",
    "lei": "529900U2JJ7GK68NI589"
  }'

5.3 按注册号解析

{
  "country": "HK",
  "reg_number": "0622909"
}

5.4 按名称消歧

{
  "company_name": "China Mobile Limited",
  "country": "HK",
  "city": "Hong Kong"
}

响应示例：

{
  "record_id": "idr_01J...",
  "status": "AUTO_MATCH",
  "confidence": 61.0,
  "confidence_band": "LOW",
  "recommended_action": "ACCEPT",
  "apex_id": "HK-HK1-2MN77ST0ORX6-3",
  "matched_name": "CHINA MOBILE LIMITED",
  "matched_country": "HK",
  "matched_status": "Active",
  "mgs": "ZAZAZZ",
  "evidence": {},
  "candidates": [
    {
      "rank": 1,
      "apex_id": "HK-HK1-2MN77ST0ORX6-3",
      "name": "CHINA MOBILE LIMITED",
      "country": "HK",
      "status": "Active",
      "reg_number": "21330874",
      "lei": "529900U2JJ7GK68NI589",
      "score": 61.0,
      "mgs": "ZAZAZZ",
      "source": "STRONG_ID",
      "evidence": {}
    }
  ],
  "decision_meta": {
    "strong_id_hit": true,
    "strong_id_field": "lei",
    "forced_review_reason": "STRONG_ID_UNIQUE"
  },
  "processing_time_ms": 29
}

5.5 决策状态

confidence_band 的可能值为 HIGH、MEDIUM、LOW、NONE。唯一强识别码命中时，即使综合分数不高，结果也可能是 AUTO_MATCH；因此不要仅依据 confidence 数值覆盖 recommended_action，应结合 status、decision_meta 和 evidence 决策。

6. 企业详情

6.1 企业概览

GET /api/v1/companies/{company_id}/overview

curl "https://api.globalcheck.cn/api/v1/companies/HK-HK1-2MN77ST0ORX6-3/overview?detail_level=basic" \
  -H "X-API-Key: $GLOBALCHECK_API_KEY"

basic 返回企业核心概览；detailed 返回可用的扩展字段。字段会随数据覆盖情况和数据版本变化，调用方应按字段名读取并容忍新增字段与空值。

6.2 详情模块

以下接口均只需要路径参数 company_id：

示例：

curl "https://api.globalcheck.cn/api/v1/companies/HK-HK1-2MN77ST0ORX6-3/identification" \
  -H "X-API-Key: $GLOBALCHECK_API_KEY"

6.3 判断企业是否存在

GET /api/v1/companies/{company_id}/exists

{
  "exists": true,
  "companyId": "HK-HK1-2MN77ST0ORX6-3"
}

7. 股权关系与财务数据

7.1 股权关系

curl "https://api.globalcheck.cn/api/v1/ownership/HK-HK1-2MN77ST0ORX6-3/shareholders" \
  -H "X-API-Key: $GLOBALCHECK_API_KEY"

股权接口通常返回数组。每条记录可能包含关联方名称、关联方 Apex ID、持股比例、关系类型、来源日期等字段，具体取决于该企业的数据覆盖情况。

可用关系：

• shareholders：股东。
• subsidiaries：子公司。
• branches：分支机构。
• private-equity：私募股权关系。

7.2 财务数据

GET /api/v1/financials/{company_id}

curl "https://api.globalcheck.cn/api/v1/financials/HK-HK1-2MN77ST0ORX6-3" \
  -H "X-API-Key: $GLOBALCHECK_API_KEY"

响应通常为按报告期排列的财务记录数组。不同国家、企业和报告期的可用科目可能不同，调用方应保留币种、单位、报告期和合并口径字段。

8. 批量导出

导出接口适用于服务端生成 xlsx、csv 或 json 文件。较小任务可能同步完成，较大任务返回异步任务 ID。

8.1 创建任务

POST /api/v1/export/create

请求字段：

curl "https://api.globalcheck.cn/api/v1/export/create" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GLOBALCHECK_API_KEY" \
  -d '{
    "type": "search_results",
    "module": "company_overview",
    "filters": {"country": "HK", "status": "Active"},
    "format": "xlsx",
    "fields_layer": "B"
  }'

响应：

{
  "task_id": "export_01J...",
  "status": "pending",
  "is_async": true,
  "total_records": 25000,
  "estimated_time": 120,
  "check_url": "/api/v1/export/export_01J.../status",
  "download_url": null
}

8.2 查询任务状态

GET /api/v1/export/{task_id}/status

{
  "task_id": "export_01J...",
  "status": "processing",
  "progress": 48,
  "total_records": 25000,
  "processed_records": 12000,
  "created_at": "2026-08-28T10:00:00",
  "started_at": "2026-08-28T10:00:01",
  "completed_at": null,
  "estimated_completion": "2026-08-28T10:02:05",
  "file_size": null,
  "error_message": null
}

任务状态包括 pending、processing、completed、failed 和 cancelled。建议轮询间隔不低于 2 秒，并在客户端设置总体超时和退避策略。

8.3 下载文件

GET /api/v1/export/{task_id}/download

仅 completed 状态可下载。下载请求同样必须携带 X-API-Key：

curl "https://api.globalcheck.cn/api/v1/export/export_01J.../download" \
  -H "X-API-Key: $GLOBALCHECK_API_KEY" \
  --output globalcheck-export.xlsx

导出文件默认保留 7 天。应在任务完成后及时下载，不要长期依赖下载 URL。

8.4 取消及查询任务

DELETE /api/v1/export/{task_id}
GET /api/v1/export/my-tasks?status=completed&limit=20
GET /api/v1/export/statistics

只有等待中的任务可以取消。已经处理中的任务可能无法立即终止。

9. 公开统计与健康检查

9.1 健康检查

GET /health

curl "https://api.globalcheck.cn/health"

HTTP 200 表示服务可用；HTTP 503 表示服务暂时异常。健康检查响应可能增加扩展字段，监控程序应以 HTTP 状态码和顶层 status 字段为准。

9.2 国家/地区企业数量

GET /api/v1/companies/statistics/countries

返回以 ISO2 代码为键的企业数量映射：

{
  "CN": 0,
  "HK": 0,
  "US": 0
}

上例中的数量仅说明结构，不代表当前实际统计值。

9.3 数据总量摘要

GET /api/v1/companies/statistics/summary

返回当前企业总量、覆盖国家/地区数等摘要。统计值会随数据更新变化，不应在客户端写死。

10. 错误处理

错误响应通常采用统一的 detail 结构：

{
  "detail": "Company not found: HK-EXAMPLE"
}

常见 HTTP 状态码：

缺少 API Key：

{
  "detail": "Missing API Key"
}

限流响应示例：

{
  "detail": {
    "error": "Rate limit exceeded",
    "reason": "requests_per_minute",
    "quota": 100,
    "usage": 100,
    "remaining": 0,
    "reset_at": "2026-08-28T10:01:00Z"
  }
}

对于 429、500 和 503，建议采用带随机抖动的指数退避。写操作或计费操作重试时，应由调用方保存业务幂等标识，避免重复提交。

11. SDK 调用示例

11.1 Python

import os
import requests

BASE_URL = "https://api.globalcheck.cn"
HEADERS = {"X-API-Key": os.environ["GLOBALCHECK_API_KEY"]}

response = requests.get(
    f"{BASE_URL}/api/v1/companies/search",
    headers=HEADERS,
    params={"q": "China Mobile", "country": "HK", "limit": 10},
    timeout=30,
)
response.raise_for_status()

for company in response.json()["items"]:
    print(company["company_id"], company.get("company_name"))

11.2 JavaScript / Node.js

const baseUrl = "https://api.globalcheck.cn";
const url = new URL("/api/v1/idr/resolve", baseUrl);

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.GLOBALCHECK_API_KEY,
  },
  body: JSON.stringify({
    country: "HK",
    lei: "529900U2JJ7GK68NI589",
  }),
  signal: AbortSignal.timeout(30000),
});

if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}

console.log(await response.json());

12. 兼容性与支持

• 当前稳定前缀为 /api/v1。
• v1 内可能新增可选字段。调用方应忽略未知字段，不应因新增字段失败。
• 删除字段、改变字段含义或其他破坏性变更将通过新版本前缀或迁移通知发布。
• 数据来源和覆盖率因国家、企业、报告期及模块而异。
• 文档示例用于说明接口结构，不构成对具体企业数据的承诺。

技术支持：support@globalcheck.cn