新增費用明細

您可以為任何交易新增備註、分類，以及/或附件（例如收據、發票、採購單）。註解可在原始交易時加入，或之後使用 updateTransactionMetadata mutation 更新。對於已啟用 ERP 整合且有有效 QuickBooks Online 連線的帳戶，您也可以管理 ERP 交易中繼資料：會計分類、供應商、客戶、可計費狀態，以及 ERP 專用的備註。ERP 中繼資料與註解彼此獨立。註解支援於：

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

ERP 中繼資料支援於：

既有交易（updateTransactionMetadata.input.erpTransactionMetadata）
交易批次更新（bulkUpdateErpTransactionMetadata）
交易讀取（Transaction.erpMetadata, erpTransactionMetadata, erpTransactionMetadataList）

運作方式

選用：若您要附加檔案，請先透過 REST 上傳端點上傳。您會取得一個 attachmentId。
將 memo、transactionCategory，以及/或 attachmentId 傳入 mutation 的 input 中——可於交易當下或之後透過 updateTransactionMetadata 傳入。
對於 ERP 中繼資料，先查詢已匯入的 QuickBooks Online 參考項目，或傳入應在 QuickBooks Online 解析或建立的名稱。
以 updateTransactionMetadata.input.erpTransactionMetadata 更新單筆交易的 ERP 中繼資料，或使用 bulkUpdateErpTransactionMetadata 一次更新最多 100 筆交易。
透過 getTransactions、getUserPurchases，或 mutation 回應讀取註解。透過 Transaction.erpMetadata、erpTransactionMetadata，或 erpTransactionMetadataList 讀取 ERP 明細。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 接受 memo、transactionCategory 與 attachmentId 作為 input 中的選填欄位：

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.0,
  "balanceAmount": 50.0,
  "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) {
    recordId
    memo
    transactionCategory
    attachmentUrl
  }
}

UpdateTransactionMetadataInput

欄位	類型	必填	說明
`recordId`	UUID!	是	要更新的交易 `recordId`。
`memo`	String	否	自由文字備註。最多 255 個字元。省略則不變；傳入 `null` 以清空。
`transactionCategory`	String	否	分類標籤。省略則不變；傳入 `null` 以清空。
`attachmentId`	String	否	來自上傳端點的 ID。省略則不變；傳入 `null` 以清空。
`erpTransactionMetadata`	`UpdateErpTransactionMetadataInput`	否	選用的 ERP 感知分類。省略或傳入 `null` 皆不變更 ERP 中繼資料。

必要權限範圍

LIST_PAYMENT 與 LIST_PURCHASES。若包含 erpTransactionMetadata，此請求也需要 MANAGE_ERP_TRANSACTION_METADATA。

範例 — 新增備註與分類

