公司状态与预警 - DCS Technical Documentation

📄 正文

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

查询公司详情

GET /open-api-corp/organization/v1/query 查询已开户公司的基础资料、资金池币种与当前状态。

请求参数

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

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`

公司状态呈现为一个合并状态字段：生命周期与行为状态叠加，判断能否开卡、消费以是否 ACTIVE 为准。状态机语义详见状态机与冻结体系。

响应示例

{
  "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）

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

请求参数

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

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

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

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

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

响应示例

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

{
  "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 设置公司资金池按币种的余额不足预警。

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

请求参数

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

请求示例

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

响应示例

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

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": null
}

触发行为（`LOW_BALANCE`）

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

错误码

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

下一步

收到低余额预警后为资金池充值并对账：资金与对账
回顾开户到维护的整体流程：管理公司

​📄 正文

​查询公司详情

​请求参数

​响应字段（data）

​响应示例

​错误码

​冻结与解冻

​五个能力域码

​请求参数

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

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

​响应示例

​错误码

​余额不足预警

​请求参数

​请求示例

​响应示例

​触发行为（LOW_BALANCE）

​错误码

​下一步

📄 正文

查询公司详情

请求参数

响应字段（`data`）

响应示例

错误码

冻结与解冻

五个能力域码

请求参数

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

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

响应示例

错误码

余额不足预警

请求参数

请求示例

响应示例

触发行为（`LOW_BALANCE`）

错误码

下一步