## 货币设置 (`settings`)

管理员维护货币表(启用、汇率、取整)、基准货币与新用户默认;老版本升级后确认升级前的记账货币。

鉴权: 仅管理员 · 文档: https://www-sa2.kuxitong.com/zh/docs/api/settings

### GET `/api/v2/settings/currencies`

货币设置 · 鉴权: 仅管理员

```sh
curl "https://panel.example.com/api/v2/settings/currencies" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/settings/currencies`

添加货币 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `code` | string | 有 | 币种代码(ISO 4217,3 位大写字母)。 |
| `enabled` | boolean |  | 是否启用 |
| `minor_digits` | integer |  | 展示小数位:2 = 两位小数,0 = 不显示小数(JPY/KRW 等);0 位时换算价取整到整元、x99 按档取到 xx99/x9 元。金额字段仍按 1/100 主单位记,不受影响。新建不给 = 按 ISO 4217(零小数位币种 0,其余 2)。 可选值: [0,2] |
| `name` | string | 有 | 名称 |
| `rate` | string |  | 1 单位该币 = ? 基准货币,大于 0,最多 8 位小数。 |
| `rate_mode` | string |  | 汇率模式:auto 定时从汇率源取(须先取到过),manual 手填。 可选值: ["auto","manual"] |
| `rounding` | string |  | 价格取整:none 不取整;x99 按档取整,先试 .99、再试 .x9,取第一个比照算价溢价 ≤10% 的,都超则照算不取整。 可选值: ["none","x99"] |
| `symbol` | string | 有 | 显示符号,如 ¥、US$、HK$。 |

```sh
curl -X POST "https://panel.example.com/api/v2/settings/currencies" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"USD","name":"美元","rate":"7.10000000","rate_mode":"manual","rounding":"x99","symbol":"US$"}'
```

### PUT `/api/v2/settings/currencies`

改货币设置 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `base_currency` | string |  | 基准货币:统计报表按它折算;出现第一笔订单后锁定。 |
| `default_currency` | string |  | 新用户默认的账户货币。 |
| `fx_source` | string |  | 汇率源。 |

```sh
curl -X PUT "https://panel.example.com/api/v2/settings/currencies" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"default_currency":"USD"}'
```

### GET `/api/v2/settings/currencies/fx/preview`

预览汇率 · 鉴权: 仅管理员

```sh
curl "https://panel.example.com/api/v2/settings/currencies/fx/preview" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/settings/currencies/fx/refresh`

立即获取汇率 · 鉴权: 仅管理员

```sh
curl -X POST "https://panel.example.com/api/v2/settings/currencies/fx/refresh" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PUT `/api/v2/settings/currencies/{code}`

改货币 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `enabled` | boolean |  | 是否启用 |
| `minor_digits` | integer |  | 展示小数位:2 = 两位小数,0 = 不显示小数(JPY/KRW 等);0 位时换算价取整到整元、x99 按档取到 xx99/x9 元。金额字段仍按 1/100 主单位记,不受影响。新建不给 = 按 ISO 4217(零小数位币种 0,其余 2)。 可选值: [0,2] |
| `name` | string |  | 名称 |
| `rate` | string |  | 1 单位该币 = ? 基准货币,大于 0,最多 8 位小数。 |
| `rate_mode` | string |  | 汇率模式:auto 定时从汇率源取(须先取到过),manual 手填。 可选值: ["auto","manual"] |
| `rounding` | string |  | 价格取整:none 不取整;x99 按档取整,先试 .99、再试 .x9,取第一个比照算价溢价 ≤10% 的,都超则照算不取整。 可选值: ["none","x99"] |
| `symbol` | string |  | 显示符号,如 ¥、US$、HK$。 |

```sh
curl -X PUT "https://panel.example.com/api/v2/settings/currencies/{code}" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rate":"7.20000000","rate_mode":"manual"}'
```

### DELETE `/api/v2/settings/currencies/{code}`

删除货币 · 鉴权: 仅管理员

```sh
curl -X DELETE "https://panel.example.com/api/v2/settings/currencies/{code}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/settings/currency-legacy`

