管理消費力 - Fluz

一旦連結了銀行帳戶（請參見 Linking a Plaid Bank Account），你可以讀取其餘額與消費力，並在需要較即時讀數時，觸發即時餘額重新整理。

什麼是消費力

消費力 是使用者目前可從已連結銀行帳戶支出的金額。此數值基於該帳戶最新已知的餘額，並扣除尚未完全結清的近期 ACH 流出款項。當使用者自該帳戶支出時，這些金額大約會被預扣三個工作天，之後清算完成便不再影響消費力。（確切清算時窗由各銀行設定，可能更短。） Fluz 會自動維持每個已連結帳戶的儲存餘額為最新狀態。當你需要更即時的讀數——例如使用者剛把資金轉入或轉出其銀行——請發出一次即時重新整理（具速率限制；見下文）。重新整理餘額會更新基於餘額推導的消費力數值。

Auth

以包含 MANAGE_PAYMENT 的 Fluz 使用者 Bearer 存取權杖呼叫 /api/v1/graphql。此區域不允許 Basic auth。

Authorization: Bearer <fluz-user-access-token>

取得單一銀行帳戶的消費力

query GetPlaidBankAccountSpendPower($input: PlaidBankAccountInput!) {
  getPlaidBankAccountSpendPower(input: $input) {
    bankAccountId
    spendPower
    availableSpendPower
    lastRecordedBalance
    pendingTransactions
    updatedAt
  }
}

{
  "input": {
    "bankAccountId": "bank-account-id"
  }
}

回應欄位

欄位	說明
`lastRecordedBalance`	此帳戶最新已知的銀行餘額。
`pendingTransactions`	近期 ACH 流出（約近三個工作天的借記）尚未結清，且仍自餘額中預扣的款項。
`availableSpendPower`	使用者此刻可支出的金額，來自最新餘額扣除預扣款。於即時餘額重新整理後會立即變動。
`spendPower`	此帳戶的決策性消費力數值。其更新頻率可能慢於餘額，因此在重新整理後，可能短暫與 `availableSpendPower` 不同。
`updatedAt`	此數值上次計算的時間。

取得最新儲存的餘額

對單一銀行帳戶：

query GetPlaidBankAccountBalance($input: PlaidBankAccountInput!) {
  getPlaidBankAccountBalance(input: $input) {
    platformItemId
    bankInstitutionAuthId
    bankAccountId
    amount
    current
    source
    trigger
    startedAt
  }
}

{
  "input": {
    "bankAccountId": "bank-account-id"
  }
}

對該使用者所有已連結帳戶：

query GetPlaidBankBalances($input: PlaidBankBalanceFilterInput) {
  getPlaidBankBalances(input: $input) {
    platformItemId
    bankInstitutionAuthId
    bankAccountId
    amount
    current
    source
    trigger
    startedAt
  }
}

即時重新整理單一帳戶

為單一銀行帳戶請求具速率限制的即時餘額重新整理。這會自 Plaid 取得新鮮餘額，並更新基於餘額推導的消費力。

mutation RefreshPlaidBankAccountBalance($input: PlaidBankAccountInput!) {
  refreshPlaidBankAccountBalance(input: $input) {
    status
    balances {
      bankAccountId
      amount
      current
      source
      trigger
      startedAt
    }
  }
}

{
  "input": {
    "bankAccountId": "bank-account-id"
  }
}

重新整理速率限制

為了控管成本，即時重新整理以每個 Plaid 機構為單位實施速率限制：每小時一次、每日六次。在限制視窗內提出的重新整理請求，不會再次呼叫 Plaid——會回傳最新的儲存餘額，因此呼叫仍會成功並返回資料。設計你的 UI 時，請勿一律假設返回的餘額一定是全新即時讀數。

重新整理所有連線（快取）

為已驗證帳戶請求所有已連結 Plaid 銀行資料的快取重新整理。

mutation RefreshPlaidBankConnections {
  refreshPlaidBankConnections {
    status
    balances {
      bankAccountId
      amount
      current
    }
    verifyMembers {
      platformItemId
      bankInstitutionAuthId
    }
  }
}

當你希望 identity-service 執行其快取的全連線重新整理時，請使用 refreshPlaidBankConnections。

若回傳 verifyMembers，表示一個或多個連線需要修復。使用 platformItemId 啟動重新連結流程——請參見 Relinking Disconnected Bank Accounts。請注意，單一帳戶的 refreshPlaidBankAccountBalance 變更操作並不會回傳此訊號，因此當你需要偵測已中斷的連線時，請使用 refreshPlaidBankConnections。

​什麼是消費力

​Auth

​取得單一銀行帳戶的消費力

​取得最新儲存的餘額

​即時重新整理單一帳戶

​重新整理速率限制

​重新整理所有連線（快取）