概览 - Fluz

使用 Fluz API 提交敏感账户操作的审批请求、列出待处理请求，并代表管理者进行批准或拒绝。审批请求通过 Transactional Graph Service 的 GraphQL API 提供。当提交请求时，Fluz 会创建持久的审批记录并通知已配置的审批人。若获批，底层操作将自动执行（例如，购买礼品卡或转账）。

工作原理

Requester                    Manager / Approver
   |                                |
   |  1. request* mutation          |
   |------------------------------->|
   |                                |
   |  2. APPROVAL_CREATE webhook    |
   |<-------------------------------|
   |                                |
   |              3. approvalRequests query (optional)
   |              4. approveApprovalRequest or declineApprovalRequest
   |                                |
   |  5. APPROVAL_APPROVE or        |
   |     APPROVAL_DECLINE webhook   |
   |<-------------------------------|

请求 — 具有相应 REQUEST_* 范围的用户调用 request* 变更。API 会验证输入并将请求加入队列。该变更返回 messageId，而不是 approvalId。
创建 — Fluz 创建一条待审批记录并将账户管理者指派为审批人。你的应用会接收包含 approvalId 的 APPROVAL_CREATE webhook。
列表（可选） — 具有 LIST_APPROVALS 的审批人可调用 approvalRequests 获取该账户的未结请求。
批准或拒绝 — 具有 MANAGE_APPROVALS 的审批人调用 approveApprovalRequest 或 declineApprovalRequest。批准后，Fluz 会执行所请求的操作。
Webhook — 你的应用会接收 APPROVAL_APPROVE 或 APPROVAL_DECLINE。若在批准后执行失败，可能会收到 APPROVAL_HANDLER_ERROR。

请求以异步方式处理。提交后通过轮询 approvalRequests 或监听 webhook 获取 approvalId。

通用操作

以下操作适用于所有审批请求类型。

列出待处理审批

approvalRequests 返回已认证账户的开放（PENDING）审批请求。 所需范围： LIST_APPROVALS

query {
  approvalRequests {
    approvalId
    accountId
    requesterUserId
    approvalType
    approvalCode
    approvalStatus
    approversLogic
    expireDate
    createdAt
    approvers {
      approvalApproverId
      approverUserId
      role
      status
    }
  }
}

批准请求

approveApprovalRequest 批准一条待处理请求。成功后，Fluz 将运行该请求关联的操作（例如，创建虚拟卡）。 所需范围： MANAGE_APPROVALS

mutation {
  approveApprovalRequest(approvalId: "07df5653-43a8-4532-9881-3ab5857bbe12") {
    success
    approvalId
    action
    error {
      code
      message
    }
  }
}

拒绝请求

declineApprovalRequest 拒绝一条待处理请求。不执行任何下游操作。 所需范围： MANAGE_APPROVALS

mutation {
  declineApprovalRequest(approvalId: "07df5653-43a8-4532-9881-3ab5857bbe12") {
    success
    approvalId
    action
    error {
      code
      message
    }
  }
}

应用范围（Scopes）

与审批相关的范围必须同时在应用层级（由 Fluz 授权）和用户层级（通过 OAuth 同意或 generateUserAccessToken）授予。

Scope	用途
`LIST_APPROVALS`	列出待处理审批请求；接收 `APPROVAL_CREATE` 与 `APPROVAL_HANDLER_ERROR` webhook
`MANAGE_APPROVALS`	批准或拒绝请求；接收 `APPROVAL_APPROVE` 与 `APPROVAL_DECLINE` webhook
`REQUEST_VIRTUAL_CARD`	提交虚拟卡创建请求
`REQUEST_VIRTUAL_CARD_LIMIT_CHANGE`	提交虚拟卡限额变更请求
`REQUEST_GIFT_CARD`	提交礼品卡购买请求
`REQUEST_INTERNAL_TRANSFER`	提交内部消费账户转账请求
`REQUEST_ACCOUNT_TRANSFER`	提交账户到账户转账请求
`REQUEST_REIMBURSEMENT`	提交报销请求

参见 Authentication 了解范围的授予与校验方式。

请求类型

