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

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

企业三端统一模块

新接入建议使用以下模块接口；现有独立接口仍保留，响应结构不变。

• GET /api/v1/companies/module-catalog：获取版本、模块顺序、名称、权限及子章节定义。
• GET /api/v1/companies/{company_id}/modules/{module_id}：获取某企业的完整模块数据。

返回结构包含 schema_version、company_id、module_id、label、status、sections 和 data。 sections 按目录顺序返回；每个章节含标准字段数据、字段标签、类型、分组及展示格式。 data 是按章节 key 组织的同一份数据，便于客户端取值。

status=available 表示存在数据，no_data 表示暂无数据，不代表权限不足或查询失败。 未授权返回 401/403，超额返回 429；企业或模块不存在返回 404；查询故障返回错误而非伪装为空结果。

金额字段通过 fields[field].format=amount 标明。接口保留映射值，页面和 PDF 展示金额采用千分位及两位小数； 行业代码、标识符、年份、人数和比例不得据数值外观套用金额格式。金额币种和原始单位仍由关联字段说明，不自动换算。 数组保留位置和空值，不能独立过滤多个并行数组后再进行配对。

PDF 使用同一模块取数服务和目录；企业报告下载权限及管理员字段导出开关独立生效。 该约定不包含暂不可用的股票、债券、基金和旧风险信息接口，也不替代独立的风险评估、制裁筛查或行业报告。

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 决策。

5.6 批量 IDR

可在 GlobalCheck 顶部的“批量匹配”进入文件任务界面，也可以直接调用 API。 支持正式服务端 X-API-Key（需要 globalcheck.api_access）或用户 Bearer/Cookie 会话。 旧的开发 Key 不支持批量 IDR。企业成员按企业共享额度计费，任务和结果仅对提交者可见。

文件与限制：CSV（UTF-8/BOM 或 GB18030），或只有一个工作表的 XLSX。最多 1,000 行企业数据、5 MB；每个用户或 Key 同时只允许一个活动任务。该上限用于约束逐企业匹配的数据库负载和等待时间，不承诺固定完成时长。

下载模板：GET /api/v1/idr/batch-template?format=xlsx，也支持 format=csv。 第一行必须是英文列名，不接受重复列、额外列或公式。所有非空 Excel 单元格必须为文本，避免注册号、邮编等前导零被丢失。

每行至少提供以下一组：公司名称（country可选）、注册号+country、税号+country、apex_id、lei 或 swift_bic。仅提供名称时允许匹配，但同名企业可能跨多个国家，通常需根据候选结果人工确认；提供country可缩小范围。不要求所有列均存在，但推荐保留模板列。空行跳过；重复企业行不自动去重，按实际提交行数计费。任一非空行格式错误则整批拒绝，不扣费。

reference,company_name,country,apex_id,reg_number,lei,swift_bic,tax_id,website,city,postcode
customer-001,China Mobile Limited,HK,,,,,,,Hong Kong,

上传创建任务，X-Business-Action-Id 必填（8–128字符），同一次上传重试必须沿用此值；相同值上传不同数据会返回409：

curl -X POST 'https://api.globalcheck.cn/api/v1/idr/batches' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-Business-Action-Id: idr-upload-20261028-001' \
  -F 'file=@companies.xlsx'

接口返回202和 task_id，文件校验通过不代表任务已经完成或预扣成功：

建议每5秒查询一次进度。状态依次为 queued → processing → settling → completed，也可能为 failed 或 cancelled。 matched 仅统计 AUTO_MATCH，并不代表其它结果都是执行失败。 CSV及Excel摘要包含原始行号、reference、输入字段、匹配状态、综合证据分（confidence）、名称相似度（name_similarity_pct）、建议操作、判断原因和首选候选Apex ID（matched_apex_id）。原始输入列apex_id不会被覆盖。confidence不是名称相似度，也不是匹配正确的概率；仅名称完全一致并且状态存续时，综合分可能为43，而名称相似度为100。 Excel包含三个工作表：IDR为逐行摘要，Candidates为全部已保留候选明细，Readme解释字段和状态。候选表通过row_number和reference关联输入，包含国家、城市、地址、网站、注册号、LEI和评分等核验信息。 candidate_count是已保留候选数（最多20），candidates_generated是召回后参与评分的候选数，均不是全库同名企业总数；非AUTO_MATCH状态下，matched_*仅代表排名第一的候选，不表示已确认匹配。JSONL保留完整候选及匹配证据。 任务执行中也可下载已处理的部分结果，取消或失败后仍可下载已完成行。结果可访问7天，后台数据最长保留30天后自动清理。

计费：后台开始执行前，原子预扣全部有效企业行数。登录用户扣“企业搜索”额度；服务端Key扣自身日/月/总额度，共用原有Key计数器。不额外收取上传、模板、进度查询或结果下载次数，但这些接口仍受访问频率限制。 额度不足则任务失败，整批不执行、不部分扣费。NO_MATCH、REVIEW、NEED_MORE_INFO 等业务结果照常计费；系统异常行、取消或终止后未处理行在结算时退回。 charged 为预扣，refunded 为退回，consumed 为净消耗。下载文件不再扣报告导出额度。 服务重启后自动从逐行检查点恢复，已提交的扣费凭据和退款凭据均具备幂等保护。Key撤销或企业归属变更时停止剩余处理，并结算未处理额度。

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