收支
登记收入与支出，保留凭证，并按既有规则处理作废与冲销。
收支规则
amount 必须为正数十进制字符串，最多两位小数；recordType 为 INCOME 或 EXPENSE，fundAccount 为 PERSONAL 或 CORPORATE。日期使用 YYYY-MM-DD。
PERSONAL 会沿用现有个人垫付与积分账务逻辑；CORPORATE 只登记对公收支。接口不会执行银行付款或转账。
非管理员只能读取本人的收支。空间关闭收支提交时不能新建或上传凭证；已作废、冲销或历史划转记录的修改限制与网页一致。
创建后如需关联标签，使用返回的记录 ID 调用 tags 操作。金额和发生类型不可通过编辑日期说明接口修改。
接口参考
查询收支列表
/api/v1/workspaces/{workspaceId}/finance
响应 data 字段（列表元素）
- id
- 收支 ID
- reimbursementNo
- 记录编号
- reimbursementDate
- 发生日期 ISO 8601
- requesterId
- 记录归属人
- createdById
- 创建者
- description
- 说明
- amount
- 十进制金额字符串
- recordType
- INCOME / EXPENSE
- fundAccount
- 资金账户
- status
- 既有账务状态
- reversedAt
- 原记录冲销时间，可为空
- reversedFromId
- 冲销来源 ID，可为空
- supplierId
- 供应商 ID，可为空
- attachmentKey
- 附件引用，可为空
- attachmentName
- 附件名称，可为空
- attachmentSize
- 附件字节数，可为空
- attachmentMimeType
- 附件 MIME，可为空
- downloadUrl
- 有关联附件时返回的鉴权下载入口
- createdAt
- 创建时间 ISO 8601
- updatedAt
- 更新时间 ISO 8601
- tags
- 标签关联数组，元素为 { tag: { id, name, archivedAt } }
curl --request GET "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/finance" \
--header "Authorization: Bearer $AGENT_API_KEY"成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
查询收支详情
/api/v1/workspaces/{workspaceId}/finance/{id}
响应 data 字段
- id
- 收支 ID
- reimbursementNo
- 记录编号
- reimbursementDate
- 发生日期 ISO 8601
- requesterId
- 记录归属人
- createdById
- 创建者
- description
- 说明
- amount
- 十进制金额字符串
- recordType
- INCOME / EXPENSE
- fundAccount
- 资金账户
- status
- 既有账务状态
- reversedAt
- 原记录冲销时间，可为空
- reversedFromId
- 冲销来源 ID，可为空
- supplierId
- 供应商 ID，可为空
- attachmentKey
- 附件引用，可为空
- attachmentName
- 附件名称，可为空
- attachmentSize
- 附件字节数，可为空
- attachmentMimeType
- 附件 MIME，可为空
- downloadUrl
- 有关联附件时返回的鉴权下载入口
- createdAt
- 创建时间 ISO 8601
- updatedAt
- 更新时间 ISO 8601
- tags
- 标签关联数组，元素为 { tag: { id, name, archivedAt } }
curl --request GET "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/finance/{id}" \
--header "Authorization: Bearer $AGENT_API_KEY"成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
提交收支记录
/api/v1/workspaces/{workspaceId}/finance
| 参数 | 类型 | 说明 |
|---|---|---|
| recordType | string | INCOME / EXPENSE |
| reimbursementDate* | string | YYYY-MM-DD |
| fundAccount* | string | PERSONAL / CORPORATE |
| description* | string | 沿用业务表单规则 |
| amount* | string | 正数十进制字符串，最多两位小数 |
| supplierId | string | 沿用业务表单规则 |
| attachmentKey | string | 沿用业务表单规则 |
| attachmentName | string | 沿用业务表单规则 |
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request POST "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/finance" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{"reimbursementDate":"2026-11-03","fundAccount":"PERSONAL","description":"客户服务费用","amount":"100.00"}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
修改日期及说明
/api/v1/workspaces/{workspaceId}/finance/{id}
| 参数 | 类型 | 说明 |
|---|---|---|
| reimbursementDate* | string | 沿用业务表单规则 |
| description* | string | 沿用业务表单规则 |
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request PATCH "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/finance/{id}" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{"reimbursementDate":"2026-11-03","description":"客户服务费用"}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
作废并按既有规则冲销记录
/api/v1/workspaces/{workspaceId}/finance/{id}/cancel
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request POST "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/finance/{id}/cancel" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
上传附件
/api/v1/workspaces/{workspaceId}/finance/attachments
响应 data 字段
- id
- 附件 ID
- objectKey
- 存储引用
- name
- 文件名
- mimeType
- MIME 类型
- size
- 字节数
- downloadUrl
- 需要 Bearer Key 的相对下载地址
- attachmentKey
- 跟进或收支所用的附件引用
- attachmentName
- 附件名称
- attachmentSize
- 字节数字符串
- attachmentMimeType
- MIME 类型
- media
- 仅交流上传：用于发布时关联的媒体对象
curl --request POST "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/finance/attachments" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--form "file=@./example.png"成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。