新增費用詳細資訊

你可以為任何交易新增備註、類別，以及/或附件（例如收據、發票、採購單）。註記可在原始交易時加入，或之後使用 updateTransactionMetadata mutation 進行更新。支援註記的類型：

存款（depositCashBalance1）
禮品卡購買（purchaseGiftCard）
錢包轉帳（createTransfer, transferInternalBalance）
虛擬卡建立（createVirtualCard）
- 不支援 attachment

運作方式

選用：若你想附加檔案，先透過 REST 上傳端點上傳。你會收到一個 attachmentId。
在 mutation 的 input 中傳入 memo、transactionCategory，以及/或 attachmentId——可以在交易發生時傳入，或之後透過 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 input 中使用它。

attachmentId 會限制在你的帳戶範圍內。當你提交 mutation 時，系統會驗證該檔案是否存在於你的帳戶儲存空間中。來自其他帳戶的 ID 會被拒絕。

上傳錯誤

原因	狀態	詳細資訊
請求中未包含檔案	400	Missing file
檔案類型不允許（例如 JPEG）	400	`INVALID_ARGUMENTS`

第 2 步：為交易加上註記

你可以在原始交易發生時提供註記，或是之後再更新。

選項 A — 在交易發生時

以下 mutations 的 input 接受 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` 以清除。

必要 Scopes

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

​必要 Scopes

​範例 — 新增備註與類別

​範例 — 將檔案附加至現有交易

​範例 — 清除備註

​範例回應

​錯誤

​讀取註記