添加费用明细

你可以为任何交易添加备注、类别和/或附件（例如收据、发票、采购订单）。可以在原始交易发生时添加注释，或之后通过 updateTransactionMetadata mutation 进行更新。支持注释的场景：

存款（depositCashBalance1）
礼品卡购买（purchaseGiftCard）
钱包转账（createTransfer, transferInternalBalance）
虚拟卡创建（createVirtualCard）
- 不支持 attachment

工作原理

可选：如果你想附加文件，先通过 REST 上传端点上传。你会获得一个 attachmentId。
将 memo、transactionCategory 和/或 attachmentId 传入你的 mutation 输入中——可在交易发生时传入，或之后通过 updateTransactionMetadata 传入。
通过 getTransactions、getUserPurchases 或 mutation 响应读取注释。attachmentUrl 字段会返回一个短期有效的签名 URL 用于文件访问。

第 1 步：上传附件（可选）

这是一个 REST 端点，而不是 GraphQL mutation

端点

POST /api/v1/file-upload/transaction-memo-attachment

认证

Authorization: Bearer <YOUR_USER_ACCESS_TOKEN>

请求

以 multipart/form-data 发送文件，字段名为 file。 接受类型： application/pdf, image/png

⚠️ 交易附件不接受 JPEG。

示例请求

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/file-upload/transaction-memo-attachment \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -F "file=@receipt.pdf"

响应

{
  "attachmentId": "3f2a1b4c-e5d6-7890-abcd-ef1234567890"
}

复制该 attachmentId —— 你将在下一步将其传入 mutation 输入中。

attachmentId 的作用域限定在你的账户内。当你提交 mutation 时，系统会验证该文件是否存在于你账户的存储中。来自其他账户的 ID 将被拒绝。

上传错误

原因	状态	详情
请求中未包含文件	400	Missing file
文件类型不允许（例如 JPEG）	400	`INVALID_ARGUMENTS`

第 2 步：为交易添加注释

你可以在原始交易发生时提供注释，或在之后进行更新。

选项 A — 交易发生时

以下 mutations 在其输入中接受可选字段 memo、transactionCategory 和 attachmentId：

depositCashBalance → DepositCashBalanceInput
purchaseGiftCard → PurchaseGiftCardInput
createTransfer → CreateTransferInput
transferInternalBalance → TransferInternalBalanceInput

注释字段

字段	类型	描述
`memo`	String	自由文本备注。最多 255 个字符。
`transactionCategory`	String	类别标签。自由形式——类别会在首次使用时自动创建，如果再次传入相同名称则复用。
`attachmentId`	String	上传端点返回的 ID。必须在提交 mutation 前完成文件上传。

示例 — 带注释的礼品卡购买

mutation purchaseGiftCard($input: PurchaseGiftCardInput!) {
  purchaseGiftCard(input: $input) {
    purchaseDisplayId
    purchaseAmount
    memo
    transactionCategory
    attachmentUrl
    giftCard {
      giftCardId
      status
    }
  }
}

{
  "idempotencyKey": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "offerId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "amount": 50.00,
  "balanceAmount": 50.00,
  "memo": "Team lunch — Q2",
  "transactionCategory": "Meals & Entertainment",
  "attachmentId": "3f2a1b4c-e5d6-7890-abcd-ef1234567890"
}

选项 B — 交易之后（`updateTransactionMetadata`）

使用此 mutation 为任意已有交易添加或更新注释。

部分更新语义：只会更新你传入的字段。未包含的字段保持不变。传入 null 可清空字段。

Mutation

mutation updateTransactionMetadata($input: UpdateTransactionMetadataInput!) {
  updateTransactionMetadata(input: $input) {
    record_id
    memo
    transactionCategory
    attachmentUrl
  }
}

UpdateTransactionMetadataInput

字段	类型	必填	描述
`recordId`	UUID!	是	要更新的交易的 `record_id`。
`memo`	String	否	自由文本备注。最多 255 个字符。省略则不变；传入 `null` 清空。
`transactionCategory`	String	否	类别标签。省略则不变；传入 `null` 清空。
`attachmentId`	String	否	上传端点返回的 ID。省略则不变；传入 `null` 清空。

必需的作用域

LIST_PAYMENT 和 LIST_PURCHASES

示例 — 添加备注和类别

{
  "recordId": "550e8400-e29b-41d4-a716-446655440000",
  "memo": "Q1 vendor payment",
  "transactionCategory": "Operating Expenses"
}

示例 — 为现有交易附加文件

{
  "recordId": "550e8400-e29b-41d4-a716-446655440000",
  "attachmentId": "3f2a1b4c-e5d6-7890-abcd-ef1234567890"
}

示例 — 清空备注

{
  "recordId": "550e8400-e29b-41d4-a716-446655440000",
  "memo": null
}

示例响应

{
  "data": {
    "updateTransactionMetadata": {
      "record_id": "550e8400-e29b-41d4-a716-446655440000",
      "memo": "Q1 vendor payment",
      "transactionCategory": "Operating Expenses",
      "attachmentUrl": "https://storage.googleapis.com/..."
    }
  }
}

错误

原因	错误
找不到 `recordId` 或属于其他账户	`INVALID_ARGUMENTS` — transaction not found
交易类型不支持元数据	`INVALID_ARGUMENTS` — transaction does not support metadata
`attachmentId` 不是有效的 UUID	`INVALID_ARGUMENTS` — Invalid attachment ID
存储中未找到文件（未上传，或账户不匹配）	`INVALID_ARGUMENTS` — Attachment file not found. Please upload the file first.

读取注释

以下接口会返回注释：

查询 / Mutation	类型	字段
`getTransactions`	`Transaction`	`memo`, `transactionCategory`, `attachmentUrl`
`getUserPurchases`	`UserPurchase`	`memo`, `transactionCategory`, `attachmentUrl`
`updateTransactionMetadata`	`Transaction`	`memo`, `transactionCategory`, `attachmentUrl`
`depositCashBalance`	`CashBalanceDeposit`	`attachmentUrl`

⚠️ attachmentUrl 是签名 URL，生成后会很快过期。请不要存储它——当你需要显示或访问文件时重新获取该交易。

​工作原理

​第 1 步：上传附件（可选）

​端点

​认证

​请求

​示例请求

​响应

​上传错误

​第 2 步：为交易添加注释

​选项 A — 交易发生时

​注释字段

​示例 — 带注释的礼品卡购买

​选项 B — 交易之后（updateTransactionMetadata）

​Mutation

​UpdateTransactionMetadataInput

​必需的作用域

​示例 — 添加备注和类别

​示例 — 为现有交易附加文件

​示例 — 清空备注

​示例响应

​错误

​读取注释