> ## 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*` mutation。API 驗證輸入並將請求排入佇列。該 mutation 回傳的是 `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 } } } ``` ## 應用程式權限範圍 與核准相關的權限範圍必須同時在應用程式層級（由 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) 以了解權限範圍如何被授與與驗證。 ## 請求類型 | 請求 | Mutation | 建立所需權限範圍 | | ------- | ------------------------------- | ----------------------------------- | | 虛擬卡建立 | `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" } ``` ## 認證 核准相關的 mutation 視你的整合模式而定，支援 Bearer token（使用者 OAuth）與 Basic Auth（應用程式 API 金鑰）。已驗證主體會成為請求人。 請使用具備必要權限範圍的 User Access Token。請參閱 [Authentication & Authorization Guide](/concepts/authentication)。 ## 錯誤處理 請求類的 mutation 會回傳 `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: ..." } } } } ``` 核准與拒絕的 mutation 在無法完成動作時（例如找不到核准或已被處理），會回傳 `success: false` 並包含 `error` 物件。