> ## Documentation Index > Fetch the complete documentation index at: https://docs.fluz.app/llms.txt > Use this file to discover all available pages before exploring further. # 概览 使用 Fluz API 提交敏感账户操作的审批请求、列出待处理请求，并代表管理者进行批准或拒绝。 审批请求通过 Transactional Graph Service 的 GraphQL API 提供。当提交请求时，Fluz 会创建持久的审批记录并通知已配置的审批人。若获批，底层操作将自动执行（例如，购买礼品卡或转账）。 ## 工作原理 ```text theme={null} 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 | |<-------------------------------| ``` 1. **请求** — 具有相应 `REQUEST_*` 范围的用户调用 `request*` 变更。API 会验证输入并将请求加入队列。该变更返回 `messageId`，而不是 `approvalId`。 2. **创建** — Fluz 创建一条待审批记录并将账户管理者指派为审批人。你的应用会接收包含 `approvalId` 的 `APPROVAL_CREATE` webhook。 3. **列表（可选）** — 具有 `LIST_APPROVALS` 的审批人可调用 `approvalRequests` 获取该账户的未结请求。 4. **批准或拒绝** — 具有 `MANAGE_APPROVALS` 的审批人调用 `approveApprovalRequest` 或 `declineApprovalRequest`。批准后，Fluz 会执行所请求的操作。 5. **Webhook** — 你的应用会接收 `APPROVAL_APPROVE` 或 `APPROVAL_DECLINE`。若在批准后执行失败，可能会收到 `APPROVAL_HANDLER_ERROR`。 > 请求以异步方式处理。提交后通过轮询 `approvalRequests` 或监听 webhook 获取 `approvalId`。 ## 通用操作 以下操作适用于所有审批请求类型。 ### 列出待处理审批 `approvalRequests` 返回已认证账户的开放（`PENDING`）审批请求。 **所需范围：** `LIST_APPROVALS` ```graphql theme={null} query { approvalRequests { approvalId accountId requesterUserId approvalType approvalCode approvalStatus approversLogic expireDate createdAt approvers { approvalApproverId approverUserId role status } } } ``` ### 批准请求 `approveApprovalRequest` 批准一条待处理请求。成功后，Fluz 将运行该请求关联的操作（例如，创建虚拟卡）。 **所需范围：** `MANAGE_APPROVALS` ```graphql theme={null} mutation { approveApprovalRequest(approvalId: "07df5653-43a8-4532-9881-3ab5857bbe12") { success approvalId action error { code message } } } ``` ### 拒绝请求 `declineApprovalRequest` 拒绝一条待处理请求。不执行任何下游操作。 **所需范围：** `MANAGE_APPROVALS` ```graphql theme={null} 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](/concepts/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](/developers) 了解设置与验证。 | 事件 | 触发时机 | Webhook 订阅范围 | | ------------------------ | ----------- | ------------------ | | `APPROVAL_CREATE` | 创建了新的审批请求 | `LIST_APPROVALS` | | `APPROVAL_APPROVE` | 请求被批准 | `MANAGE_APPROVALS` | | `APPROVAL_DECLINE` | 请求被拒绝 | `MANAGE_APPROVALS` | | `APPROVAL_HANDLER_ERROR` | 审批成功但操作执行失败 | `LIST_APPROVALS` | ### APPROVAL\_CREATE 负载 ```json theme={null} { "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 负载 ```json theme={null} { "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 负载 当请求已被批准但下游操作失败时发送（例如，执行时余额不足）。 ```json theme={null} { "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](/concepts/authentication)。 ## 错误处理 请求变更返回 `RequestApprovalResponse`： ```json theme={null} { "data": { "requestGiftCardPurchase": { "success": true, "messageId": "1234567890" } } } ``` 失败时： ```json theme={null} { "data": { "requestGiftCardPurchase": { "success": false, "messageId": null, "error": { "code": "APPROVAL_REQUEST_FAILED", "message": "Input validation error: ..." } } } } ``` 批准与拒绝的变更在操作无法完成时返回 `success: false` 且带有 `error` 对象（例如，未找到审批或已被处理）。