大马小杨记账下载价格与服务在线手册 · 简体中文

API 接口参考

本文逐项说明现有记账接口。所有路径以 /api/v1 开头，下载完整OpenAPI 3.0规范可导入开发工具。先阅读认证与令牌，再按下列顺序对接。

共同约定

接口目录

查询账本列表

GET /api/v1/ledgers

仅返回当前用户可访问的数据。

路径、查询与请求头参数

参数位置必填类型、含义与限制
pagequery否integer；页码，默认1。流水列表超过末页时返回末页，其他列表超界返回空数组。
page_sizequery否integer；每页数量，默认20，限制为1–100。
sortquery否string；排序字段：id, created_at, name；加前缀-表示倒序。默认流水为日期倒序，其他为ID倒序。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers?page=1&page_size=20" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataarray是
data[].namestring否名称，去除首尾空白后1–50个字符。maxLength=50
data[].descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
data[].currencystring否受支持的货币代码，例如CNY、USD；不进行自动汇率转换。
data[].idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data[].versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data[].created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data[].updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data[].created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data[].updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data[].user_idstring否账本所有者登录用户ID。pattern="^[1-9][0-9]*$"
pageinteger是实际页码。
page_sizeinteger是实际每页数量。
totalinteger是符合条件的总条数；转账合并计一条。
{
  "data": [
    {
      "name": "团队日常",
      "description": "团队采购",
      "currency": "CNY",
      "id": "1",
      "version": 1,
      "created_by": "1",
      "updated_by": "1",
      "created_at": "2026-11-04T10:00:00Z",
      "updated_at": "2026-11-04T10:00:00Z",
      "user_id": "1"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

创建账本

POST /api/v1/ledgers

仅管理员可创建、修改、删除账本。商业版读写令牌或Demo读写令牌必需。

请求体字段

字段类型必填含义与约束
namestring是名称，去除首尾空白后1–50个字符。maxLength=50
descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
currencystring是受支持的货币代码，例如CNY、USD；不进行自动汇率转换。
template_idstring否可选场景模板。none表示不使用模板；与省略或空字符串一样，仅创建空白账本，不添加分类、账户或记账成员；模板只创建分类、账户及本人记账成员，不创建流水、预算、周期记账或登录用户。名称和货币仍使用请求值；未知值返回400。已有账本更新不接受非空template_id。enum=["", "none", "family", "personal", "office", "group", "shop", "project", "travel"]；default=""

请求示例

curl -X POST "$ILITEBOOK_URL/api/v1/ledgers" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "团队日常", "description": "团队采购", "currency": "CNY", "template_id": "office"}'

成功响应：HTTP 201

字段类型必填含义与约束
dataobject是
data.namestring否名称，去除首尾空白后1–50个字符。maxLength=50
data.descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
data.currencystring否受支持的货币代码，例如CNY、USD；不进行自动汇率转换。
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.user_idstring否账本所有者登录用户ID。pattern="^[1-9][0-9]*$"
{
  "data": {
    "name": "团队日常",
    "description": "团队采购",
    "currency": "CNY",
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "user_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited；413 attachment_too_large。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

查询账本详情

GET /api/v1/ledgers/{id}

路径、查询与请求头参数

参数位置必填类型、含义与限制
idpath是string；此资源的ID。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.namestring否名称，去除首尾空白后1–50个字符。maxLength=50
data.descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
data.currencystring否受支持的货币代码，例如CNY、USD；不进行自动汇率转换。
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.user_idstring否账本所有者登录用户ID。pattern="^[1-9][0-9]*$"
{
  "data": {
    "name": "团队日常",
    "description": "团队采购",
    "currency": "CNY",
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "user_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

修改账本

PATCH /api/v1/ledgers/{id}

仅管理员可创建、修改、删除账本。商业版读写令牌或Demo读写令牌必需。提交version和要修改的字段。省略或空字符串保留原值，因此不能用空字符串清空备注等字段。

路径、查询与请求头参数

参数位置必填类型、含义与限制
idpath是string；此资源的ID。

请求体字段

字段类型必填含义与约束
namestring否名称，去除首尾空白后1–50个字符。maxLength=50
descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
currencystring否受支持的货币代码，例如CNY、USD；不进行自动汇率转换。
versioninteger是当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1

请求示例

curl -X PATCH "$ILITEBOOK_URL/api/v1/ledgers/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "团队日常", "description": "团队采购", "currency": "CNY", "version": 1}'

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.namestring否名称，去除首尾空白后1–50个字符。maxLength=50
data.descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
data.currencystring否受支持的货币代码，例如CNY、USD；不进行自动汇率转换。
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.user_idstring否账本所有者登录用户ID。pattern="^[1-9][0-9]*$"
{
  "data": {
    "name": "团队日常",
    "description": "团队采购",
    "currency": "CNY",
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "user_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

删除账本

DELETE /api/v1/ledgers/{id}

仅管理员可创建、修改、删除账本。商业版读写令牌或Demo读写令牌必需。删除账本会连带删除所属资料和流水。删除分类或账户会停用关联周期任务并移除对应流水的关联；删除转账会同时删除两侧流水，附件按规则清理。

路径、查询与请求头参数

参数位置必填类型、含义与限制
idpath是string；此资源的ID。

请求体字段

字段类型必填含义与约束
versioninteger是当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1

请求示例

curl -X DELETE "$ILITEBOOK_URL/api/v1/ledgers/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": 1}'

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.deletedboolean是删除成功时为true。
{
  "data": {
    "deleted": true
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

查询账户列表

GET /api/v1/ledgers/{ledger_id}/accounts

仅返回当前用户可访问的数据。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
pagequery否integer；页码，默认1。流水列表超过末页时返回末页，其他列表超界返回空数组。
page_sizequery否integer；每页数量，默认20，限制为1–100。
sortquery否string；排序字段：id, created_at, name；加前缀-表示倒序。默认流水为日期倒序，其他为ID倒序。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers/1/accounts?page=1&page_size=20" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataarray是
data[].namestring否名称，去除首尾空白后1–50个字符。maxLength=50
data[].kindstring否收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
data[].colorstring否十六进制颜色，默认#3c8dbc。default="#3c8dbc"；pattern="^#[0-9a-fA-F]{6}$"
data[].iconstring否图标名称，可省略，最多50字节。maxLength=50
data[].idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data[].versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data[].created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data[].updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data[].created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data[].updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data[].ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
pageinteger是实际页码。
page_sizeinteger是实际每页数量。
totalinteger是符合条件的总条数；转账合并计一条。
{
  "data": [
    {
      "name": "团队日常",
      "kind": "expense",
      "color": "#3c8dbc",
      "icon": "bank",
      "id": "1",
      "version": 1,
      "created_by": "1",
      "updated_by": "1",
      "created_at": "2026-11-04T10:00:00Z",
      "updated_at": "2026-11-04T10:00:00Z",
      "ledger_id": "1"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

创建账户

POST /api/v1/ledgers/{ledger_id}/accounts

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。

请求体字段

字段类型必填含义与约束
namestring是名称，去除首尾空白后1–50个字符。maxLength=50
kindstring是收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
colorstring否十六进制颜色，默认#3c8dbc。default="#3c8dbc"；pattern="^#[0-9a-fA-F]{6}$"
iconstring否图标名称，可省略，最多50字节。maxLength=50

请求示例

curl -X POST "$ILITEBOOK_URL/api/v1/ledgers/1/accounts" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "团队日常", "kind": "expense", "color": "#3c8dbc", "icon": "bank"}'

成功响应：HTTP 201

字段类型必填含义与约束
dataobject是
data.namestring否名称，去除首尾空白后1–50个字符。maxLength=50
data.kindstring否收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
data.colorstring否十六进制颜色，默认#3c8dbc。default="#3c8dbc"；pattern="^#[0-9a-fA-F]{6}$"
data.iconstring否图标名称，可省略，最多50字节。maxLength=50
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
{
  "data": {
    "name": "团队日常",
    "kind": "expense",
    "color": "#3c8dbc",
    "icon": "bank",
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "ledger_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited；413 attachment_too_large。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

查询账户详情

GET /api/v1/ledgers/{ledger_id}/accounts/{id}

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers/1/accounts/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.namestring否名称，去除首尾空白后1–50个字符。maxLength=50
data.kindstring否收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
data.colorstring否十六进制颜色，默认#3c8dbc。default="#3c8dbc"；pattern="^#[0-9a-fA-F]{6}$"
data.iconstring否图标名称，可省略，最多50字节。maxLength=50
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
{
  "data": {
    "name": "团队日常",
    "kind": "expense",
    "color": "#3c8dbc",
    "icon": "bank",
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "ledger_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

修改账户

PATCH /api/v1/ledgers/{ledger_id}/accounts/{id}

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。提交version和要修改的字段。省略或空字符串保留原值，因此不能用空字符串清空备注等字段。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求体字段

字段类型必填含义与约束
namestring否名称，去除首尾空白后1–50个字符。maxLength=50
kindstring否收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
colorstring否十六进制颜色，默认#3c8dbc。default="#3c8dbc"；pattern="^#[0-9a-fA-F]{6}$"
iconstring否图标名称，可省略，最多50字节。maxLength=50
versioninteger是当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1

请求示例

curl -X PATCH "$ILITEBOOK_URL/api/v1/ledgers/1/accounts/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "团队日常", "kind": "expense", "color": "#3c8dbc", "icon": "bank", "version": 1}'

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.namestring否名称，去除首尾空白后1–50个字符。maxLength=50
data.kindstring否收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
data.colorstring否十六进制颜色，默认#3c8dbc。default="#3c8dbc"；pattern="^#[0-9a-fA-F]{6}$"
data.iconstring否图标名称，可省略，最多50字节。maxLength=50
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
{
  "data": {
    "name": "团队日常",
    "kind": "expense",
    "color": "#3c8dbc",
    "icon": "bank",
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "ledger_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

删除账户

DELETE /api/v1/ledgers/{ledger_id}/accounts/{id}

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。请求体必须携带version。关联附件和内部转账两侧流水由服务统一处理。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求体字段

字段类型必填含义与约束
versioninteger是当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1

请求示例

curl -X DELETE "$ILITEBOOK_URL/api/v1/ledgers/1/accounts/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": 1}'

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.deletedboolean是删除成功时为true。
{
  "data": {
    "deleted": true
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

查询分类列表

GET /api/v1/ledgers/{ledger_id}/categories

仅返回当前用户可访问的数据。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
pagequery否integer；页码，默认1。流水列表超过末页时返回末页，其他列表超界返回空数组。
page_sizequery否integer；每页数量，默认20，限制为1–100。
sortquery否string；排序字段：id, created_at, name；加前缀-表示倒序。默认流水为日期倒序，其他为ID倒序。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers/1/categories?page=1&page_size=20" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataarray是
data[].namestring否名称，去除首尾空白后1–50个字符。maxLength=50
data[].kindstring否收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
data[].colorstring否十六进制颜色，默认#3c8dbc。default="#3c8dbc"；pattern="^#[0-9a-fA-F]{6}$"
data[].iconstring否图标名称，可省略，最多50字节。maxLength=50
data[].idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data[].versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data[].created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data[].updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data[].created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data[].updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data[].ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
pageinteger是实际页码。
page_sizeinteger是实际每页数量。
totalinteger是符合条件的总条数；转账合并计一条。
{
  "data": [
    {
      "name": "团队日常",
      "kind": "expense",
      "color": "#3c8dbc",
      "icon": "shopping-cart",
      "id": "1",
      "version": 1,
      "created_by": "1",
      "updated_by": "1",
      "created_at": "2026-11-04T10:00:00Z",
      "updated_at": "2026-11-04T10:00:00Z",
      "ledger_id": "1"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

创建分类

POST /api/v1/ledgers/{ledger_id}/categories

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。

请求体字段

字段类型必填含义与约束
namestring是名称，去除首尾空白后1–50个字符。maxLength=50
kindstring是收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
colorstring否十六进制颜色，默认#3c8dbc。default="#3c8dbc"；pattern="^#[0-9a-fA-F]{6}$"
iconstring否图标名称，可省略，最多50字节。maxLength=50

请求示例

curl -X POST "$ILITEBOOK_URL/api/v1/ledgers/1/categories" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "团队日常", "kind": "expense", "color": "#3c8dbc", "icon": "shopping-cart"}'

成功响应：HTTP 201

字段类型必填含义与约束
dataobject是
data.namestring否名称，去除首尾空白后1–50个字符。maxLength=50
data.kindstring否收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
data.colorstring否十六进制颜色，默认#3c8dbc。default="#3c8dbc"；pattern="^#[0-9a-fA-F]{6}$"
data.iconstring否图标名称，可省略，最多50字节。maxLength=50
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
{
  "data": {
    "name": "团队日常",
    "kind": "expense",
    "color": "#3c8dbc",
    "icon": "shopping-cart",
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "ledger_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited；413 attachment_too_large。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

查询分类详情

GET /api/v1/ledgers/{ledger_id}/categories/{id}

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers/1/categories/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.namestring否名称，去除首尾空白后1–50个字符。maxLength=50
data.kindstring否收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
data.colorstring否十六进制颜色，默认#3c8dbc。default="#3c8dbc"；pattern="^#[0-9a-fA-F]{6}$"
data.iconstring否图标名称，可省略，最多50字节。maxLength=50
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
{
  "data": {
    "name": "团队日常",
    "kind": "expense",
    "color": "#3c8dbc",
    "icon": "shopping-cart",
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "ledger_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

修改分类

PATCH /api/v1/ledgers/{ledger_id}/categories/{id}

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。提交version和要修改的字段。省略或空字符串保留原值，因此不能用空字符串清空备注等字段。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求体字段

字段类型必填含义与约束
namestring否名称，去除首尾空白后1–50个字符。maxLength=50
kindstring否收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
colorstring否十六进制颜色，默认#3c8dbc。default="#3c8dbc"；pattern="^#[0-9a-fA-F]{6}$"
iconstring否图标名称，可省略，最多50字节。maxLength=50
versioninteger是当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1

请求示例

curl -X PATCH "$ILITEBOOK_URL/api/v1/ledgers/1/categories/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "团队日常", "kind": "expense", "color": "#3c8dbc", "icon": "shopping-cart", "version": 1}'

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.namestring否名称，去除首尾空白后1–50个字符。maxLength=50
data.kindstring否收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
data.colorstring否十六进制颜色，默认#3c8dbc。default="#3c8dbc"；pattern="^#[0-9a-fA-F]{6}$"
data.iconstring否图标名称，可省略，最多50字节。maxLength=50
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
{
  "data": {
    "name": "团队日常",
    "kind": "expense",
    "color": "#3c8dbc",
    "icon": "shopping-cart",
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "ledger_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

删除分类

DELETE /api/v1/ledgers/{ledger_id}/categories/{id}

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。请求体必须携带version。关联附件和内部转账两侧流水由服务统一处理。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求体字段

字段类型必填含义与约束
versioninteger是当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1

请求示例

curl -X DELETE "$ILITEBOOK_URL/api/v1/ledgers/1/categories/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": 1}'

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.deletedboolean是删除成功时为true。
{
  "data": {
    "deleted": true
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

查询记账成员列表

GET /api/v1/ledgers/{ledger_id}/members

仅返回当前用户可访问的数据。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
pagequery否integer；页码，默认1。流水列表超过末页时返回末页，其他列表超界返回空数组。
page_sizequery否integer；每页数量，默认20，限制为1–100。
sortquery否string；排序字段：id, created_at, name；加前缀-表示倒序。默认流水为日期倒序，其他为ID倒序。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers/1/members?page=1&page_size=20" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataarray是
data[].namestring否名称，去除首尾空白后1–50个字符。maxLength=50
data[].relationstring否关系标记，默认other，最多32字节；仅为记账信息，不分配登录权限。default="other"；maxLength=32
data[].colorstring否十六进制颜色，默认#3c8dbc。default="#3c8dbc"；pattern="^#[0-9a-fA-F]{6}$"
data[].idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data[].versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data[].created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data[].updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data[].created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data[].updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data[].ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
pageinteger是实际页码。
page_sizeinteger是实际每页数量。
totalinteger是符合条件的总条数；转账合并计一条。
{
  "data": [
    {
      "name": "团队日常",
      "relation": "other",
      "color": "#3c8dbc",
      "id": "1",
      "version": 1,
      "created_by": "1",
      "updated_by": "1",
      "created_at": "2026-11-04T10:00:00Z",
      "updated_at": "2026-11-04T10:00:00Z",
      "ledger_id": "1"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

创建记账成员

POST /api/v1/ledgers/{ledger_id}/members

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。

请求体字段

字段类型必填含义与约束
namestring是名称，去除首尾空白后1–50个字符。maxLength=50
relationstring否关系标记，默认other，最多32字节；仅为记账信息，不分配登录权限。default="other"；maxLength=32
colorstring否十六进制颜色，默认#3c8dbc。default="#3c8dbc"；pattern="^#[0-9a-fA-F]{6}$"

请求示例

curl -X POST "$ILITEBOOK_URL/api/v1/ledgers/1/members" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "团队日常", "relation": "other", "color": "#3c8dbc"}'

成功响应：HTTP 201

字段类型必填含义与约束
dataobject是
data.namestring否名称，去除首尾空白后1–50个字符。maxLength=50
data.relationstring否关系标记，默认other，最多32字节；仅为记账信息，不分配登录权限。default="other"；maxLength=32
data.colorstring否十六进制颜色，默认#3c8dbc。default="#3c8dbc"；pattern="^#[0-9a-fA-F]{6}$"
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
{
  "data": {
    "name": "团队日常",
    "relation": "other",
    "color": "#3c8dbc",
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "ledger_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited；413 attachment_too_large。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

查询记账成员详情

GET /api/v1/ledgers/{ledger_id}/members/{id}

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers/1/members/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.namestring否名称，去除首尾空白后1–50个字符。maxLength=50
data.relationstring否关系标记，默认other，最多32字节；仅为记账信息，不分配登录权限。default="other"；maxLength=32
data.colorstring否十六进制颜色，默认#3c8dbc。default="#3c8dbc"；pattern="^#[0-9a-fA-F]{6}$"
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
{
  "data": {
    "name": "团队日常",
    "relation": "other",
    "color": "#3c8dbc",
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "ledger_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

修改记账成员

PATCH /api/v1/ledgers/{ledger_id}/members/{id}

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。提交version和要修改的字段。省略或空字符串保留原值，因此不能用空字符串清空备注等字段。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求体字段

字段类型必填含义与约束
namestring否名称，去除首尾空白后1–50个字符。maxLength=50
relationstring否关系标记，默认other，最多32字节；仅为记账信息，不分配登录权限。default="other"；maxLength=32
colorstring否十六进制颜色，默认#3c8dbc。default="#3c8dbc"；pattern="^#[0-9a-fA-F]{6}$"
versioninteger是当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1

请求示例

curl -X PATCH "$ILITEBOOK_URL/api/v1/ledgers/1/members/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "团队日常", "relation": "other", "color": "#3c8dbc", "version": 1}'

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.namestring否名称，去除首尾空白后1–50个字符。maxLength=50
data.relationstring否关系标记，默认other，最多32字节；仅为记账信息，不分配登录权限。default="other"；maxLength=32
data.colorstring否十六进制颜色，默认#3c8dbc。default="#3c8dbc"；pattern="^#[0-9a-fA-F]{6}$"
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
{
  "data": {
    "name": "团队日常",
    "relation": "other",
    "color": "#3c8dbc",
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "ledger_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

删除记账成员

DELETE /api/v1/ledgers/{ledger_id}/members/{id}

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。请求体必须携带version。关联附件和内部转账两侧流水由服务统一处理。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求体字段

字段类型必填含义与约束
versioninteger是当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1

请求示例

curl -X DELETE "$ILITEBOOK_URL/api/v1/ledgers/1/members/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": 1}'

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.deletedboolean是删除成功时为true。
{
  "data": {
    "deleted": true
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

查询流水列表

GET /api/v1/ledgers/{ledger_id}/transactions

仅返回当前用户可访问的数据。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
pagequery否integer；页码，默认1。流水列表超过末页时返回末页，其他列表超界返回空数组。
page_sizequery否integer；每页数量，默认20，限制为1–100。
sortquery否string；排序字段：id, created_at, date, amount；加前缀-表示倒序。默认流水为日期倒序，其他为ID倒序。
kindquery否string；收支类型。all或省略表示全部；type为兼容别名，kind优先。
typequery否string；kind的别名；建议只使用kind。
date_fromquery否string；起始日期，包含当日。
date_toquery否string；结束日期，包含当日。
monthquery否string；月份，YYYY-MM，与日期条件同时使用时取交集。
category_idquery否string；正整数ID；始终按字符串处理，不能使用其他账本的ID。
account_idquery否string；流水列表按任一侧账户筛选仍合并显示转账；转账专用列表按转出侧筛选。
member_idquery否string；正整数ID；始终按字符串处理，不能使用其他账本的ID。
amount_minquery否string；最低金额，包含，允许0。
amount_maxquery否string；最高金额，包含，允许0。
searchquery否string；备注包含查询，忽略大小写；SQL通配符%和_保留通配含义。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers/1/transactions?page=1&page_size=20&kind=expense&date_from=2026-11-04&date_to=2026-11-04&month=2026-11&category_id=1&account_id=1&member_id=1&amount_min=12.34&amount_max=12.34" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataarray是
data[].idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data[].versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data[].typestring否列表使用type而不是kind；转账被合并成一行。enum=["expense", "income", "transfer"]
data[].amountstring否十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
data[].datestring否有效日历日期，YYYY-MM-DD。
data[].descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
data[].is_transferboolean否是否为合并转账。
data[].category_idstring / null否列表关联ID。未关联时可能为空字符串或null；转账的分类ID为空。pattern="^(|[1-9][0-9]*)$"
data[].account_idstring / null否列表关联ID。未关联时可能为空字符串或null；转账的分类ID为空。pattern="^(|[1-9][0-9]*)$"
data[].member_idstring / null否列表关联ID。未关联时可能为空字符串或null；转账的分类ID为空。pattern="^(|[1-9][0-9]*)$"
data[].category_namestring否用于展示的关联名称、颜色或图标；未关联时为空或未分类标记。
data[].category_colorstring否用于展示的关联名称、颜色或图标；未关联时为空或未分类标记。
data[].category_iconstring否用于展示的关联名称、颜色或图标；未关联时为空或未分类标记。
data[].account_namestring否用于展示的关联名称、颜色或图标；未关联时为空或未分类标记。
data[].member_namestring否用于展示的关联名称、颜色或图标；未关联时为空或未分类标记。
data[].transfer_idstring否仅转账行出现。转账接口中的id为transfer_id；流水列表中的id为其中一侧流水ID。pattern="^[1-9][0-9]*$"
data[].from_account_idstring否仅转账行出现。转账接口中的id为transfer_id；流水列表中的id为其中一侧流水ID。pattern="^[1-9][0-9]*$"
data[].to_account_idstring否仅转账行出现。转账接口中的id为transfer_id；流水列表中的id为其中一侧流水ID。pattern="^[1-9][0-9]*$"
data[].from_account_namestring否转账两侧账户名称，仅转账行出现。
data[].to_account_namestring否转账两侧账户名称，仅转账行出现。
data[]._mergedboolean否内部展示辅助字段，客户端应忽略，使用无下划线的对应字段。
data[]._from_account_idstring否内部展示辅助字段，客户端应忽略，使用无下划线的对应字段。
data[]._to_account_idstring否内部展示辅助字段，客户端应忽略，使用无下划线的对应字段。
data[]._from_account_namestring否内部展示辅助字段，客户端应忽略，使用无下划线的对应字段。
data[]._to_account_namestring否内部展示辅助字段，客户端应忽略，使用无下划线的对应字段。
pageinteger是实际页码。
page_sizeinteger是实际每页数量。
totalinteger是符合条件的总条数；转账合并计一条。
{
  "data": [
    {
      "id": "1",
      "version": 1,
      "type": "expense",
      "amount": "12.34",
      "date": "2026-11-04",
      "description": "团队采购",
      "is_transfer": false,
      "category_id": "1",
      "account_id": "1",
      "member_id": "1",
      "category_name": "",
      "category_color": "",
      "category_icon": "",
      "account_name": "",
      "member_name": "",
      "from_account_id": "1",
      "to_account_id": "1",
      "from_account_name": "备用金",
      "to_account_name": "备用金"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

创建流水

POST /api/v1/ledgers/{ledger_id}/transactions

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
Idempotency-Keyheader否string；可选，最长128字节。相同令牌、路径、键及请求体重放返回原201结果；内容不同返回409。网络重试需复用相同请求体字节和键。

请求体字段

字段类型必填含义与约束
kindstring是收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
amountstring是十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
datestring是有效日历日期，YYYY-MM-DD。
descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
category_idstring是同账本、与kind相同收支类型的分类ID。pattern="^[1-9][0-9]*$"
account_idstring是同账本、与kind相同收支类型的账户ID。pattern="^[1-9][0-9]*$"
member_idstring否记账成员ID。账本有记账成员时必填；没有成员时可省略或传空字符串。不是登录用户ID。pattern="^[1-9][0-9]*$"
attachment_idsarray否已上传、属于当前用户和当前账本的临时附件ID。追加关联，不会删除未列出的旧附件。

请求示例

curl -X POST "$ILITEBOOK_URL/api/v1/ledgers/1/transactions" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Idempotency-Key: example-unique-001" \
  -H "Content-Type: application/json" \
  -d '{"kind": "expense", "amount": "12.34", "date": "2026-11-04", "description": "团队采购", "category_id": "1", "account_id": "1", "member_id": "1", "attachment_ids": ["1"]}'

成功响应：HTTP 201

字段类型必填含义与约束
dataobject是
data.kindstring否收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
data.amountstring否十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
data.datestring否有效日历日期，YYYY-MM-DD。
data.descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
data.category_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data.account_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data.member_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.transfer_idstring / null否转账ID；普通收支为null。转账明细是其中一侧流水，kind为income或expense。pattern="^[1-9][0-9]*$"
data.attachmentsarray否详情GET返回关联附件；写入响应不带此字段。
data.attachments[].idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.attachments[].namestring否文件名。
data.attachments[].sizeinteger否文件字节数，最大10485760。
data.attachments[].download_urlstring否同源API下载路径，下载时仍须Bearer认证。
{
  "data": {
    "kind": "expense",
    "amount": "12.34",
    "date": "2026-11-04",
    "description": "团队采购",
    "category_id": "1",
    "account_id": "1",
    "member_id": "1",
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "ledger_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited；413 attachment_too_large。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

查询流水详情

GET /api/v1/ledgers/{ledger_id}/transactions/{id}

流水详情和写入响应使用kind；流水列表使用type，字段结构不同。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers/1/transactions/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.kindstring否收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
data.amountstring否十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
data.datestring否有效日历日期，YYYY-MM-DD。
data.descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
data.category_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data.account_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data.member_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.transfer_idstring / null否转账ID；普通收支为null。转账明细是其中一侧流水，kind为income或expense。pattern="^[1-9][0-9]*$"
data.attachmentsarray否详情GET返回关联附件；写入响应不带此字段。
data.attachments[].idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.attachments[].namestring否文件名。
data.attachments[].sizeinteger否文件字节数，最大10485760。
data.attachments[].download_urlstring否同源API下载路径，下载时仍须Bearer认证。
{
  "data": {
    "kind": "expense",
    "amount": "12.34",
    "date": "2026-11-04",
    "description": "团队采购",
    "category_id": "1",
    "account_id": "1",
    "member_id": "1",
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "ledger_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

修改流水

PATCH /api/v1/ledgers/{ledger_id}/transactions/{id}

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。提交完整业务字段和version。省略的可选字段会恢复默认值；attachment_ids只追加关联。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求体字段

字段类型必填含义与约束
kindstring是收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
amountstring是十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
datestring是有效日历日期，YYYY-MM-DD。
descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
category_idstring是同账本、与kind相同收支类型的分类ID。pattern="^[1-9][0-9]*$"
account_idstring是同账本、与kind相同收支类型的账户ID。pattern="^[1-9][0-9]*$"
member_idstring否记账成员ID。账本有记账成员时必填；没有成员时可省略或传空字符串。不是登录用户ID。pattern="^[1-9][0-9]*$"
attachment_idsarray否已上传、属于当前用户和当前账本的临时附件ID。追加关联，不会删除未列出的旧附件。
versioninteger是当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1

请求示例

curl -X PATCH "$ILITEBOOK_URL/api/v1/ledgers/1/transactions/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind": "expense", "amount": "12.34", "date": "2026-11-04", "description": "团队采购", "category_id": "1", "account_id": "1", "member_id": "1", "attachment_ids": ["1"], "version": 1}'

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.kindstring否收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
data.amountstring否十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
data.datestring否有效日历日期，YYYY-MM-DD。
data.descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
data.category_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data.account_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data.member_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.transfer_idstring / null否转账ID；普通收支为null。转账明细是其中一侧流水，kind为income或expense。pattern="^[1-9][0-9]*$"
data.attachmentsarray否详情GET返回关联附件；写入响应不带此字段。
data.attachments[].idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.attachments[].namestring否文件名。
data.attachments[].sizeinteger否文件字节数，最大10485760。
data.attachments[].download_urlstring否同源API下载路径，下载时仍须Bearer认证。
{
  "data": {
    "kind": "expense",
    "amount": "12.34",
    "date": "2026-11-04",
    "description": "团队采购",
    "category_id": "1",
    "account_id": "1",
    "member_id": "1",
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "ledger_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

删除流水

DELETE /api/v1/ledgers/{ledger_id}/transactions/{id}

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。请求体必须携带version。关联附件和内部转账两侧流水由服务统一处理。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求体字段

字段类型必填含义与约束
versioninteger是当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1

请求示例

curl -X DELETE "$ILITEBOOK_URL/api/v1/ledgers/1/transactions/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": 1}'

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.deletedboolean是删除成功时为true。
{
  "data": {
    "deleted": true
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

查询转账列表

GET /api/v1/ledgers/{ledger_id}/transfers

仅返回当前用户可访问的数据。转账固定按日期、流水ID倒序，sort参数不生效。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
pagequery否integer；页码，默认1。流水列表超过末页时返回末页，其他列表超界返回空数组。
page_sizequery否integer；每页数量，默认20，限制为1–100。
kindquery否string；收支类型。all或省略表示全部；type为兼容别名，kind优先。
typequery否string；kind的别名；建议只使用kind。
date_fromquery否string；起始日期，包含当日。
date_toquery否string；结束日期，包含当日。
monthquery否string；月份，YYYY-MM，与日期条件同时使用时取交集。
category_idquery否string；正整数ID；始终按字符串处理，不能使用其他账本的ID。
account_idquery否string；流水列表按任一侧账户筛选仍合并显示转账；转账专用列表按转出侧筛选。
member_idquery否string；正整数ID；始终按字符串处理，不能使用其他账本的ID。
amount_minquery否string；最低金额，包含，允许0。
amount_maxquery否string；最高金额，包含，允许0。
searchquery否string；备注包含查询，忽略大小写；SQL通配符%和_保留通配含义。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers/1/transfers?page=1&page_size=20&kind=expense&date_from=2026-11-04&date_to=2026-11-04&month=2026-11&category_id=1&account_id=1&member_id=1&amount_min=12.34&amount_max=12.34" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataarray是
data[].idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data[].versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data[].typestring否列表使用type而不是kind；转账被合并成一行。enum=["transfer"]
data[].amountstring否十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
data[].datestring否有效日历日期，YYYY-MM-DD。
data[].descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
data[].is_transferboolean否是否为合并转账。
data[].category_idstring / null否列表关联ID。未关联时可能为空字符串或null；转账的分类ID为空。pattern="^(|[1-9][0-9]*)$"
data[].account_idstring / null否列表关联ID。未关联时可能为空字符串或null；转账的分类ID为空。pattern="^(|[1-9][0-9]*)$"
data[].member_idstring / null否列表关联ID。未关联时可能为空字符串或null；转账的分类ID为空。pattern="^(|[1-9][0-9]*)$"
data[].category_namestring否用于展示的关联名称、颜色或图标；未关联时为空或未分类标记。
data[].category_colorstring否用于展示的关联名称、颜色或图标；未关联时为空或未分类标记。
data[].category_iconstring否用于展示的关联名称、颜色或图标；未关联时为空或未分类标记。
data[].account_namestring否用于展示的关联名称、颜色或图标；未关联时为空或未分类标记。
data[].member_namestring否用于展示的关联名称、颜色或图标；未关联时为空或未分类标记。
data[].transfer_idstring否仅转账行出现。转账接口中的id为transfer_id；流水列表中的id为其中一侧流水ID。pattern="^[1-9][0-9]*$"
data[].from_account_idstring否仅转账行出现。转账接口中的id为transfer_id；流水列表中的id为其中一侧流水ID。pattern="^[1-9][0-9]*$"
data[].to_account_idstring否仅转账行出现。转账接口中的id为transfer_id；流水列表中的id为其中一侧流水ID。pattern="^[1-9][0-9]*$"
data[].from_account_namestring否转账两侧账户名称，仅转账行出现。
data[].to_account_namestring否转账两侧账户名称，仅转账行出现。
data[]._mergedboolean否内部展示辅助字段，客户端应忽略，使用无下划线的对应字段。
data[]._from_account_idstring否内部展示辅助字段，客户端应忽略，使用无下划线的对应字段。
data[]._to_account_idstring否内部展示辅助字段，客户端应忽略，使用无下划线的对应字段。
data[]._from_account_namestring否内部展示辅助字段，客户端应忽略，使用无下划线的对应字段。
data[]._to_account_namestring否内部展示辅助字段，客户端应忽略，使用无下划线的对应字段。
pageinteger是实际页码。
page_sizeinteger是实际每页数量。
totalinteger是符合条件的总条数；转账合并计一条。
{
  "data": [
    {
      "id": "1",
      "version": 1,
      "type": "transfer",
      "amount": "12.34",
      "date": "2026-11-04",
      "description": "团队采购",
      "is_transfer": true,
      "category_id": "1",
      "account_id": "1",
      "member_id": "1",
      "category_name": "",
      "category_color": "",
      "category_icon": "",
      "account_name": "",
      "member_name": "",
      "from_account_id": "1",
      "to_account_id": "1",
      "from_account_name": "备用金",
      "to_account_name": "备用金"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

创建转账

POST /api/v1/ledgers/{ledger_id}/transfers

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。转账只支持创建和删除；修改请删除后重新创建。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
Idempotency-Keyheader否string；可选，最长128字节。相同令牌、路径、键及请求体重放返回原201结果；内容不同返回409。网络重试需复用相同请求体字节和键。

请求体字段

字段类型必填含义与约束
amountstring是十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
datestring是有效日历日期，YYYY-MM-DD。
descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
from_account_idstring是转出账户ID；与转入账户不同，且同属当前账本。pattern="^[1-9][0-9]*$"
to_account_idstring是转入账户ID；账户收支类型不限制转账方向。pattern="^[1-9][0-9]*$"
member_idstring否记账成员ID。账本有记账成员时必填；没有成员时可省略或传空字符串。不是登录用户ID。pattern="^[1-9][0-9]*$"
attachment_idsarray否已上传、属于当前用户和当前账本的临时附件ID。追加关联，不会删除未列出的旧附件。

请求示例

curl -X POST "$ILITEBOOK_URL/api/v1/ledgers/1/transfers" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Idempotency-Key: example-unique-001" \
  -H "Content-Type: application/json" \
  -d '{"amount": "12.34", "date": "2026-11-04", "description": "团队采购", "from_account_id": "1", "to_account_id": "1", "member_id": "1", "attachment_ids": ["1"]}'

成功响应：HTTP 201

字段类型必填含义与约束
dataobject是
data.idstring是转账ID，不是流水ID；后续使用/transfers/{id}。pattern="^[1-9][0-9]*$"
data.versioninteger是当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
{
  "data": {
    "id": "1",
    "version": 1
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited；413 attachment_too_large。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

查询转账详情

GET /api/v1/ledgers/{ledger_id}/transfers/{id}

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers/1/transfers/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.typestring否列表使用type而不是kind；转账被合并成一行。enum=["transfer"]
data.amountstring否十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
data.datestring否有效日历日期，YYYY-MM-DD。
data.descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
data.is_transferboolean否是否为合并转账。
data.category_idstring / null否列表关联ID。未关联时可能为空字符串或null；转账的分类ID为空。pattern="^(|[1-9][0-9]*)$"
data.account_idstring / null否列表关联ID。未关联时可能为空字符串或null；转账的分类ID为空。pattern="^(|[1-9][0-9]*)$"
data.member_idstring / null否列表关联ID。未关联时可能为空字符串或null；转账的分类ID为空。pattern="^(|[1-9][0-9]*)$"
data.category_namestring否用于展示的关联名称、颜色或图标；未关联时为空或未分类标记。
data.category_colorstring否用于展示的关联名称、颜色或图标；未关联时为空或未分类标记。
data.category_iconstring否用于展示的关联名称、颜色或图标；未关联时为空或未分类标记。
data.account_namestring否用于展示的关联名称、颜色或图标；未关联时为空或未分类标记。
data.member_namestring否用于展示的关联名称、颜色或图标；未关联时为空或未分类标记。
data.transfer_idstring否仅转账行出现。转账接口中的id为transfer_id；流水列表中的id为其中一侧流水ID。pattern="^[1-9][0-9]*$"
data.from_account_idstring否仅转账行出现。转账接口中的id为transfer_id；流水列表中的id为其中一侧流水ID。pattern="^[1-9][0-9]*$"
data.to_account_idstring否仅转账行出现。转账接口中的id为transfer_id；流水列表中的id为其中一侧流水ID。pattern="^[1-9][0-9]*$"
data.from_account_namestring否转账两侧账户名称，仅转账行出现。
data.to_account_namestring否转账两侧账户名称，仅转账行出现。
data._mergedboolean否内部展示辅助字段，客户端应忽略，使用无下划线的对应字段。
data._from_account_idstring否内部展示辅助字段，客户端应忽略，使用无下划线的对应字段。
data._to_account_idstring否内部展示辅助字段，客户端应忽略，使用无下划线的对应字段。
data._from_account_namestring否内部展示辅助字段，客户端应忽略，使用无下划线的对应字段。
data._to_account_namestring否内部展示辅助字段，客户端应忽略，使用无下划线的对应字段。
{
  "data": {
    "id": "1",
    "version": 1,
    "type": "transfer",
    "amount": "12.34",
    "date": "2026-11-04",
    "description": "团队采购",
    "is_transfer": true,
    "category_id": "1",
    "account_id": "1",
    "member_id": "1",
    "category_name": "",
    "category_color": "",
    "category_icon": "",
    "account_name": "",
    "member_name": "",
    "from_account_id": "1",
    "to_account_id": "1",
    "from_account_name": "备用金",
    "to_account_name": "备用金"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

删除转账

DELETE /api/v1/ledgers/{ledger_id}/transfers/{id}

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。转账只支持创建和删除；修改请删除后重新创建。请求体必须携带version。关联附件和内部转账两侧流水由服务统一处理。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求体字段

字段类型必填含义与约束
versioninteger是当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1

请求示例

curl -X DELETE "$ILITEBOOK_URL/api/v1/ledgers/1/transfers/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": 1}'

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.deletedboolean是删除成功时为true。
{
  "data": {
    "deleted": true
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

查询预算列表

GET /api/v1/ledgers/{ledger_id}/budgets

仅返回当前用户可访问的数据。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
pagequery否integer；页码，默认1。流水列表超过末页时返回末页，其他列表超界返回空数组。
page_sizequery否integer；每页数量，默认20，限制为1–100。
sortquery否string；排序字段：id, created_at, amount, year, month；加前缀-表示倒序。默认流水为日期倒序，其他为ID倒序。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers/1/budgets?page=1&page_size=20" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataarray是
data[].category_idstring否当前账本的支出分类ID。同分类、年、月只有一项预算。pattern="^[1-9][0-9]*$"
data[].yearinteger否预算年份，1–9999。minimum=1；maximum=9999
data[].monthinteger否预算月份，1–12。minimum=1；maximum=12
data[].amountstring否十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
data[].idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data[].versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data[].created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data[].updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data[].created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data[].updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data[].ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
pageinteger是实际页码。
page_sizeinteger是实际每页数量。
totalinteger是符合条件的总条数；转账合并计一条。
{
  "data": [
    {
      "category_id": "1",
      "year": 2026,
      "month": 11,
      "amount": "12.34",
      "id": "1",
      "version": 1,
      "created_by": "1",
      "updated_by": "1",
      "created_at": "2026-11-04T10:00:00Z",
      "updated_at": "2026-11-04T10:00:00Z",
      "ledger_id": "1"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

创建预算

POST /api/v1/ledgers/{ledger_id}/budgets

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。分类、年、月共同唯一；更新时这三个字段必须与原预算一致。POST新预算不传version；若更新已存在预算须传当前version。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。

请求体字段

字段类型必填含义与约束
category_idstring是当前账本的支出分类ID。同分类、年、月只有一项预算。pattern="^[1-9][0-9]*$"
yearinteger是预算年份，1–9999。minimum=1；maximum=9999
monthinteger是预算月份，1–12。minimum=1；maximum=12
amountstring是十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。

请求示例

curl -X POST "$ILITEBOOK_URL/api/v1/ledgers/1/budgets" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"category_id": "1", "year": 2026, "month": 11, "amount": "12.34"}'

成功响应：HTTP 201

字段类型必填含义与约束
dataobject是
data.category_idstring否当前账本的支出分类ID。同分类、年、月只有一项预算。pattern="^[1-9][0-9]*$"
data.yearinteger否预算年份，1–9999。minimum=1；maximum=9999
data.monthinteger否预算月份，1–12。minimum=1；maximum=12
data.amountstring否十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
{
  "data": {
    "category_id": "1",
    "year": 2026,
    "month": 11,
    "amount": "12.34",
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "ledger_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited；413 attachment_too_large。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

查询预算详情

GET /api/v1/ledgers/{ledger_id}/budgets/{id}

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers/1/budgets/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.category_idstring否当前账本的支出分类ID。同分类、年、月只有一项预算。pattern="^[1-9][0-9]*$"
data.yearinteger否预算年份，1–9999。minimum=1；maximum=9999
data.monthinteger否预算月份，1–12。minimum=1；maximum=12
data.amountstring否十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
{
  "data": {
    "category_id": "1",
    "year": 2026,
    "month": 11,
    "amount": "12.34",
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "ledger_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

修改预算

PATCH /api/v1/ledgers/{ledger_id}/budgets/{id}

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。分类、年、月共同唯一；更新时这三个字段必须与原预算一致。POST新预算不传version；若更新已存在预算须传当前version。提交完整业务字段和version。省略的可选字段会恢复默认值；attachment_ids只追加关联。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求体字段

字段类型必填含义与约束
category_idstring是当前账本的支出分类ID。同分类、年、月只有一项预算。pattern="^[1-9][0-9]*$"
yearinteger是预算年份，1–9999。minimum=1；maximum=9999
monthinteger是预算月份，1–12。minimum=1；maximum=12
amountstring是十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
versioninteger是当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1

请求示例

curl -X PATCH "$ILITEBOOK_URL/api/v1/ledgers/1/budgets/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"category_id": "1", "year": 2026, "month": 11, "amount": "12.34", "version": 1}'

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.category_idstring否当前账本的支出分类ID。同分类、年、月只有一项预算。pattern="^[1-9][0-9]*$"
data.yearinteger否预算年份，1–9999。minimum=1；maximum=9999
data.monthinteger否预算月份，1–12。minimum=1；maximum=12
data.amountstring否十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
{
  "data": {
    "category_id": "1",
    "year": 2026,
    "month": 11,
    "amount": "12.34",
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "ledger_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

删除预算

DELETE /api/v1/ledgers/{ledger_id}/budgets/{id}

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。分类、年、月共同唯一；更新时这三个字段必须与原预算一致。POST新预算不传version；若更新已存在预算须传当前version。请求体必须携带version。关联附件和内部转账两侧流水由服务统一处理。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求体字段

字段类型必填含义与约束
versioninteger是当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1

请求示例

curl -X DELETE "$ILITEBOOK_URL/api/v1/ledgers/1/budgets/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": 1}'

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.deletedboolean是删除成功时为true。
{
  "data": {
    "deleted": true
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

查询周期记账列表

GET /api/v1/ledgers/{ledger_id}/recurring

仅返回当前用户可访问的数据。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
pagequery否integer；页码，默认1。流水列表超过末页时返回末页，其他列表超界返回空数组。
page_sizequery否integer；每页数量，默认20，限制为1–100。
sortquery否string；排序字段：id, created_at, amount, next_date；加前缀-表示倒序。默认流水为日期倒序，其他为ID倒序。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers/1/recurring?page=1&page_size=20" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataarray是
data[].kindstring否收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
data[].amountstring否十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
data[].descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
data[].category_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data[].account_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data[].member_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data[].frequencystring否重复单位：日、周、月、年。月/年遇到不存在的日期取当月最后一天。enum=["daily", "weekly", "monthly", "yearly"]
data[].intervalinteger否间隔单位数量，1–365；例如frequency=weekly、interval=2为每两周。minimum=1；maximum=365
data[].next_datestring否下次到期日。查询API不会触发生成流水。
data[].end_datestring否结束日期，YYYY-MM-DD；省略或空字符串表示不设结束日，非空时不得早于next_date。
data[].activeboolean否是否启用，创建时默认true。更新时省略同样按true处理。default=true
data[].idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data[].versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data[].created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data[].updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data[].created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data[].updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data[].ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
pageinteger是实际页码。
page_sizeinteger是实际每页数量。
totalinteger是符合条件的总条数；转账合并计一条。
{
  "data": [
    {
      "kind": "expense",
      "amount": "12.34",
      "description": "团队采购",
      "category_id": "1",
      "account_id": "1",
      "member_id": "1",
      "frequency": "monthly",
      "interval": 1,
      "next_date": "2026-11-04",
      "end_date": "",
      "active": true,
      "id": "1",
      "version": 1,
      "created_by": "1",
      "updated_by": "1",
      "created_at": "2026-11-04T10:00:00Z",
      "updated_at": "2026-11-04T10:00:00Z",
      "ledger_id": "1"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

创建周期记账

POST /api/v1/ledgers/{ledger_id}/recurring

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。仅支持收入和支出；不支持转账。GET不会生成到期流水，网页访问周期记账及程序维护任务负责生成。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。

请求体字段

字段类型必填含义与约束
kindstring是收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
amountstring是十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
category_idstring是同账本、与kind相同收支类型的分类ID。pattern="^[1-9][0-9]*$"
account_idstring是同账本、与kind相同收支类型的账户ID。pattern="^[1-9][0-9]*$"
member_idstring否记账成员ID。账本有记账成员时必填；没有成员时可省略或传空字符串。不是登录用户ID。pattern="^[1-9][0-9]*$"
frequencystring是重复单位：日、周、月、年。月/年遇到不存在的日期取当月最后一天。enum=["daily", "weekly", "monthly", "yearly"]
intervalinteger是间隔单位数量，1–365；例如frequency=weekly、interval=2为每两周。minimum=1；maximum=365
next_datestring是下次到期日。查询API不会触发生成流水。
end_datestring否结束日期，YYYY-MM-DD；省略或空字符串表示不设结束日，非空时不得早于next_date。
activeboolean否是否启用，创建时默认true。更新时省略同样按true处理。default=true

请求示例

curl -X POST "$ILITEBOOK_URL/api/v1/ledgers/1/recurring" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind": "expense", "amount": "12.34", "description": "团队采购", "category_id": "1", "account_id": "1", "member_id": "1", "frequency": "monthly", "interval": 1, "next_date": "2026-11-04", "end_date": "", "active": true}'

成功响应：HTTP 201

字段类型必填含义与约束
dataobject是
data.kindstring否收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
data.amountstring否十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
data.descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
data.category_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data.account_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data.member_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data.frequencystring否重复单位：日、周、月、年。月/年遇到不存在的日期取当月最后一天。enum=["daily", "weekly", "monthly", "yearly"]
data.intervalinteger否间隔单位数量，1–365；例如frequency=weekly、interval=2为每两周。minimum=1；maximum=365
data.next_datestring否下次到期日。查询API不会触发生成流水。
data.end_datestring否结束日期，YYYY-MM-DD；省略或空字符串表示不设结束日，非空时不得早于next_date。
data.activeboolean否是否启用，创建时默认true。更新时省略同样按true处理。default=true
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
{
  "data": {
    "kind": "expense",
    "amount": "12.34",
    "description": "团队采购",
    "category_id": "1",
    "account_id": "1",
    "member_id": "1",
    "frequency": "monthly",
    "interval": 1,
    "next_date": "2026-11-04",
    "end_date": "",
    "active": true,
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "ledger_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited；413 attachment_too_large。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

查询周期记账详情

GET /api/v1/ledgers/{ledger_id}/recurring/{id}

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers/1/recurring/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.kindstring否收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
data.amountstring否十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
data.descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
data.category_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data.account_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data.member_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data.frequencystring否重复单位：日、周、月、年。月/年遇到不存在的日期取当月最后一天。enum=["daily", "weekly", "monthly", "yearly"]
data.intervalinteger否间隔单位数量，1–365；例如frequency=weekly、interval=2为每两周。minimum=1；maximum=365
data.next_datestring否下次到期日。查询API不会触发生成流水。
data.end_datestring否结束日期，YYYY-MM-DD；省略或空字符串表示不设结束日，非空时不得早于next_date。
data.activeboolean否是否启用，创建时默认true。更新时省略同样按true处理。default=true
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
{
  "data": {
    "kind": "expense",
    "amount": "12.34",
    "description": "团队采购",
    "category_id": "1",
    "account_id": "1",
    "member_id": "1",
    "frequency": "monthly",
    "interval": 1,
    "next_date": "2026-11-04",
    "end_date": "",
    "active": true,
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "ledger_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

修改周期记账

PATCH /api/v1/ledgers/{ledger_id}/recurring/{id}

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。仅支持收入和支出；不支持转账。GET不会生成到期流水，网页访问周期记账及程序维护任务负责生成。提交完整业务字段和version。省略的可选字段会恢复默认值；attachment_ids只追加关联。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求体字段

字段类型必填含义与约束
kindstring是收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
amountstring是十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
category_idstring是同账本、与kind相同收支类型的分类ID。pattern="^[1-9][0-9]*$"
account_idstring是同账本、与kind相同收支类型的账户ID。pattern="^[1-9][0-9]*$"
member_idstring否记账成员ID。账本有记账成员时必填；没有成员时可省略或传空字符串。不是登录用户ID。pattern="^[1-9][0-9]*$"
frequencystring是重复单位：日、周、月、年。月/年遇到不存在的日期取当月最后一天。enum=["daily", "weekly", "monthly", "yearly"]
intervalinteger是间隔单位数量，1–365；例如frequency=weekly、interval=2为每两周。minimum=1；maximum=365
next_datestring是下次到期日。查询API不会触发生成流水。
end_datestring否结束日期，YYYY-MM-DD；省略或空字符串表示不设结束日，非空时不得早于next_date。
activeboolean否是否启用，创建时默认true。更新时省略同样按true处理。default=true
versioninteger是当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1

请求示例

curl -X PATCH "$ILITEBOOK_URL/api/v1/ledgers/1/recurring/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind": "expense", "amount": "12.34", "description": "团队采购", "category_id": "1", "account_id": "1", "member_id": "1", "frequency": "monthly", "interval": 1, "next_date": "2026-11-04", "end_date": "", "active": true, "version": 1}'

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.kindstring否收支类型；分类和账户创建后不可改变此值。enum=["expense", "income"]
data.amountstring否十进制金额，最多两位小数，不含货币符号、千分位或负号；写入须大于0，最大999999999.00。货币由账本决定。
data.descriptionstring否备注，最多500个字符，省略默认为空。default=""；maxLength=500
data.category_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data.account_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data.member_idstring / null否关联ID，未关联或关联资料已删除时为null。pattern="^[1-9][0-9]*$"
data.frequencystring否重复单位：日、周、月、年。月/年遇到不存在的日期取当月最后一天。enum=["daily", "weekly", "monthly", "yearly"]
data.intervalinteger否间隔单位数量，1–365；例如frequency=weekly、interval=2为每两周。minimum=1；maximum=365
data.next_datestring否下次到期日。查询API不会触发生成流水。
data.end_datestring否结束日期，YYYY-MM-DD；省略或空字符串表示不设结束日，非空时不得早于next_date。
data.activeboolean否是否启用，创建时默认true。更新时省略同样按true处理。default=true
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.versioninteger否当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1
data.created_bystring否创建人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.updated_bystring否最后修改人登录用户ID；系统初始化记录可能为字符串0。pattern="^[0-9]+$"
data.created_atstring / null否服务器创建时间；未设置时可能为空值或零时间。
data.updated_atstring / null否服务器修改时间；未设置时可能为零时间。
data.ledger_idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
{
  "data": {
    "kind": "expense",
    "amount": "12.34",
    "description": "团队采购",
    "category_id": "1",
    "account_id": "1",
    "member_id": "1",
    "frequency": "monthly",
    "interval": 1,
    "next_date": "2026-11-04",
    "end_date": "",
    "active": true,
    "id": "1",
    "version": 1,
    "created_by": "1",
    "updated_by": "1",
    "created_at": "2026-11-04T10:00:00Z",
    "updated_at": "2026-11-04T10:00:00Z",
    "ledger_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

删除周期记账

DELETE /api/v1/ledgers/{ledger_id}/recurring/{id}

需要读写令牌、可用的商业授权（Demo豁免）及当前账本editor以上权限。仅支持收入和支出；不支持转账。GET不会生成到期流水，网页访问周期记账及程序维护任务负责生成。请求体必须携带version。关联附件和内部转账两侧流水由服务统一处理。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求体字段

字段类型必填含义与约束
versioninteger是当前记录版本号。修改、删除必须使用最近一次查询返回的值，成功修改后递增。minimum=1

请求示例

curl -X DELETE "$ILITEBOOK_URL/api/v1/ledgers/1/recurring/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": 1}'

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.deletedboolean是删除成功时为true。
{
  "data": {
    "deleted": true
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

查询报表

GET /api/v1/ledgers/{ledger_id}/reports

不分页；不计转账。months为所选年份的月度汇总；days按所选月份的日序号汇总，month=0时为空数组；分类/账户/成员为所选月或全年汇总。其他流水筛选参数不作用于报表。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
yearquery否integer；年份，默认服务器时区当前年份。
monthquery否integer；月份，默认当前月份；0表示全年。与流水筛选month的YYYY-MM格式不同。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers/1/reports?year=2026&month=11" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.incomestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data.expensestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data.balancestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data.savings_ratestring否结余率百分数，不含百分号；收入为0时为0.0。
data.monthsarray否按此维度汇总，不计转账；时间范围由year和month指定。
data.months[].incomestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data.months[].expensestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data.months[].balancestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data.months[].namestring否月份/日序号或对应维度的展示名称。
data.daysarray否按此维度汇总，不计转账；时间范围由year和month指定。
data.days[].incomestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data.days[].expensestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data.days[].balancestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data.days[].namestring否月份/日序号或对应维度的展示名称。
data.categoriesarray否按此维度汇总，不计转账；时间范围由year和month指定。
data.categories[].incomestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data.categories[].expensestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data.categories[].balancestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data.categories[].namestring否月份/日序号或对应维度的展示名称。
data.accountsarray否按此维度汇总，不计转账；时间范围由year和month指定。
data.accounts[].incomestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data.accounts[].expensestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data.accounts[].balancestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data.accounts[].namestring否月份/日序号或对应维度的展示名称。
data.membersarray否按此维度汇总，不计转账；时间范围由year和month指定。
data.members[].incomestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data.members[].expensestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data.members[].balancestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data.members[].namestring否月份/日序号或对应维度的展示名称。
{
  "data": {
    "income": "0.00",
    "expense": "0.00",
    "balance": "0.00",
    "savings_rate": "25.0",
    "months": [
      {
        "income": "0.00",
        "expense": "0.00",
        "balance": "0.00",
        "name": "11"
      }
    ],
    "days": [
      {
        "income": "0.00",
        "expense": "0.00",
        "balance": "0.00",
        "name": "11"
      }
    ],
    "categories": [
      {
        "income": "0.00",
        "expense": "0.00",
        "balance": "0.00",
        "name": "11"
      }
    ],
    "accounts": [
      {
        "income": "0.00",
        "expense": "0.00",
        "balance": "0.00",
        "name": "11"
      }
    ],
    "members": [
      {
        "income": "0.00",
        "expense": "0.00",
        "balance": "0.00",
        "name": "11"
      }
    ]
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

查询日历汇总

GET /api/v1/ledgers/{ledger_id}/calendar

不分页；按日期升序，仅返回有非转账收支的日期。不存在的日期不会补零；不应用报表year/month参数。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
startquery否string；起始日，包含；省略表示不限制。
endquery否string；结束日，不包含；省略表示不限制。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers/1/calendar?start=2026-11-04&end=2026-11-04" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataarray是
data[].incomestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data[].expensestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data[].balancestring否按账本货币表示的金额，固定两位小数；balance为income减expense，可以为负。
data[].datestring否有效日历日期，YYYY-MM-DD。
{
  "data": [
    {
      "income": "0.00",
      "expense": "0.00",
      "balance": "0.00",
      "date": "2026-11-04"
    }
  ]
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

上传一个附件

POST /api/v1/ledgers/{ledger_id}/attachments

需商业版读写令牌或Demo读写令牌及账本编辑权限。每个请求只传一个file，可多次上传，附件数量不限。单文件1–10485760字节，整个multipart请求最多11MiB。上传后尚未关联流水，临时附件两小时后清理。支持照片、PDF、Office、OpenDocument、RTF、TXT、CSV；拒绝空文件、可执行文件、HTML、SVG及与扩展名不符的内容。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。

请求体字段

字段类型必填含义与约束
filestring是实际文件内容，不是服务器文件路径。

请求示例

curl -X POST "$ILITEBOOK_URL/api/v1/ledgers/1/attachments" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -F "file=@receipt.pdf"

成功响应：HTTP 201

字段类型必填含义与约束
dataobject是
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.namestring否文件名。
data.sizeinteger否文件字节数，最大10485760。
{
  "data": {
    "id": "1",
    "name": "receipt.pdf",
    "size": 1234
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited；413 attachment_too_large。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

查询附件元信息

GET /api/v1/attachments/{id}

临时附件仅上传者可见；已关联附件遵守账本可读权限。

路径、查询与请求头参数

参数位置必填类型、含义与限制
idpath是string；此资源的ID。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/attachments/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data.namestring否文件名。
data.sizeinteger否文件字节数，最大10485760。
data.transaction_idstring否已关联的流水ID；尚未关联时为空字符串。
{
  "data": {
    "id": "1",
    "name": "receipt.pdf",
    "size": 1234,
    "transaction_id": "1"
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

删除附件

DELETE /api/v1/attachments/{id}

需要读写令牌及对应权限。临时附件仅上传者可删；不要求version。转账共享附件，删除同时影响两侧。

路径、查询与请求头参数

参数位置必填类型、含义与限制
idpath是string；此资源的ID。

请求示例

curl -X DELETE "$ILITEBOOK_URL/api/v1/attachments/1" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.deletedboolean是删除成功时为true。
{
  "data": {
    "deleted": true
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

下载附件

GET /api/v1/attachments/{id}/download

返回文件原始字节，Content-Disposition为attachment，Content-Type为application/octet-stream；不是JSON。需Bearer认证，支持正式免费版。

路径、查询与请求头参数

参数位置必填类型、含义与限制
idpath是string；此资源的ID。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/attachments/1/download" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" -o receipt.pdf

成功响应：HTTP 200

文件内容，不含data包装。根据Content-Disposition保存文件；失败时仍返回JSON错误。

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

查询流水附件

GET /api/v1/ledgers/{ledger_id}/transactions/{id}/attachments

id为流水ID，不是转账ID。转账使用其任一侧流水ID，读取共享附件。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求示例

curl -X GET "$ILITEBOOK_URL/api/v1/ledgers/1/transactions/1/attachments" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN"

成功响应：HTTP 200

字段类型必填含义与约束
dataarray是
data[].idstring否正整数ID；始终按字符串处理，不能使用其他账本的ID。pattern="^[1-9][0-9]*$"
data[].namestring否文件名。
data[].sizeinteger否文件字节数，最大10485760。
data[].download_urlstring否同源API下载路径，下载时仍须Bearer认证。
{
  "data": [
    {
      "id": "1",
      "name": "receipt.pdf",
      "size": 1234,
      "download_url": "/api/v1/attachments/1/download"
    }
  ]
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request。具体原因及处理见下方错误表。

{"error": {"code": "unauthorized"}}

向已有流水追加附件

POST /api/v1/ledgers/{ledger_id}/transactions/{id}/attachments

需读写令牌及账本编辑权限。只追加，不移除旧附件，不要求version。转账使用任一侧流水ID共享关联；附件必须属于当前用户和账本。

路径、查询与请求头参数

参数位置必填类型、含义与限制
ledger_idpath是string；账本ID。
idpath是string；此资源的ID。

请求体字段

字段类型必填含义与约束
attachment_idsarray是已上传、属于当前用户和当前账本的临时附件ID。追加关联，不会删除未列出的旧附件。

请求示例

curl -X POST "$ILITEBOOK_URL/api/v1/ledgers/1/transactions/1/attachments" \
  -H "Authorization: Bearer $ILITEBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"attachment_ids": ["1"]}'

成功响应：HTTP 200

字段类型必填含义与约束
dataobject是
data.attachedboolean是关联成功时为true。
{
  "data": {
    "attached": true
  }
}

失败响应

401 unauthorized；403 forbidden；404 not_found；500 internal_error；400 invalid_request；409 version_conflict；429 rate_limited；413 attachment_too_large。具体原因及处理见下方错误表。

{"error": {"code": "invalid_request"}}

错误码与重试

HTTPerror.code处理方式
400invalid_request字段、关联关系、金额、日期、枚举或文件格式不合法。检查请求字段；未知JSON字段同样被拒绝。
401unauthorized缺少Bearer令牌、令牌无效/已撤销/已到期，或登录用户不可用。Demo重置和退出后也是此错误。
403forbidden角色或账本权限不足。commercial_required表示正式安装需要商业授权；token_read_only表示令牌仅可查询。
404not_found路径、资源不存在或不可见；系统管理接口不开放。
409version_conflictversion缺失/过期、预算键冲突，或同一幂等键提交不同请求内容。重新查询并确认后再提交。
413attachment_too_large附件最大10MiB（10485760字节）；request_too_large表示JSON请求超过1MiB。
429rate_limited达到操作配额，或Demo当前访客累计请求超过2000次。等待额度恢复或重置Demo，不要无限重试。
500internal_error服务器异常。记录时间、路径及已脱敏的请求内容联系维护人员。

另有 invalid_idempotency_key（400）、commercial_required（403）、token_read_only（403）、request_too_large（413）。写入超时不要直接创建新请求：仅创建流水和转账支持Idempotency-Key，必须复用同一令牌、路径、键和原始JSON字节。修改与删除冲突时先重新读取version，确认业务内容后提交；不应自动覆盖他人的更新。

放大的操作截图