# GlobalCheck API 接入文档

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

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

## 1. 接入信息

### 1.1 服务地址

```text
https://api.globalcheck.cn
```

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

| 资源 | 地址 |
|---|---|
| 开发者接入指南 | [https://globalcheck.cn/developers/api](https://globalcheck.cn/developers/api) |
| 交互式 Swagger | [https://api.globalcheck.cn/docs](https://api.globalcheck.cn/docs) |
| OpenAPI 定义 | [https://api.globalcheck.cn/openapi.json](https://api.globalcheck.cn/openapi.json) |

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

### 1.2 获取 API Key

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

```text
ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

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

### 1.3 认证方式

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

```http
X-API-Key: ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

快速验证：

```bash
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**，例如：

```text
HK-HK1-2MN77ST0ORX6-3
```

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

### 2.3 名称搜索与识别码解析

| 需求 | 应使用的接口 |
|---|---|
| 按企业名称查找候选 | `GET /api/v1/companies/search` |
| 按名称加国家、城市等信息消歧 | `POST /api/v1/idr/resolve` |
| 按注册号、LEI、SWIFT/BIC、税号查找 | `POST /api/v1/idr/resolve` |
| 已知 Apex ID 查询企业详情 | `GET /api/v1/companies/{company_id}/overview` |

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

### 2.4 分页

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

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

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

## 3. 接口总览

### 3.1 企业检索与详情

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/v1/companies/search` | 按名称及辅助条件搜索企业 |
| GET | `/api/v1/companies/filter-options` | 获取企业搜索筛选项 |
| GET | `/api/v1/companies/{company_id}/exists` | 判断 Apex ID 是否存在 |
| GET | `/api/v1/companies/{company_id}/overview` | 企业概览 |
| GET | `/api/v1/companies/{company_id}/contacts` | 联系方式与地址 |
| GET | `/api/v1/companies/{company_id}/industry` | 行业分类 |
| GET | `/api/v1/companies/{company_id}/identification` | 企业识别码 |
| GET | `/api/v1/companies/{company_id}/legal-info` | 法律与登记信息 |
| GET | `/api/v1/companies/{company_id}/directors` | 董事及管理人员 |
| GET | `/api/v1/companies/{company_id}/auditors-advisors` | 审计师及顾问 |
| GET | `/api/v1/companies/{company_id}/segments` | 业务线与地区分部 |
| GET | `/api/v1/companies/{company_id}/risk-assessment` | 国家/地区及行业风险评估 |
| GET | `/api/v1/companies/{company_id}/trade-payment` | 贸易支付风险 |

### 3.2 身份解析、股权和财务

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/v1/idr/resolve` | 企业身份解析，返回 Apex ID 候选及证据 |
| GET | `/api/v1/ownership/{company_id}/shareholders` | 股东 |
| GET | `/api/v1/ownership/{company_id}/subsidiaries` | 子公司 |
| GET | `/api/v1/ownership/{company_id}/branches` | 分支机构 |
| GET | `/api/v1/ownership/{company_id}/private-equity` | 私募股权关系 |
| GET | `/api/v1/financials/{company_id}` | 企业财务数据 |

### 3.3 批量导出

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/v1/export/create` | 创建导出任务 |
| GET | `/api/v1/export/{task_id}/status` | 查询任务状态 |
| GET | `/api/v1/export/{task_id}/download` | 下载导出文件 |
| DELETE | `/api/v1/export/{task_id}` | 取消等待中的任务 |
| GET | `/api/v1/export/my-tasks` | 查询导出任务列表 |
| GET | `/api/v1/export/statistics` | 查询导出任务统计 |

### 3.4 公开接口

| 方法 | 路径 | 认证 | 说明 |
|---|---|---|---|
| GET | `/health` | 无 | 服务健康检查 |
| GET | `/api/v1/companies/statistics/countries` | 无 | 按国家/地区统计企业数量 |
| GET | `/api/v1/companies/statistics/summary` | 无 | 企业数据总量摘要 |

## 4. 企业名称搜索

### GET `/api/v1/companies/search`

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

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `q` | string | 否 | 企业名称关键词 |
| `country` | string | 否 | ISO2 国家/地区代码 |
| `city` | string | 否 | 城市前缀 |
| `postcode` | string | 否 | 邮编前缀 |
| `industry` | string | 否 | NACE 行业代码 |
| `status` | string | 否 | 企业状态，例如 `Active` |
| `skip` | integer | 否 | 分页偏移，默认 `0` |
| `limit` | integer | 否 | 返回数量，默认 `20`，最大 `100` |

请求示例：

```bash
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"
```

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

```json
{
  "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 请求字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `company_name` | string | 否 | 企业名称 |
| `country` | string | 否 | ISO2 国家/地区代码，名称匹配时强烈建议提供 |
| `apex_id` | string | 否 | 已知 Apex ID |
| `reg_number` | string | 否 | 企业注册号或贸易登记号，按源数据口径匹配 |
| `lei` | string | 否 | Legal Entity Identifier |
| `swift_bic` | string | 否 | SWIFT/BIC |
| `tax_id` | string | 否 | 税号 |
| `website` | string | 否 | 企业官网或邮箱域名 |
| `city` | string | 否 | 城市 |
| `postcode` | string | 否 | 邮编 |
| `_custom` | object | 否 | 预留的客户扩展字段，当前不参与匹配；不要依赖响应回传 |

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

### 5.2 按 LEI 解析

```bash
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 按注册号解析

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

### 5.4 按名称消歧

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

响应示例：

```json
{
  "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 决策状态

| `status` | 含义 | 建议处理 |
|---|---|---|
| `AUTO_MATCH` | 可以自动接受的高可信匹配 | 使用返回的 Apex ID |
| `REVIEW` | 存在冲突或候选差距不足 | 人工复核候选和证据 |
| `CANDIDATES_ONLY` | 有候选，但信息不足以自动确认 | 补充国家或识别码后重试 |
| `NO_MATCH` | 未找到可靠候选 | 检查输入或转人工处理 |
| `NEED_MORE_INFO` | 输入信息不足 | 至少补充有效名称或识别码 |

`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`

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `company_id` | path | string | 是 | Apex ID |
| `detail_level` | query | string | 否 | `basic` 或 `detailed`，默认 `basic` |

```bash
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`：

| 路径后缀 | 典型内容 | 无数据时常见响应 |
|---|---|---|
| `/contacts` | 地址、电话、邮箱、网站 | `[]` |
| `/industry` | NACE、NAICS、SIC 及行业描述 | `{}` 或 `[]` |
| `/identification` | 注册号、LEI、税号及其他识别码 | `{}` |
| `/legal-info` | 法律形态、登记状态、成立日期 | `{}` |
| `/directors` | 董事和管理人员 | `[]` |
| `/auditors-advisors` | 审计师、律师和顾问 | `[]` |
| `/debt` | 债务工具及债务信息 | `[]` |
| `/funds` | 关联基金 | `[]` |
| `/segments` | `business_lines` 与 `geographic_segments` | 两个空数组 |
| `/risk` | 企业风险相关字段 | `{}` |
| `/risk-assessment` | 国家/地区风险与行业风险评估 | `{}` 或业务状态对象 |
| `/trade-payment` | 贸易支付风险评分与历史 | `{}` |
| `/stock` | 交易所、Ticker、ISIN 等上市信息 | `null` 或 `{}` |

示例：

```bash
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`

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

## 7. 股权关系与财务数据

### 7.1 股权关系

```bash
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}`

```bash
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`

请求字段：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `type` | string | 是 | `search_results`、`company_full`、`companies_batch` 或 `module_export` |
| `module` | string | 是 | 导出的业务模块 |
| `filters` | object | 否 | 模块对应的筛选条件 |
| `format` | string | 否 | `xlsx`、`csv` 或 `json`，默认 `xlsx` |
| `fields_layer` | string | 否 | `A` 基础、`B` 详细、`C` 完整，默认 `B` |
| `filename` | string | 否 | 自定义文件名 |

```bash
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"
  }'
```

响应：

```json
{
  "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`

```json
{
  "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`：

```bash
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 取消及查询任务

```http
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`

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

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

### 9.2 国家/地区企业数量

### GET `/api/v1/companies/statistics/countries`

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

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

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

### 9.3 数据总量摘要

### GET `/api/v1/companies/statistics/summary`

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

## 10. 错误处理

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

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

常见 HTTP 状态码：

| 状态码 | 含义 | 建议处理 |
|---|---|---|
| `400` | 请求业务状态不允许，例如任务尚未完成 | 修正参数或等待任务状态变化 |
| `401` | 缺少或无效 API Key | 检查 `X-API-Key` Header |
| `403` | API Key 已禁用或未开通所需权限 | 联系管理员确认 Key 状态和权限 |
| `404` | 企业、任务或文件不存在 | 检查 Apex ID、任务 ID 或文件有效期 |
| `422` | 参数类型或请求体校验失败 | 按响应中的字段错误修正请求 |
| `429` | 调用频率或额度超限 | 按配额窗口退避，不要立即高频重试 |
| `500` | 服务内部错误 | 记录请求时间和业务标识后联系支持 |
| `503` | 数据库、额度服务或其他依赖暂不可用 | 指数退避后重试 |

缺少 API Key：

```json
{
  "detail": "Missing API Key"
}
```

限流响应示例：

```json
{
  "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

```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

```javascript
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`