添加费用明细

你可以为任何交易添加并丰富一个备注、一个类别，以及/或者一个附件（例如收据、发票、采购订单）。可在原始交易时添加注释，或在事后通过 updateTransactionMetadata 变更进行更新。对于启用了 ERP 集成且已连接 QuickBooks Online 的账户，你还可以管理 ERP 交易元数据：会计类别、供应商、客户、可计费状态，以及 ERP 专属备注。ERP 元数据与注释相互独立。支持注释的交易：

入金（depositCashBalance）
礼品卡购买（purchaseGiftCard）
钱包转账（createTransfer、transferInternalBalance）
虚拟卡创建（createVirtualCard）
- 不支持 attachment

支持 ERP 元数据的操作：

已有交易（updateTransactionMetadata.input.erpTransactionMetadata）
批量交易更新（bulkUpdateErpTransactionMetadata）
交易读取（Transaction.erpMetadata、erpTransactionMetadata、erpTransactionMetadataList）

工作原理

可选：如果你想附加文件，请先通过 REST 上传端点上传。你将获得一个 attachmentId。
在交易时或之后通过 updateTransactionMetadata，将 memo、transactionCategory，以及/或者 attachmentId 传入你的变更输入。
对于 ERP 元数据，先查询已导入的 QuickBooks Online 参考项，或直接传入需要在 QuickBooks Online 中解析或创建的名称。
使用 updateTransactionMetadata.input.erpTransactionMetadata 更新单笔交易的 ERP 元数据，或用 bulkUpdateErpTransactionMetadata 一次更新最多 100 笔交易。
通过 getTransactions、getUserPurchases 或变更响应读取注释。通过 Transaction.erpMetadata、erpTransactionMetadata 或 erpTransactionMetadataList 读取 ERP 详情。attachmentUrl 字段返回用于访问文件的短期签名 URL。

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

这是一个 REST 端点，而非 GraphQL 变更

端点

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 —— 你将在下一步把它传入变更输入中。

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

上传错误

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

步骤 2：为交易添加注释

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

选项 A — 交易发生时

以下变更的输入均接受可选字段 memo、transactionCategory 和 attachmentId：

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

注释字段

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

示例 — 购买礼品卡并添加注释

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`）

使用此变更为任意已存在的交易添加或更新注释。

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

变更

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`	此导入 ERP 参考项的 Fluz ID。在 ERP 元数据更新输入中使用该值。
`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 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 中返回，其他有效项仍可成功。

读取注释

以下接口会返回注释：

查询 / 变更	类型	字段
`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）

​变更

​UpdateTransactionMetadataInput

​必需的权限范围

​示例 — 添加备注和类别

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

​示例 — 清空备注

​示例响应

​错误

​步骤 3：管理 ERP 元数据

​UpdateErpTransactionMetadataInput

​示例：同时更新注释与 ERP 元数据

​步骤 4：查找 ERP 参考项

​参考项字段

​参考项过滤器

​示例：搜索会计科目表

​示例：搜索供应商与客户

​步骤 5：读取 ERP 元数据

​在 getTransactions 中读取 ERP 元数据

​读取单笔交易的 ERP 元数据

​列出 ERP 元数据记录

​ERP 元数据列表过滤器

​ERP 同步状态

​批量更新 ERP 元数据

​变更

​变量

​示例响应

​读取注释

​常见错误

​说明与限制

工作原理

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

端点

认证

请求

示例请求

响应

上传错误

步骤 2：为交易添加注释

选项 A — 交易发生时

注释字段

示例 — 购买礼品卡并添加注释

选项 B — 交易发生后（`updateTransactionMetadata`）

变更

UpdateTransactionMetadataInput

必需的权限范围

示例 — 添加备注和类别

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

示例 — 清空备注

示例响应

错误

步骤 3：管理 ERP 元数据

UpdateErpTransactionMetadataInput

示例：同时更新注释与 ERP 元数据

步骤 4：查找 ERP 参考项

参考项字段

参考项过滤器

示例：搜索会计科目表

示例：搜索供应商与客户

步骤 5：读取 ERP 元数据

在 getTransactions 中读取 ERP 元数据

读取单笔交易的 ERP 元数据

列出 ERP 元数据记录

ERP 元数据列表过滤器

ERP 同步状态

批量更新 ERP 元数据

变更

变量

示例响应

读取注释

常见错误

说明与限制