> ## 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.

# 公司状态与预警

> 查询已开户公司详情、按能力域冻结与解冻公司（幂等集合语义）、按币种设置资金池余额不足预警（整份替换语义），含字段表、示例与错误码。

## 📄 正文

无论是日常运营核对、风控处置还是资金管理，您都可以通过本页的三个接口维护一家已开户的公司：查询详情（`query`）、冻结与解冻（`update-state`）、余额不足预警（`balance-alert-set`）。三个接口都以开户成功后返回的 `organizationId` 定位公司；开户与审核流程见[公司开户与审核](./company-onboarding)。

## 查询公司详情

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

查询已开户公司的基础资料、资金池币种与当前状态。

### 请求参数

| 字段               | 类型     |  必填 | 说明        |
| ---------------- | ------ | :-: | --------- |
| `organizationId` | string |  是  | ≤20；公司 ID |

```http theme={null}
GET /open-api-corp/organization/v1/query?organizationId=e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f
```

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

| 字段                          | 类型        | 说明                                                                                   |
| --------------------------- | --------- | ------------------------------------------------------------------------------------ |
| `organizationId`            | string    | 公司 ID                                                                                |
| `organizationRef`           | string    | 合作伙伴侧标识                                                                              |
| `organizationName`          | string    | 公司法定名称                                                                               |
| `companyRegistrationNumber` | string    | 注册号                                                                                  |
| `fundingCurrencies`         | string\[] | 资金池币种列表                                                                              |
| `status`                    | string    | 公司状态（合并视图）：生命周期 `ACTIVE` / `TERMINATED`，叠加行为状态 `SUSPENDED` / `FROZEN` / `RESTRICTED` |

<Note>
  公司状态呈现为一个合并状态字段：生命周期与行为状态叠加，判断能否开卡、消费以是否 `ACTIVE` 为准。状态机语义详见[状态机与冻结体系](../basic-concepts/states-and-freezing)。
</Note>

### 响应示例

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
    "organizationRef": "ext-company-001",
    "organizationName": "EXAMPLE COMPANY LIMITED",
    "companyRegistrationNumber": "CR1234567",
    "fundingCurrencies": ["USD", "HKD"],
    "status": "ACTIVE"
  }
}
```

### 错误码

| 错误码                    | 说明              |
| ---------------------- | --------------- |
| `ORGANIZATION_INVALID` | 公司不存在（或不属本合作伙伴） |

## 冻结与解冻

**`POST /open-api-corp/organization/v1/update-restrictions`**

按能力域冻结或解冻公司，采用幂等集合语义：公司的行为状态是一个状态集合，`addRestrictions` 把能力域码加入集合即冻结、`removeRestrictions` 从集合移除即解冻，同一操作重复提交结果一致。

### 五个能力域码

冻结按能力域生效，一次可传多个：

| 能力域码              | 冻结后停用的范围                     |
| ----------------- | ---------------------------- |
| `ACCOUNT_FROZEN`  | 账户整体（登录、改密、改手机/邮箱、绑定 MFA、销户） |
| `CASH_IN_FROZEN`  | 入金/充值                        |
| `CASH_OUT_FROZEN` | 出金/提现/汇款                     |
| `PAYMENT_FROZEN`  | 支付/消费（含卡支付）                  |
| `CARD_FROZEN`     | 卡管理动作（申卡、激活、改 PIN）           |

<Warning>
  `addRestrictions` / `removeRestrictions` 的取值仅限上表 5 个开放的 L1 能力域码，传其余值（含 `KYC_FROZEN` / `TRANSFER_FROZEN`、L2 细粒度码、`SUSPENDED` / `RESTRICTED`）返回 `DAPI_PARAM_INVALID`。由风控、监管或司法写入的受限态不可经此接口解除。
</Warning>

### 请求参数

| 字段                   | 类型        |  必填 | 说明                              |
| -------------------- | --------- | :-: | ------------------------------- |
| `organizationId`     | string    |  是  | ≤20；目标公司                        |
| `addRestrictions`    | string\[] |  否  | 冻结状态码，取值仅限 5 个 L1 能力域码，可多传      |
| `removeRestrictions` | string\[] |  否  | 解冻状态码，取值同 `addRestrictions`，可多传 |
| `remark`             | string    |  否  | ≤256；操作备注                       |

### 请求示例：冻结（加行为状态）

```json theme={null}
{
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "addRestrictions": ["PAYMENT_FROZEN", "CARD_FROZEN"],
  "remark": "suspicious transactions under review"
}
```

### 请求示例：解冻（删行为状态）

```json theme={null}
{
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "removeRestrictions": ["PAYMENT_FROZEN", "CARD_FROZEN"],
  "remark": "review cleared"
}
```

### 响应示例

动作类接口，成功时 `data` 为空：

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": null
}
```

状态变更后 DCS 会推送公司状态变更通知（事件名以 API 参考的 Webhook 事件表为准），载荷携带本次的 `addRestrictions` / `removeRestrictions`。

### 错误码

| 错误码                    | 说明                        |
| ---------------------- | ------------------------- |
| `ORGANIZATION_INVALID` | 公司不存在（或不属本合作伙伴）           |
| `STATUS_CONFLICT`      | 当前状态不允许该操作（如公司非 `ACTIVE`） |

## 余额不足预警

**`POST /open-api-corp/fund/v1/balance-alert-set`**

设置公司资金池按币种的余额不足预警。

<Warning>
  **整份替换语义**：每次提交都会重设全部预警配置，请每次传入完整的配置列表，而不是只传增量。
</Warning>

### 请求参数

| 字段                            | 类型         |  必填 | 说明                                                            |
| ----------------------------- | ---------- | :-: | ------------------------------------------------------------- |
| `organizationId`              | string     |  是  | ≤20；公司 ID                                                     |
| `balanceSettings`             | array      |  是  | 按币种阈值，≥1 项；同一币种不可重复（重复返回 `DAPI_PARAM_INVALID`）；币种须属于公司已开资金池币种 |
| `balanceSettings[].currency`  | string     |  是  | `USD` / `HKD`                                                 |
| `balanceSettings[].threshold` | BigDecimal |  是  | 阈值（可用余额低于此触发；两位小数，非负）                                         |
| `emailSettings`               | string\[]  |  否  | ≤128/项；通知邮箱（公司级，可多个，每项为邮箱地址）；不传只发 Webhook                     |

### 请求示例

```json theme={null}
{
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "balanceSettings": [
    { "currency": "USD", "thresholdAmount": "1000.00" },
    { "currency": "HKD", "thresholdAmount": "8000.00" }
  ],
  "emailSettings": ["finance@example.com"]
}
```

### 响应示例

动作类接口，成功时 `data` 为空：

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": null
}
```

### 触发行为（`LOW_BALANCE`）

* 某币种资金池的可用余额低于阈值时，DCS 推送 Webhook `LOW_BALANCE`（公司资金池低余额预警）。
* 默认只发 Webhook；配置了 `emailSettings` 才额外发送邮件。
* 同一预警一天发送一次，直至余额回补。

### 错误码

| 错误码                              | 说明              |
| -------------------------------- | --------------- |
| `SUBJECT_INVALID`                | 公司（资金池主体）不存在/无效 |
| `BALANCE_ALERT_CURRENCY_NO_POOL` | 预警币种无对应资金池      |

## 下一步

* 收到低余额预警后为资金池充值并对账：[资金与对账](./funding-and-reconciliation)
* 回顾开户到维护的整体流程：[管理公司](./managing-companies)