{
  "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": {
      "recordId": "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.

步驟 3：管理 ERP 中繼資料

ERP 中繼資料用於在匯出至已連線的會計服務供應商前，先行為交易分類。目前可用的供應商為 QuickBooks Online。 ERP 中繼資料欄位與註解分開：

註解的 memo 最多 255 個字元。
ERP 的 erpTransactionMetadata.memo 最多 4000 個字元。
註解的 transactionCategory 是 Fluz 的分類標籤。
ERP 的 categoryReferenceItemId 會指向 QuickBooks Online 的會計科目表項目。

UpdateErpTransactionMetadataInput

欄位	類型	說明
`categoryReferenceItemId`	`UUID`	QuickBooks Online 會計科目表參考項目 ID。省略則不變；傳入 `null` 以清空。必須參照到啟用中的會計科目表項目。
`categoryName`	`String`	依名稱尋找或建立 QuickBooks Online 的 Expense 帳戶，並將其用作分類。當提供 `categoryReferenceItemId` 時會被忽略。最多 100 個字元。
`vendorReferenceItemId`	`UUID`	QuickBooks Online 供應商參考項目 ID。省略則不變；傳入 `null` 以清空。必須參照到啟用中的供應商。
`vendorName`	`String`	依名稱尋找或建立 QuickBooks Online 供應商。當提供 `vendorReferenceItemId` 時會被忽略。最多 100 個字元。
`customerReferenceItemId`	`UUID`	QuickBooks Online 客戶參考項目 ID。省略則不變；傳入 `null` 以清空。必須參照到啟用中的客戶。
`customerName`	`String`	依名稱尋找或建立 QuickBooks Online 客戶。當提供 `customerReferenceItemId` 時會被忽略。最多 100 個字元。
`isBillable`	`Boolean`	設定可計費狀態。省略則不變；傳入 `null` 以清空。若為 `true`，在交易成為 `READY` 之前必須指定客戶。
`memo`	`String`	ERP 備註。省略則不變；傳入 `null` 以清空。最多 4000 個字元。

當您不想更新 ERP 中繼資料時，請從請求中省略 erpTransactionMetadata。

範例：同時更新註解與 ERP 中繼資料

mutation updateTransactionMetadata($input: UpdateTransactionMetadataInput!) {
  updateTransactionMetadata(input: $input) {
    recordId
    memo
    transactionCategory
    erpMetadata {
      category {
        referenceItemId
        name
      }
      vendor {
        referenceItemId
        name
      }
      customer {
        referenceItemId
        name
      }
      isBillable
      memo
      syncStatus
    }
  }
}

{
  "input": {
    "recordId": "550e8400-e29b-41d4-a716-446655440000",
    "memo": "Receipt added in Fluz",
    "transactionCategory": "Office Supplies",
    "erpTransactionMetadata": {
      "categoryReferenceItemId": "11111111-1111-4111-8111-111111111111",
      "vendorName": "Example Vendor",
      "customerReferenceItemId": "22222222-2222-4222-8222-222222222222",
      "isBillable": true,
      "memo": "QuickBooks Online memo for client office supplies"
    }
  }
}

步驟 4：尋找 ERP 參考項目

使用以下查詢以在設定 categoryReferenceItemId、vendorReferenceItemId 或 customerReferenceItemId 前，先尋找已匯入的 QuickBooks Online 參考項目。

查詢	回傳內容
`erpChartOfAccounts`	已匯入的 QuickBooks Online 會計科目表項目。
`erpVendors`	已匯入的 QuickBooks Online 供應商。
`erpCustomers`	已匯入的 QuickBooks Online 客戶。

參考項目欄位

欄位	說明
`referenceItemId`	Fluz 對應此已匯入 ERP 參考項目的 ID。在更新 ERP 中繼資料的 input 中使用此值。
`externalId`	QuickBooks Online 的 ID。
`name`	顯示名稱。
`fullyQualifiedName`	供應商端的完整限定名稱（若可用）。
`accountType`	會計科目表的帳戶類型。僅會計科目表項目會帶有此欄位。
`accountSubType`	會計科目表的子類型。僅會計科目表項目會帶有此欄位。
`active`	匯入的供應商端項目是否為啟用狀態。
`lastChangedAt`	QuickBooks Online 上次更新時間戳（若可用）。

參考項目篩選器

欄位	類型	說明
`q`	`String`	對名稱進行不分大小寫的子字串搜尋。
`active`	`Boolean`	預設為 `true`。設定為 `false` 以列出非啟用項目。
`accountType`	`[String!]`	僅適用會計科目表。以 QuickBooks Online 帳戶類型（如 `Expense`）進行篩選。
`accountSubType`	`[String!]`	僅適用會計科目表。以 QuickBooks Online 帳戶子類型進行篩選。
`sortKey`	`ErpReferenceItemSortKey`	`NAME`、`FULLY_QUALIFIED_NAME`，或 `LAST_CHANGED_AT`。預設為 `NAME`。
`sortOrder`	`SortOrder`	`ASC` 或 `DESC`。預設為 `ASC`。

範例：搜尋會計科目表

query erpChartOfAccounts {
  erpChartOfAccounts(
    filter: {
      q: "office"
      accountType: ["Expense"]
      sortKey: NAME
      sortOrder: ASC
    }
    paginate: { limit: 10, offset: 0 }
  ) {
    totalCount
    hasNextPage
    items {
      referenceItemId
      externalId
      name
      fullyQualifiedName
      accountType
      accountSubType
      active
      lastChangedAt
    }
  }
}

範例：搜尋供應商與客戶

query erpCounterparties {
  erpVendors(
    filter: { q: "example vendor" }
    paginate: { limit: 10, offset: 0 }
  ) {
    items {
      referenceItemId
      name
      active
    }
  }
  erpCustomers(
    filter: { q: "example company" }
    paginate: { limit: 10, offset: 0 }
  ) {
    items {
      referenceItemId
      name
      active
    }
  }
}

步驟 5：讀取 ERP 中繼資料

ERP 中繼資料可從交易物件或透過專用的 ERP 中繼資料查詢取得。

在 getTransactions 中讀取 ERP 中繼資料

query getTransactionsWithErpMetadata {
  getTransactions(paginate: { limit: 10, offset: 0 }) {
    totalCount
    hasNextPage
    transactions {
      recordId
      amount
      memo
      transactionCategory
      erpMetadata {
        transactionMetadataId
        transactionRecordId
        category {
          referenceItemId
          name
        }
        vendor {
          referenceItemId
          name
        }
        customer {
          referenceItemId
          name
        }
        isBillable
        memo
        syncStatus
        isSyncing
        updatedAt
      }
    }
  }
}

當帳戶沒有啟用中的 ERP 連線，或該交易沒有 ERP 中繼資料時，erpMetadata 會是 null。

讀取單筆交易的 ERP 中繼資料

query erpTransactionMetadata($transactionRecordId: UUID!) {
  erpTransactionMetadata(transactionRecordId: $transactionRecordId) {
    transactionMetadataId
    transactionRecordId
    category {
      referenceItemId
      name
    }
    vendor {
      referenceItemId
      name
    }
    customer {
      referenceItemId
      name
    }
    isBillable
    memo
    syncStatus
    isSyncing
    updatedAt
  }
}

{
  "transactionRecordId": "550e8400-e29b-41d4-a716-446655440000"
}

若該交易沒有 ERP 中繼資料或帳戶沒有啟用中的 ERP 連線，此查詢會回傳 null，而非錯誤。

列出 ERP 中繼資料紀錄

query erpTransactionMetadataList {
  erpTransactionMetadataList(
    filter: { syncStatus: DRAFT, updatedAfter: "2026-07-01T00:00:00.000Z" }
    paginate: { limit: 20, offset: 0 }
  ) {
    totalCount
    hasNextPage
    items {
      transactionRecordId
      category {
        referenceItemId
        name
      }
      isBillable
      memo
      syncStatus
      updatedAt
    }
  }
}

ERP 中繼資料清單篩選器

欄位	類型	說明
`syncStatus`	`ErpTransactionSyncStatus`	依同步狀態篩選。
`updatedAfter`	`DateTime`	回傳在此時間戳之後更新的中繼資料。
`transactionRecordIds`	`[UUID!]`	僅限於特定交易紀錄 ID。
`sortKey`	`ErpTransactionMetadataSortKey`	目前為 `UPDATED_AT`。預設為 `UPDATED_AT`。
`sortOrder`	`SortOrder`	`ASC` 或 `DESC`。預設為 `DESC`。

ERP 同步狀態

狀態	意義
`DRAFT`	缺少必要的 ERP 欄位，尚無法匯出。多數交易類型需要分類。若 `isBillable` 為 `true`，也需要客戶。
`READY`	必要的 ERP 欄位已齊備，交易可準備匯出。
`SYNC_STARTED`	正在匯出到會計供應商。此狀態期間無法編輯交易。
`SYNCED`	匯出成功。之後無法再透過 ERP 中繼資料 API 修改該交易。
`SYNC_FAILED`	上次匯出嘗試失敗。請編輯中繼資料並重試匯出。

批次更新 ERP 中繼資料

使用 bulkUpdateErpTransactionMetadata 可在單一請求中更新最多 100 筆交易的 ERP 中繼資料。每個項目皆使用相同的 UpdateErpTransactionMetadataInput 欄位。省略的欄位保持不變；可為空的參考欄位、memo 與 isBillable 可傳入 null 以清空。

Mutation

mutation bulkUpdateErpTransactionMetadata(
  $items: [BulkUpdateErpTransactionMetadataItem!]!
) {
  bulkUpdateErpTransactionMetadata(items: $items) {
    succeeded
    failed {
      transactionRecordId
      error {
        code
        message
      }
    }
  }
}

變數

{
  "items": [
    {
      "transactionRecordId": "550e8400-e29b-41d4-a716-446655440000",
      "erpTransactionMetadata": {
        "categoryName": "Office Supplies",
        "vendorName": "Example Vendor",
        "memo": "Bulk-updated QuickBooks Online memo"
      }
    },
    {
      "transactionRecordId": "660e8400-e29b-41d4-a716-446655440000",
      "erpTransactionMetadata": {
        "categoryReferenceItemId": "11111111-1111-4111-8111-111111111111",
        "customerName": "Example Company LLC",
        "isBillable": true
      }
    }
  ]
}

範例回應

{
  "data": {
    "bulkUpdateErpTransactionMetadata": {
      "succeeded": ["550e8400-e29b-41d4-a716-446655440000"],
      "failed": [
        {
          "transactionRecordId": "660e8400-e29b-41d4-a716-446655440000",
          "error": {
            "code": "ERP-0019",
            "message": "The reference item type does not match the expected type for this field."
          }
        }
      ]
    }
  }
}

針對單筆的 ERP 驗證失敗會回傳於 failed 中，其他有效的項目仍可成功。

讀取註解

以下項目會回傳註解：

查詢 / Mutation	類型	欄位
`getTransactions`	`Transaction`	`memo`、`transactionCategory`、`attachmentUrl`、選填 `erpMetadata`
`getUserPurchases`	`UserPurchase`	`memo`、`transactionCategory`、`attachmentUrl`
`updateTransactionMetadata`	`Transaction`	`memo`、`transactionCategory`、`attachmentUrl`、選填 `erpMetadata`
`depositCashBalance`	`CashBalanceDeposit`	`attachmentUrl`
`erpTransactionMetadata`	`ErpTransactionMetadata`	ERP 分類、供應商、客戶、可計費狀態、ERP 備註、同步狀態
`erpTransactionMetadataList`	`ErpTransactionMetadataConnection`	分頁的 ERP 中繼資料紀錄

⚠️ attachmentUrl 為簽署 URL。它會在產生後不久到期。請勿儲存——當您需要顯示或存取檔案時，請重新抓取該交易。

常見錯誤

原因	錯誤
缺少註解所需的權限範圍	`AUTH-0031` / invalid scope
缺少 ERP 讀取所需的 `VIEW_ERP_TRANSACTION_METADATA`	`AUTH-0031` / invalid scope
缺少 ERP 寫入所需的 `MANAGE_ERP_TRANSACTION_METADATA`	`AUTH-0031` / invalid scope
帳戶未啟用 ERP 整合	`ERP-0018` / forbidden
沒有啟用中的 QuickBooks Online 連線	`ERP-0001` / no active connection
QuickBooks Online 連線需要處理	`ERP-0016` / connection action required
在此帳戶中找不到交易	`ERP-0026` / transaction not found
交易已同步	`ERP-0027` / transaction already synced
交易匯出進行中	`ERP-0052` / transaction sync in progress
參考項目類型錯誤或不屬於此連線	`ERP-0019` / invalid reference type
參考項目為非啟用狀態	`ERP-0028` / stale reference item
ERP 備註超過 4000 個字元	`ERP-0029` / memo too long

注意事項與限制

recordId 為交易查詢回傳的交易紀錄 ID。
註解更新為部分更新：省略的欄位保持不變，傳入 null 會清空。
ERP 中繼資料更新同樣為部分更新：省略的欄位保持不變，且支援為空的欄位可用 null 清空。
在 updateTransactionMetadata 中，erpTransactionMetadata: null 表示不進行任何操作（no-op），而非清空。
在 updateTransactionMetadata 中，erpTransactionMetadata: {} 無效。請改為省略該欄位。
若同時提供 ERP 參考 ID 與名稱於同一欄位，會以參考 ID 為準。
categoryName 會建立或選擇一個 QuickBooks Online、帳戶類型為 Expense 的帳戶。
vendorName 會建立或選擇一個 QuickBooks Online 供應商。
customerName 會建立或選擇一個 QuickBooks Online 客戶。
GraphQL 分頁使用 OffsetInput，limit 預設為 20，且受 API 分頁上限限制。

​運作方式

​步驟 1：上傳附件（選用）

​端點

​驗證

​請求

​範例請求

​回應

​上傳錯誤

​步驟 2：為交易加上註解

​選項 A — 於交易當下

​註解欄位

​範例 — 購買禮品卡並加上註解

​選項 B — 交易後（updateTransactionMetadata）

​Mutation

​UpdateTransactionMetadataInput

​必要權限範圍

​範例 — 新增備註與分類

​範例 — 為既有交易附加檔案

​範例 — 清空備註

​範例回應

​錯誤

​步驟 3：管理 ERP 中繼資料

​UpdateErpTransactionMetadataInput

​範例：同時更新註解與 ERP 中繼資料

​步驟 4：尋找 ERP 參考項目

​參考項目欄位

​參考項目篩選器

​範例：搜尋會計科目表

​範例：搜尋供應商與客戶

​步驟 5：讀取 ERP 中繼資料

​在 getTransactions 中讀取 ERP 中繼資料

​讀取單筆交易的 ERP 中繼資料

​列出 ERP 中繼資料紀錄

​ERP 中繼資料清單篩選器

​ERP 同步狀態

​批次更新 ERP 中繼資料

​Mutation

​變數

​範例回應

​讀取註解

​常見錯誤

​注意事項與限制

運作方式

步驟 1：上傳附件（選用）

端點

驗證

請求

範例請求

回應

上傳錯誤

步驟 2：為交易加上註解

選項 A — 於交易當下

註解欄位

範例 — 購買禮品卡並加上註解

選項 B — 交易後（`updateTransactionMetadata`）

Mutation

UpdateTransactionMetadataInput

必要權限範圍

範例 — 新增備註與分類

範例 — 為既有交易附加檔案

範例 — 清空備註

範例回應

錯誤

步驟 3：管理 ERP 中繼資料

UpdateErpTransactionMetadataInput

範例：同時更新註解與 ERP 中繼資料

步驟 4：尋找 ERP 參考項目

參考項目欄位

參考項目篩選器

範例：搜尋會計科目表

範例：搜尋供應商與客戶

步驟 5：讀取 ERP 中繼資料

在 getTransactions 中讀取 ERP 中繼資料

讀取單筆交易的 ERP 中繼資料

列出 ERP 中繼資料紀錄

ERP 中繼資料清單篩選器

ERP 同步狀態

批次更新 ERP 中繼資料

Mutation

變數

範例回應

讀取註解

常見錯誤

注意事項與限制