货币设置 settings

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

点击任一接口,右侧显示对应的调用示例。

支付与账户鉴权: 仅管理员9 个接口

鉴权

请求头带 X-API-Key(在「API 密钥」页开通,密钥只在开通时显示一次);也可用登录得到的 Authorization: Bearer 令牌。

X-API-Key

鉴权失败回 401;无权回 403(code 为 insufficient_scope 等)。

约定

分页参数 page(从 1 起)、page_size;排序 sort=字段 或 -字段。

时间一律 RFC 3339(UTC);金额单位为分。

写操作成功回 200/201/204;重复提交按资源唯一键回 409。

POST/api/v2/settings/currencies添加货币

鉴权: 仅管理员

请求体 application/json

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

鉴权: 仅管理员

请求体 application/json

字段类型说明
base_currencystring 基准货币:统计报表按它折算;出现第一笔订单后锁定。
default_currencystring 新用户默认的账户货币。
fx_sourcestring 汇率源。
POST/api/v2/settings/currencies/fx/refresh立即获取汇率

鉴权: 仅管理员

PUT/api/v2/settings/currencies/{code}改货币

鉴权: 仅管理员

请求体 application/json

字段类型说明
enabledboolean 是否启用
minor_digitsinteger 展示小数位:2 = 两位小数,0 = 不显示小数(JPY/KRW 等);0 位时换算价取整到整元、x99 按档取到 xx99/x9 元。金额字段仍按 1/100 主单位记,不受影响。新建不给 = 按 ISO 4217(零小数位币种 0,其余 2)。
可选值 [0,2]
namestring 名称
ratestring 1 单位该币 = ? 基准货币,大于 0,最多 8 位小数。
rate_modestring 汇率模式:auto 定时从汇率源取(须先取到过),manual 手填。
可选值 ["auto","manual"]
roundingstring 价格取整:none 不取整;x99 按档取整,先试 .99、再试 .x9,取第一个比照算价溢价 ≤10% 的,都超则照算不取整。
可选值 ["none","x99"]
symbolstring 显示符号,如 ¥、US$、HK$。
POST/api/v2/settings/currency-legacy确认升级前的记账货币

鉴权: 仅管理员

请求体 application/json

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

货币设置对象

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

返回与错误

成功直接回资源 JSON(HTTP 2xx);失败回 application/problem+json(code、detail,校验失败带 errors);列表为 items + total。

成功
{
  "id": 1,
  "name": "example"
}
列表
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
失败
{
  "code": "validation_failed",
  "detail": "请求参数不合法",
  "errors": [
    {
      "code": "required",
      "field": "/name",
      "message": "name 必填"
    }
  ],
  "request_id": "0123456789abcdef",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "about:blank"
}
开始使用

体验在线演示

访问在线演示,或联系我们获取报价与安装命令