请求	变更	创建所需范围
创建虚拟卡	`requestVirtualCard`	`REQUEST_VIRTUAL_CARD`
虚拟卡限额变更	`requestVirtualCardLimitChange`	`REQUEST_VIRTUAL_CARD_LIMIT_CHANGE`
购买礼品卡	`requestGiftCardPurchase`	`REQUEST_GIFT_CARD`
内部转账	`requestInternalTransfer`	`REQUEST_INTERNAL_TRANSFER`
账户转账	`requestAccountTransfer`	`REQUEST_ACCOUNT_TRANSFER`
报销	`requestReimbursement`	`REQUEST_REIMBURSEMENT`

每种请求类型都有专门的指南，包含输入字段、示例和 webhook 标识符。

Webhooks

在 Fluz 开发者门户中配置 webhook。审批事件使用与其他 Fluz webhook 相同的投递机制。参见 Developers overview 了解设置与验证。

事件	触发时机	Webhook 订阅范围
`APPROVAL_CREATE`	创建了新的审批请求	`LIST_APPROVALS`
`APPROVAL_APPROVE`	请求被批准	`MANAGE_APPROVALS`
`APPROVAL_DECLINE`	请求被拒绝	`MANAGE_APPROVALS`
`APPROVAL_HANDLER_ERROR`	审批成功但操作执行失败	`LIST_APPROVALS`

APPROVAL_CREATE 负载

{
  "approvalId": "07df5653-43a8-4532-9881-3ab5857bbe12",
  "accountId": "b1155504-ad30-4b2f-873d-b8795277b128",
  "userId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "approvalType": "GIFT_CARD",
  "approvalCode": "400007",
  "approvalStatus": "PENDING",
  "createdAt": "2025-07-09T10:00:00Z"
}

将 approvalType 与 approvalCode 结合使用来识别请求类型。每个类型指南都会列出该请求的取值。

APPROVAL_APPROVE / APPROVAL_DECLINE 负载

{
  "approvalId": "07df5653-43a8-4532-9881-3ab5857bbe12",
  "accountId": "b1155504-ad30-4b2f-873d-b8795277b128",
  "userId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "approvalType": "GIFT_CARD",
  "approvalCode": "400007",
  "approvalStatus": "APPROVED",
  "approvalAction": "APPROVE",
  "approverAccountId": "d4e5f6a7-b8c9-0123-def4-567890123456",
  "approverUserId": "e5f6a7b8-c9d0-1234-ef56-789012345678",
  "linkId": "f6a7b8c9-d0e1-2345-f678-901234567890",
  "attemptedAt": "2025-07-09T10:05:00Z"
}

对于拒绝，approvalAction 为 DECLINE，approvalStatus 为 DECLINED。

APPROVAL_HANDLER_ERROR 负载

当请求已被批准但下游操作失败时发送（例如，执行时余额不足）。

{
  "approvalId": "07df5653-43a8-4532-9881-3ab5857bbe12",
  "accountId": "b1155504-ad30-4b2f-873d-b8795277b128",
  "userId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "approvalType": "GIFT_CARD",
  "approvalCode": "400007",
  "approvalStatus": "APPROVED",
  "approvalAction": "APPROVE",
  "failureStage": "ACTION_EXECUTION",
  "error": "Insufficient balance",
  "failedAt": "2025-07-09T10:05:01Z"
}

认证

根据你的集成方式，审批变更支持 Bearer token（用户 OAuth）与 Basic Auth（应用 API key）。已认证的主体将成为请求发起人。使用具备所需范围的 User Access Token。参见 Authentication & Authorization Guide。

错误处理

请求变更返回 RequestApprovalResponse：

{
  "data": {
    "requestGiftCardPurchase": {
      "success": true,
      "messageId": "1234567890"
    }
  }
}

失败时：

{
  "data": {
    "requestGiftCardPurchase": {
      "success": false,
      "messageId": null,
      "error": {
        "code": "APPROVAL_REQUEST_FAILED",
        "message": "Input validation error: ..."
      }
    }
  }
}

批准与拒绝的变更在操作无法完成时返回 success: false 且带有 error 对象（例如，未找到审批或已被处理）。

​工作原理

​通用操作

​列出待处理审批

​批准请求

​拒绝请求

​应用范围（Scopes）

​请求类型

​Webhooks

​APPROVAL_CREATE 负载

​APPROVAL_APPROVE / APPROVAL_DECLINE 负载

​APPROVAL_HANDLER_ERROR 负载

​认证

​错误处理