标签与统计
用标签关联收支并查询统计明细。
标签维护
可用标签列表默认排除已归档项，includeArchived=true 可包含归档项。所有成员可新增标签；重命名、归档与恢复需要管理员。
标签统计接口返回分页收支明细，不是聚合金额。可按 tagId、日期范围、分类、记录类型或未标记筛选。非管理员始终只看到本人记录。
接口参考
GET
查询标签列表
/api/v1/workspaces/{workspaceId}/tags
响应 data 字段（列表元素）
- id
- 标签 ID
- name
- 标签名称
- archivedAt
- 归档时间，可为空
- createdAt
- 创建时间 ISO 8601
- updatedAt
- 更新时间 ISO 8601
cURL
curl --request GET "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/tags" \
--header "Authorization: Bearer $AGENT_API_KEY"成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
GET
查询标签详情
/api/v1/workspaces/{workspaceId}/tags/{id}
响应 data 字段
- id
- 标签 ID
- name
- 标签名称
- archivedAt
- 归档时间，可为空
- createdAt
- 创建时间 ISO 8601
- updatedAt
- 更新时间 ISO 8601
cURL
curl --request GET "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/tags/{id}" \
--header "Authorization: Bearer $AGENT_API_KEY"成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
POST
新增标签
/api/v1/workspaces/{workspaceId}/tags
| 参数 | 类型 | 说明 |
|---|---|---|
| name* | string | 沿用业务表单规则 |
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
cURL
curl --request POST "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/tags" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{"name":"服务费用"}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
PATCH
重命名、归档或恢复标签
/api/v1/workspaces/{workspaceId}/tags/{id}
| 参数 | 类型 | 说明 |
|---|---|---|
| operation* | string | rename / archive / restore |
| name | string | 沿用业务表单规则 |
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
cURL
curl --request PATCH "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/tags/{id}" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{"operation":"rename"}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
GET
查询标签收支明细
/api/v1/workspaces/{workspaceId}/tag-report
响应 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
curl --request GET "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/tag-report" \
--header "Authorization: Bearer $AGENT_API_KEY"成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。