管理消费能力

一旦银行账户已链接（参见 链接 Plaid 银行账户），你可以读取其余额和消费能力，并在需要更实时的读数时触发实时余额刷新。

消费能力含义

消费能力 是用户当前可以从已链接银行账户中支出的金额。它基于该账户最近一次已知余额，减去尚未完全结算的近期 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 启动重新链接流程——参见 重新链接已断开的银行账户。请注意，单账户的 refreshPlaidBankAccountBalance 变更操作不会返回此信号，因此当你需要检测断开连接时，请使用 refreshPlaidBankConnections。

​消费能力含义

​Auth

​获取单个银行账户的消费能力

​获取最新存储的余额

​实时刷新单个账户

​刷新频率限制

​刷新所有连接（缓存）