> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 公司开户与审核

> 提交公司开户申请并异步完成 KYB 审核、查询审核进度与结果、被拒后按原申请重提，含完整字段表、请求响应示例与错误码。

## 📄 正文

无论您服务的是贸易企业、Web3 项目方还是跨境电商，都可以通过本页的三个接口为企业客户完成开户：提交申请（`apply`）、查询结果（`query-apply`）、被拒后重提（`resubmit`）。开户是异步流程——接口同步只返回申请单与 `PENDING` 状态，受理成功不等于开户成功，最终结果以 Webhook 推送为主、查询接口轮询为兜底。整体调用顺序见概述页[管理公司](./managing-companies)。

## 提交开户申请

**`POST /open-api-corp/organization/v1/apply`**

提交公司资料后，DCS 异步进行企业尽职调查（KYB）；受理即返回 `organizationApplyId`，同步响应中 `status` 固定为 `PENDING`。

### 请求参数

| 字段                          | 类型        |  必填 | 说明                                                                                                                                                 |
| --------------------------- | --------- | :-: | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `organizationRef`           | string    |  是  | ≤64；合作伙伴侧公司唯一标识（幂等键）；字符集 `^[A-Za-z0-9_-]+$`                                                                                                        |
| `organizationName`          | string    |  是  | ≤256；公司法定名称；仅允许英文、数字、空格                                                                                                                            |
| `companyRegistrationNumber` | string    |  是  | ≤64；公司注册号                                                                                                                                          |
| `email`                     | string    |  是  | ≤128；公司联系邮箱                                                                                                                                        |
| `fundingCurrencies`         | string\[] |  是  | 资金池币种，`USD` / `HKD`，一个或多个（各币种各建一个资金池虚拟账户 VA）；元素不可空、币种不可重复，空/重复/非枚举返回 `DAPI_PARAM_INVALID`；还须为本企业允许币种的子集，超出范围整单拒绝（不做部分开通），返回 `CURRENCY_NOT_ALLOWED` |

<Warning>
  **去重按三个维度判定**：`organizationRef`、`email`、`companyRegistrationNumber` 在合作伙伴维度唯一，后两者**即使被拒也不释放**。同一 `organizationRef` 已有在途或已成功的申请再提，返回 `APPLY_DUPLICATE`；仅存在被拒申请时返回 `APPLY_REJECTED_USE_RESUBMIT`——正确路径是 `resubmit` 沿用同一 `organizationApplyId` 重提，不要换 ID 重发。
</Warning>

### 请求示例

```json theme={null}
{
  "organizationRef": "ext-company-001",
  "organizationName": "EXAMPLE COMPANY LIMITED",
  "companyRegistrationNumber": "CR1234567",
  "email": "finance@example.com",
  "fundingCurrencies": ["USD", "HKD"]
}
```

### 响应示例

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "organizationApplyId": "5136744097353943553",
    "organizationRef": "ext-company-001",
    "status": "PENDING"
  }
}
```

### 响应字段（`data`）

| 字段                    | 类型     | 说明                         |
| --------------------- | ------ | -------------------------- |
| `organizationApplyId` | string | 开户申请 ID，后续查询与重提都用它         |
| `organizationRef`     | string | 回显合作伙伴侧标识                  |
| `status`              | string | 固定为 `PENDING`（已受理，KYB 处理中） |

### 错误码

| 错误码                              | 说明                                                      |
| -------------------------------- | ------------------------------------------------------- |
| `APPLY_DUPLICATE`                | 同一 `organizationRef` 已存在在途/已成功的申请，不可重复提交                |
| `APPLY_REJECTED_USE_RESUBMIT`    | 同一 `organizationRef` 仅存在被拒申请，改用重新提交开户审核（不再放行重复 `apply`） |
| `EMAIL_DUPLICATE`                | 同合作伙伴下该 `email` 已被占用（企业级，任意状态含被拒）                       |
| `COMPANY_REGISTRATION_DUPLICATE` | 同合作伙伴下相同 `companyRegistrationNumber` 已被申请（企业级，任意状态含被拒）  |
| `CURRENCY_NOT_ALLOWED`           | 申请币种不在该企业允许的币种列表内（`message` 点名具体币种）                     |

## 查询开户申请

**`GET /open-api-corp/organization/v1/query-apply`**

查询开户申请的审核进度与结果。建议以 Webhook 推送为主、本接口轮询为兜底。

### 请求参数

| 字段                    | 类型     |  必填 | 说明          |
| --------------------- | ------ | :-: | ----------- |
| `organizationApplyId` | string |  是  | ≤20；开户申请 ID |

```http theme={null}
GET /open-api-corp/organization/v1/query-apply?organizationApplyId=5136744097353943553
```

### 响应字段（`data`）

| 字段                    | 类型     | 说明                                                              |
| --------------------- | ------ | --------------------------------------------------------------- |
| `organizationApplyId` | string | 申请 ID                                                           |
| `organizationRef`     | string | 合作伙伴侧标识                                                         |
| `status`              | string | `PENDING`（审核中，KYB 处理中）/ `SUCCEED`（开户成功）/ `REJECTED`（未通过，KYB 拒绝） |
| `rejectMessage`       | string | 拒绝原因（`REJECTED` 时返回）                                            |
| `organizationId`      | string | 落实体后的公司 ID，`SUCCEED` 后才有——请落库，后续所有公司接口都用它                       |

### 响应示例：开户成功

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "organizationApplyId": "5136744097353943553",
    "organizationRef": "ext-company-001",
    "status": "SUCCEED",
    "rejectMessage": null,
    "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f"
  }
}
```

