版本 2.4.8 · 最新
货币设置 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。
GET
/api/v2/settings/currencies货币设置
鉴权: 仅管理员
POST
/api/v2/settings/currencies添加货币
鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
code必填 | string | 币种代码(ISO 4217,3 位大写字母)。 |
enabled | boolean | 是否启用 |
minor_digits | integer | 展示小数位:2 = 两位小数,0 = 不显示小数(JPY/KRW 等);0 位时换算价取整到整元、x99 按档取到 xx99/x9 元。金额字段仍按 1/100 主单位记,不受影响。新建不给 = 按 ISO 4217(零小数位币种 0,其余 2)。 |
name必填 | string | 名称 |
rate | string | 1 单位该币 = ? 基准货币,大于 0,最多 8 位小数。 |
rate_mode | string | 汇率模式:auto 定时从汇率源取(须先取到过),manual 手填。 |
rounding | string | 价格取整:none 不取整;x99 按档取整,先试 .99、再试 .x9,取第一个比照算价溢价 ≤10% 的,都超则照算不取整。 |
symbol必填 | string | 显示符号,如 ¥、US$、HK$。 |
PUT
/api/v2/settings/currencies改货币设置
鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
base_currency | string | 基准货币:统计报表按它折算;出现第一笔订单后锁定。 |
default_currency | string | 新用户默认的账户货币。 |
fx_source | string | 汇率源。 |
PUT
/api/v2/settings/currencies/{code}改货币
鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
enabled | boolean | 是否启用 |
minor_digits | integer | 展示小数位:2 = 两位小数,0 = 不显示小数(JPY/KRW 等);0 位时换算价取整到整元、x99 按档取到 xx99/x9 元。金额字段仍按 1/100 主单位记,不受影响。新建不给 = 按 ISO 4217(零小数位币种 0,其余 2)。 |
name | string | 名称 |
rate | string | 1 单位该币 = ? 基准货币,大于 0,最多 8 位小数。 |
rate_mode | string | 汇率模式:auto 定时从汇率源取(须先取到过),manual 手填。 |
rounding | string | 价格取整:none 不取整;x99 按档取整,先试 .99、再试 .x9,取第一个比照算价溢价 ≤10% 的,都超则照算不取整。 |
symbol | string | 显示符号,如 ¥、US$、HK$。 |
POST
/api/v2/settings/currency-legacy确认升级前的记账货币
鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
currency必填 | string | 升级前的记账货币(ISO 4217),确认后作为基准货币并给老账户、老订单改标识(不换算金额)。 |
货币设置对象
| 字段 | 类型 | 说明 |
|---|---|---|
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)。 |
name必填 | string | 名称 |
rate | string | 1 单位该币 = ? 基准货币,大于 0,最多 8 位小数。 |
rate_mode | string | 汇率模式:auto 定时从汇率源取(须先取到过),manual 手填。 |
rate_updated_at | string | 汇率最近一次变更时间。 |
rates | object | 汇率源全部币种 → 1 单位该币 = ? 基准货币(十进制串);含货币表外的币,基准币为 1。 |
rejected | string[] | 本次因新汇率相对旧值偏离超过 max_deviation_pct 而没采用的币种(汇率模式 auto 的行,旧汇率与更新时间都保持不动);没有则空数组。 |
rounding | string | 价格取整:none 不取整;x99 按档取整,先试 .99、再试 .x9,取第一个比照算价溢价 ≤10% 的,都超则照算不取整。 |
saved | string[] | 本次写回汇率的币种(汇率模式 auto 的行)。 |
source | string | 本次取数的汇率源。 |
state | string | unset 未判定、pending 待确认、confirmed 已确认、auto_cny 自动定人民币、none 新装无需确认。 |
symbol必填 | string | 显示符号,如 ¥、US$、HK$。 |
unopened_users | integer | 尚未开户(无账户行)的租户数:它们按新用户默认币计价,已计入默认币的 user_count;改默认货币时这些租户会随之换币。 |
user_count | integer | 账户币种为它的用户数。 |
返回与错误
成功直接回资源 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"
}