總覽 - 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* mutation。API 驗證輸入並將請求排入佇列。該 mutation 回傳的是 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
    }
  }
}

應用程式權限範圍

與核准相關的權限範圍必須同時在應用程式層級（由 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 以了解權限範圍如何被授與與驗證。

請求類型

請求	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 以進行設定與驗證。

事件	觸發時機	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"
}

認證

核准相關的 mutation 視你的整合模式而定，支援 Bearer token（使用者 OAuth）與 Basic Auth（應用程式 API 金鑰）。已驗證主體會成為請求人。請使用具備必要權限範圍的 User Access Token。請參閱 Authentication & Authorization Guide。

錯誤處理

請求類的 mutation 會回傳 RequestApprovalResponse：

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

失敗時：

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

核准與拒絕的 mutation 在無法完成動作時（例如找不到核准或已被處理），會回傳 success: false 並包含 error 物件。

​運作方式

​共用作業

​列出待處理核准

​核准請求

​拒絕請求

​應用程式權限範圍

​請求類型

​Webhooks

​APPROVAL_CREATE 負載

​APPROVAL_APPROVE / APPROVAL_DECLINE 負載

​APPROVAL_HANDLER_ERROR 負載

​認證

​錯誤處理