### 响应示例：审核拒绝

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "organizationApplyId": "5136744097353943553",
    "organizationRef": "ext-company-001",
    "status": "REJECTED",
    "rejectMessage": "registration number mismatch",
    "organizationId": null
  }
}
```

<Note>
  外壳 `code=SYS_SUCCESS` 只代表查询本身成功，业务结果以 `data.status` 为准：`REJECTED` 时读取 `rejectMessage` 了解拒绝原因，修正资料后走下文的重提接口。
</Note>

### 错误码

| 错误码               | 说明                |
| ----------------- | ----------------- |
| `APPLY_NOT_FOUND` | 开户申请不存在（或不属本合作伙伴） |

## 被拒后重提

**`POST /open-api-corp/organization/v1/resubmit`**

KYB 被拒后修正资料，按同一 `organizationApplyId` 重新送审；`organizationRef` 不可变更。仅当申请当前状态为 `REJECTED` 时允许重提——在途或已成功的申请无需也不允许重提，误调返回 `STATUS_CONFLICT`。

### 请求参数

| 字段                          | 类型     |  必填 | 说明                          |
| --------------------------- | ------ | :-: | --------------------------- |
| `organizationApplyId`       | string |  是  | ≤20；被拒的开户申请 ID              |
| `organizationName`          | string |  是  | ≤256；修正后的公司法定名称；仅允许英文、数字、空格 |
| `companyRegistrationNumber` | string |  是  | ≤64；修正后的公司注册号               |

### 请求示例

```json theme={null}
{
  "organizationApplyId": "5136744097353943553",
  "organizationName": "EXAMPLE COMPANY LIMITED",
  "companyRegistrationNumber": "CR7654321"
}
```

### 响应示例

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "organizationApplyId": "5136744097353943553",
    "organizationRef": "ext-company-001",
    "status": "PENDING"
  }
}
```

重提受理后申请回到 `PENDING`，结果获取方式与首次申请一致（Webhook 为主、`query-apply` 兜底）。

### 错误码

| 错误码               | 说明                                  |
| ----------------- | ----------------------------------- |
| `APPLY_NOT_FOUND` | 开户申请不存在（或不属本合作伙伴）                   |
| `STATUS_CONFLICT` | 申请当前非 `REJECTED`，不可重新提交（在途/已成功无需重提） |

## 关联 Webhook

开户结果由 DCS 主动推送，两个事件对应两种终局：

| 事件 `type`               | 触发时机        | 载荷要点                                       |
| ----------------------- | ----------- | ------------------------------------------ |
| `ORGANIZATION_CREATED`  | KYB 通过、开户成功 | 携 `organizationId`，公司状态 `ACTIVE`，可直接进入后续流程 |
| `ORGANIZATION_REJECTED` | KYB 拒绝      | 携 `rejectMessage`(拒绝原因)，据此修正资料后重提          |

事件统一信封示例（`data` 内为各事件的业务载荷）：

```json theme={null}
{
  "webhookId": "7800000000000000900",
  "webhookType": "ORGANIZATION_CREATED",
  "notificationTime": 1717211400000,
  "data": { }
}
```

信封结构、验签、重试与幂等规则见[快速开始](../getting-started/quickstart)。

## 下一步

* 开户成功、拿到 `organizationId` 后，维护公司状态与余额预警：[公司状态与预警](./company-maintenance)
* 公司 `ACTIVE` 后为其创建持卡人：[管理员工](./managing-employees)