老版本货币确认状态 · 鉴权: 仅管理员

```sh
curl "https://panel.example.com/api/v2/settings/currency-legacy" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/settings/currency-legacy`

确认升级前的记账货币 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `currency` | string | 有 | 升级前的记账货币(ISO 4217),确认后作为基准货币并给老账户、老订单改标识(不换算金额)。 |

```sh
curl -X POST "https://panel.example.com/api/v2/settings/currency-legacy" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"currency":"USD"}'
```

货币设置对象:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `base_currency` | string |  | 基准货币:统计报表按它折算;出现第一笔订单后锁定。 |
| `base_locked` | boolean |  | 已有订单,基准货币不能再改。 |
| `can_reselect` | boolean |  | 现在还能(重新)选:pending,或已确认但未满 7 天且没有升级后的新订单。 |
| `code` | string | 有 | 币种代码(ISO 4217,3 位大写字母)。 |
| `currencies` | Currency[] |  | 货币表(基准在前)。 |
| `currency` | string | 有 | 升级前的记账货币(ISO 4217),确认后作为基准货币并给老账户、老订单改标识(不换算金额)。 |
| `deadline` | string |  | 可重选的截止时间(升级后 7 天)。 |
| `default_currency` | string |  | 新用户默认的账户货币。 |
| `enabled` | boolean |  | 是否启用 |
| `fetched_at` | string |  | 本次取到汇率的时间。 |
| `fx_fetched_at` | string |  | 最近一次从汇率源取到该币的时间;为空则不能设 auto。 |
| `fx_source` | string |  | 汇率源。 |
| `fx_sources` | string[] |  | 可选的汇率源。 |
| `max_deviation_pct` | integer |  | 自动汇率单次刷新相对旧值最多允许偏离的百分比(超过不采用,即 rejected 的判定线)。 |
| `minor_digits` | integer |  | 展示小数位:2 = 两位小数,0 = 不显示小数(JPY/KRW 等);0 位时换算价取整到整元、x99 按档取到 xx99/x9 元。金额字段仍按 1/100 主单位记,不受影响。新建不给 = 按 ISO 4217(零小数位币种 0,其余 2)。 可选值: [0,2] |
| `name` | string | 有 | 名称 |
| `rate` | string |  | 1 单位该币 = ? 基准货币,大于 0,最多 8 位小数。 |
| `rate_mode` | string |  | 汇率模式:auto 定时从汇率源取(须先取到过),manual 手填。 可选值: ["auto","manual"] |
| `rate_updated_at` | string |  | 汇率最近一次变更时间。 |
| `rates` | object |  | 汇率源全部币种 → 1 单位该币 = ? 基准货币(十进制串);含货币表外的币,基准币为 1。 |
| `rejected` | string[] |  | 本次因新汇率相对旧值偏离超过 max_deviation_pct 而没采用的币种(汇率模式 auto 的行,旧汇率与更新时间都保持不动);没有则空数组。 |
| `rounding` | string |  | 价格取整:none 不取整;x99 按档取整,先试 .99、再试 .x9,取第一个比照算价溢价 ≤10% 的,都超则照算不取整。 可选值: ["none","x99"] |
| `saved` | string[] |  | 本次写回汇率的币种(汇率模式 auto 的行)。 |
| `source` | string |  | 本次取数的汇率源。 |
| `state` | string |  | unset 未判定、pending 待确认、confirmed 已确认、auto_cny 自动定人民币、none 新装无需确认。 可选值: ["unset","pending","confirmed","auto_cny","none"] |
| `symbol` | string | 有 | 显示符号,如 ¥、US$、HK$。 |
| `unopened_users` | integer |  | 尚未开户(无账户行)的租户数:它们按新用户默认币计价,已计入默认币的 user_count;改默认货币时这些租户会随之换币。 |
| `user_count` | integer |  | 账户币种为它的用户数。 |
