> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 刷新银行连接 API：立即同步

> Didit 的刷新银行连接端点可立即同步：返回 202 和 sync_id；若等待最多 25 秒，则返回 200 及已完成的同步结果。

Didit 的“刷新银行连接”端点会请求立即同步，并返回 `202` 和 `sync_id`。
发送 `"wait": true` 可最多等待 25 秒，并在一次调用中获得已完成的同步结果，且不额外收费。
由于银行限制无人值守访问，此调用可能返回 `429 refresh_limit_reached` 以及 `Retry-After`。
请参阅[按需刷新银行数据](https://docs.didit.me/zh/use-cases/refresh-bank-data-on-demand.md)。


## OpenAPI

````yaml zh/openapi-25.json POST /v3/bank/connections/{id}/refresh/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: 身份验证 API。使用 x-api-key 请求头进行身份验证。
servers:
  - url: https://verification.didit.me
security: []
tags:
  - name: Bank Data
    description: >-
      银行数据服务涵盖银行链接、连接、账户、余额、交易、机构和覆盖范围。银行数据可用于沙盒应用。在宣布开放生产访问之前，生产应用的调用将返回
      `404`。沙盒环境不收费。使用 API
      密钥进行的调用，需要具备银行数据权限（`bank-data`）的密钥：读取操作需要读取权限，会更改数据的操作需要写入权限。账户核验是例外，它需要会话的写入权限或完全访问权限，而不需要银行数据权限。银行数据不属于完全访问权限的一部分：完全访问密钥会被拒绝，调用返回
      `403
      bank_data_access_denied`，直到您创建具备该权限的密钥为止。原始银行数据（账户、余额、交易以及变更流）同样会拒绝不携带 API
      密钥的请求。


      除账户核验外，`/v3/bank/` 下的每个拒绝响应都具有相同的 JSON
      结构（`code`、`message`、`request_id`、`field`、`next_action`、`retry_after`）。不是操作的路径、不是
      UUID 的 ID 或未知的子资源，对于所有方法都返回 `404 not_found`；任何意外错误都返回 `500 internal_error`
      及 `request_id`。在银行数据不可用时，每个操作都返回平台标准的 `404`，与访问未知路由时完全相同。
paths:
  /v3/bank/connections/{id}/refresh/:
    post:
      tags:
        - Bank Data
      summary: 刷新银行连接
      description: >-
        立即同步：随时向银行读取新数据。返回 `202` 和 `sync_id`；若同步已在进行中，则返回同一个
        `sync_id`，而不会启动第二个任务。若请求正文中包含 `"wait": true`，或包含请求头 `Prefer:
        wait=<seconds>`（最多 25 秒），调用最多等待 25 秒，并返回 `200`
        和已完成的同步结果（`outcome`、各账户的计数以及
        `balances_changed`），因此一次请求即可返回最新数据。若银行在此时间内未响应，则返回 `202`：请使用 `sync_id`
        通过 `get_sync_run` 读取同步结果，或订阅 `bank.sync.completed`。仅当同步存储了变更时，才会发送
        `bank.data.updated`。


        实时同步与自动同步一样，已包含在连接的月费中：不会额外收费。唯一的限制来自银行。银行会限制无人在场时的读取次数，例如每天四次（沙盒中的
        Didit Test Bank
        也是如此）。当天的自动同步次数（`sync.frequency_per_day`）会优先预留，其余次数归你所有，因此
        `sync.budgets` 显示剩余额度，`sync.live_syncs_left_today`
        显示当天剩余的实时同步次数。自动同步计划从不占用每天的最后两次读取，因此始终保留两次实时同步。额度用完后，调用返回 `429
        refresh_limit_reached`，并附带 `Retry-After`（距离额度重置的秒数，范围为 1 到 86400）以及包含
        `live_syncs_left_today` 和 `budgets` 的 `sync`
        对象。该限制是银行设定的上限，并不保证可执行的同步次数。


        同步存储了变更时，`bank.data.updated` 会通知你；随后读取变更流。


        需要具有银行数据权限（`bank-data`）的 API
        密钥：此操作属于写入操作，会改变数据。拥有完全访问权限的密钥不包含该权限：创建密钥时需要显式授予，否则调用将返回 `403
        bank_data_access_denied`。


        刷新已删除的连接将返回 `409 connection_not_active`。
      operationId: refreshBankConnection
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: 连接 ID。
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: Prefer
          in: header
          required: false
          schema:
            type: string
            example: wait=25
          description: '`wait=<seconds>` 会将调用最多挂起指定的秒数（最多 25 秒），与请求体中的 `wait: true` 作用相同。'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankRefreshRequest'
            examples:
              Wait for the result:
                summary: 等待结果
                value:
                  wait: true
      responses:
        '200':
          description: 同步在 25 秒内完成。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankSyncCompleted'
              examples:
                Finished:
                  summary: 已完成的实时同步
                  value:
                    id: d4a9e7b2-1c58-4f03-96ab-5e2d8c7f0b14
                    connection_id: 5e1d2a70-6b3c-4f8e-a1d9-0c7b2e4f8a36
                    trigger: requested
                    status: succeeded
                    started_at: '2026-11-21T12:30:02Z'
                    finished_at: '2026-11-21T12:30:09Z'
                    results:
                      - account_id: a71f0c2e-4d85-4b1a-9e63-2f8c0d5b7a14
                        resource: transactions
                        outcome: succeeded
                        added: 3
                        modified: 0
                        removed: 1
                        error: null
                    outcome: succeeded
                    balances_changed: true
                    error: null
        '202':
          description: 刷新已接受：已排队或已在运行。使用 `wait` 时，若银行在 25 秒内未响应，请使用 `sync_id` 读取同步结果。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankRefreshAccepted'
              examples:
                Queued:
                  summary: 同步任务已进入队列
                  value:
                    sync_id: d4a9e7b2-1c58-4f03-96ab-5e2d8c7f0b14
                    status: queued
                    next_refresh_at: null
        '400':
          description: 请求体无效，例如 `wait` 不是布尔值。`field` 指明具体字段。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Invalid request:
                  summary: 请求无效
                  value:
                    code: invalid_request
                    message: The request is not valid.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: wait
                    next_action: null
                    retry_after: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BankDataAccessDenied'
        '404':
          description: 该资源在此应用和环境中不存在。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Not found:
                  summary: 未找到
                  value:
                    code: not_found
                    message: The resource does not exist.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: null
                    retry_after: null
        '409':
          description: >-
            无法刷新连接：`connection_not_active`（已撤销、已暂停、失败或已删除）或
            `consent_expired`（请先续期）。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Not active:
                  summary: 未激活
                  value:
                    code: connection_not_active
                    message: This connection is not active.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: create_link
                    retry_after: null
                Consent expired:
                  summary: 同意已过期
                  value:
                    code: consent_expired
                    message: The consent ended. Renew the connection to sync again.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: renew_connection
                    retry_after: null
        '429':
          description: 银行为用户不在场时的获取操作所设定的额度已用完。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankRefreshLimitError'
              examples:
                Refresh limit reached:
                  summary: 已达到刷新次数上限
                  value:
                    code: refresh_limit_reached
                    message: >-
                      The bank's limit on fetches without the person present is
                      used up for today.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: retry_later
                    retry_after: 3600
                    sync:
                      live_syncs_left_today: 0
                      budgets:
                        - scope: connection
                          resource: all
                          limit: 4
                          remaining: 0
                          resets_at: '2026-11-22T00:00:00Z'
          headers:
            Retry-After:
              description: 再次请求前需等待的秒数。
              schema:
                type: integer
        '500':
          $ref: '#/components/responses/BankDataInternalError'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: >-
            curl -X POST
            'https://verification.didit.me/v3/bank/connections/5e1d2a70-3b94-4c1f-8a6e-d2f07b9c1e35/refresh/'
            \
              -H 'x-api-key: YOUR_API_KEY'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.bank.refresh_connection(
                "11111111-2222-3333-4444-555555555555",
                wait=True,
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: >-
            import Didit from "@didit-protocol/sdk-node";


            // Reads DIDIT_API_KEY.

            const didit = new Didit();


            const result = await
            didit.bank.refreshConnection("11111111-2222-3333-4444-555555555555",
            {
              wait: true,
            });

            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Bank.RefreshConnection(ctx, \"11111111-2222-3333-4444-555555555555\", didit.BankRefreshConnectionParams{\n\tBody: didit.BankRefreshRequest{\n\t\tWait: didit.Bool(true),\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;

            import me.didit.types.BankRefreshConnectionParams;

            import me.didit.types.BankRefreshRequest;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.bank().refreshConnection("11111111-2222-3333-4444-555555555555",
            BankRefreshConnectionParams.builder()
                    .wait_(true)
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: >-
            <?php


            require 'vendor/autoload.php';


            use Didit\DiditClient;


            // Reads DIDIT_API_KEY.

            $didit = new DiditClient();


            $result =
            $didit->bank->refreshConnection('11111111-2222-3333-4444-555555555555',
            [
                'wait' => true,
            ]);

            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.bank.refresh_connection(
              "11111111-2222-3333-4444-555555555555",
              wait: true
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await
            client.Bank.RefreshConnectionAsync("11111111-2222-3333-4444-555555555555",
            new BankRefreshRequest

            {
                Wait = true,
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        您为单次操作选择的可选重试安全密钥，最长 255 个字符（可使用
        UUID）。使用相同密钥、endpoint、查询参数和请求体重复发送的请求，会返回第一次的响应，状态码和响应体均相同，且不会再次运行或计费。同一密钥若用于其他
        endpoint、查询参数或请求体，将返回 `409` `idempotency_key_reused`；若第一个请求仍在处理中，则返回
        `409` `idempotency_key_in_progress` 及 `Retry-After`。失败的请求（任何 `4xx` 或
        `5xx`）不会被存储，因此您可以使用相同密钥再次发送。无论您使用 API 密钥还是访问 token
        调用，密钥都归属于您的应用。请参阅[重试与幂等性](/zh/integration/api-errors#重试与幂等性)。
      schema:
        type: string
        minLength: 1
        maxLength: 255
  schemas:
    BankRefreshRequest:
      type: object
      description: 刷新的可选请求体。
      properties:
        wait:
          type: boolean
          default: false
          description: >-
            `true` 会将调用最多挂起 25 秒，并以 `200`
            响应已完成的同步结果，因此一次请求即可返回最新数据。若银行在此时间内未响应，调用将返回 `202`：请使用 `sync_id` 通过
            `get_sync_run` 读取同步结果，或订阅 `bank.sync.completed`。仅当同步存储了变更时，才会发送
            `bank.data.updated`。请求头 `Prefer: wait=<seconds>`（最多 25）效果相同。
    BankSyncCompleted:
      allOf:
        - $ref: '#/components/schemas/BankSyncRun'
        - type: object
          properties:
            outcome:
              type: string
              enum:
                - succeeded
                - partial
                - failed
              description: 同步的结束方式。
            balances_changed:
              type: boolean
              description: 是否有任何余额发生变化。
          required:
            - outcome
            - balances_changed
      description: >-
        由带 `wait` 的刷新返回的已完成同步：同步运行记录，包含其 `outcome`、`results` 中的各账户数量以及
        `balances_changed`。
    BankRefreshAccepted:
      type: object
      description: 刷新请求已被接受。同步运行期间再次调用会返回相同的 `sync_id`。
      properties:
        sync_id:
          type: string
          description: 已排队的同步，或正在运行的同步。
          format: uuid
        status:
          type: string
          enum:
            - queued
            - running
        next_refresh_at:
          type: string
          description: 可以最早再次请求刷新的时间。仅在预算用尽时有值，否则为 `null`。
          format: date-time
          nullable: true
      required:
        - sync_id
        - status
        - next_refresh_at
    BankDataError:
      type: object
      description: 所有银行数据操作的错误响应体。每个字段始终存在。
      properties:
        code:
          type: string
          enum:
            - ongoing_access_not_available
            - segment_not_available
            - window_not_available
            - history_window_ambiguous
            - redirect_url_not_registered
            - link_origin_not_allowed
            - bank_data_access_denied
            - connection_not_active
            - consent_expired
            - renewal_not_needed
            - renewal_window_expired
            - access_removed
            - refresh_limit_reached
            - cursor_expired
            - page_expired
            - invalid_cursor
            - page_token_mismatch
            - contract_rate_missing
            - insufficient_credits
            - invalid_request
            - not_found
            - internal_error
          description: 机器可读的错误代码。请据此分支处理，切勿依据 `message`。
        message:
          type: string
          description: 面向开发者的通俗说明。措辞可能变化，请勿解析。
        request_id:
          type: string
          description: 本次请求的标识符。联系支持团队时请提供此标识符。
        field:
          type: string
          description: 需要更正的请求字段（如果错误与某个字段有关）。否则为 `null`。
          nullable: true
        next_action:
          type: string
          enum:
            - retry_later
            - renew_connection
            - create_link
            - restart_from_cursor
            - restart_read
            - top_up_balance
            - enable_bank_data_access
            - contact_support
            - null
          description: 下一步应执行的操作，便于客户端无需猜测即可执行。没有标准的下一步时为 `null`。
          nullable: true
        retry_after:
          type: integer
          description: 重试前需等待的秒数。仅在触发速率限制和出现临时错误时设置，否则为 `null`。
          nullable: true
      required:
        - code
        - message
        - request_id
        - field
        - next_action
        - retry_after
      example:
        code: ongoing_access_not_available
        message: >-
          This bank cannot keep access open. Use access one_time or choose
          another bank.
        request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
        field: institution_id
        next_action: create_link
        retry_after: null
    BankRefreshLimitError:
      allOf:
        - $ref: '#/components/schemas/BankDataError'
        - type: object
          properties:
            sync:
              type: object
              description: 连接当前的同步限制。
              properties:
                live_syncs_left_today:
                  type: integer
                  nullable: true
                  minimum: 0
                budgets:
                  type: array
                  items:
                    $ref: '#/components/schemas/BankSyncBudget'
              required:
                - live_syncs_left_today
                - budgets
          required:
            - sync
      description: 刷新限制错误，附带该连接的 `sync` 限制。`Retry-After` 表示额度重置前的秒数，范围为 1 到 86400。
    BankSyncRun:
      type: object
      description: 连接的一次同步。仅列出初始同步、定时同步和请求同步。
      properties:
        id:
          type: string
          format: uuid
        connection_id:
          type: string
          format: uuid
        trigger:
          type: string
          enum:
            - initial
            - scheduled
            - requested
        status:
          type: string
          enum:
            - queued
            - running
            - succeeded
            - partial
            - failed
        started_at:
          type: string
          format: date-time
          nullable: true
        finished_at:
          type: string
          format: date-time
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/BankSyncRunResult'
          description: 本次运行按账户和资源分别执行了什么。
        error:
          type: object
          nullable: true
          description: 整个运行失败的原因。未失败时为 `null`。单个账户和资源的错误见 `results`。
          properties:
            code:
              type: string
            message:
              type: string
            at:
              type: string
              format: date-time
          required:
            - code
            - message
            - at
      required:
        - id
        - connection_id
        - trigger
        - status
        - started_at
        - finished_at
        - results
        - error
    BankSyncBudget:
      type: object
      description: 银行对用户不在场时获取数据所设限制中的一个额度分段。
      properties:
        scope:
          type: string
          enum:
            - connection
            - account
          description: 银行以什么为依据计算预算消耗。
        resource:
          type: string
          enum:
            - all
            - accounts
            - balances
            - transactions
        account_id:
          type: string
          description: 当 `scope` 为 `account` 时的账户。
          format: uuid
          nullable: true
        limit:
          type: integer
          description: 按银行定义，Didit 在用户不在场的情况下每天最多可从银行获取数据的次数。这是银行设定的上限，而非承诺值。
        remaining:
          type: integer
          description: 当前时间窗口内剩余的手动刷新次数。自动同步保留的读取次数已预先扣除，且自动同步从不占用当天最后两次读取，因此始终保留两次按需刷新的机会。
        resets_at:
          type: string
          description: 时间窗口重置的时间。
          format: date-time
      required:
        - scope
        - resource
        - limit
        - remaining
        - resets_at
    BankSyncRunResult:
      type: object
      properties:
        account_id:
          type: string
          description: 对于整个连接的结果为 `null`。
          format: uuid
          nullable: true
        resource:
          type: string
          enum:
            - accounts
            - balances
            - transactions
        outcome:
          type: string
          enum:
            - succeeded
            - failed
            - skipped
        added:
          type: integer
        modified:
          type: integer
        removed:
          type: integer
        error:
          allOf:
            - $ref: '#/components/schemas/BankSyncError'
          nullable: true
          description: 当 `outcome` 为 `failed` 时必填。
      required:
        - account_id
        - resource
        - outcome
        - added
        - modified
        - removed
        - error
    BankSyncError:
      type: object
      description: 同步失败的原因。
      properties:
        code:
          type: string
          description: Didit 错误代码。
        message:
          type: string
          description: 通俗说明。
        at:
          type: string
          description: 事件发生的时间。在单个账户的结果中为 `null`。
          format: date-time
          nullable: true
      required:
        - code
        - message
        - at
  responses:
    Unauthorized:
      description: 未授权
      content:
        application/json:
          examples:
            Invalid API Key:
              summary: API 密钥无效
              value:
                detail: Invalid API Key.
    BankDataAccessDenied:
      description: >-
        API 密钥不具有银行数据权限（`bank-data`），或者，对于生产环境应用中的原始银行数据，应用设置“Bank data in the
        API”已关闭。银行数据不属于完全访问权限：完全访问权限的密钥、仅限其他资源的密钥，以及未使用 API
        密钥认证的请求（客户端凭证，访问原始数据时）均会被以此响应体拒绝，因此请创建密钥并显式授予该权限。此拒绝发生在任何查询之前，因此不能说明对象是否存在。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Bank data not allowed:
              summary: 不允许访问银行数据
              value:
                code: bank_data_access_denied
                message: >-
                  Bank data calls need an API key that carries the Bank data
                  permission.
                request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                field: null
                next_action: enable_bank_data_access
                retry_after: null
    BankDataInternalError:
      description: >-
        Didit 端出现了问题。`/v3/bank/` 下的任何意外错误都以银行错误格式返回，绝不返回 HTML 页面：请将 `request_id`
        提供给支持团队。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Internal error:
              summary: 意外错误
              value:
                code: internal_error
                message: >-
                  Something went wrong on our side. Quote the request_id to
                  support.
                request_id: 3f6a1c8e92b54d07a1e38c4b7f0d2e59
                field: null
                next_action: contact_support
                retry_after: null
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        您的应用 API 密钥，可在 Business Console 的开发者 -> API
        密钥中获取。主密钥拥有完全访问权限。命名密钥可以设置范围：可按资源设置无权限、只读或读写，可限定为部分工作流或已批准的会话，可限定为一组 IP
        地址，并可设置过期日期。401 表示密钥错误、已被撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或执行该操作，或请求来自其 IP
        列表之外的地址；会话相关路由返回 404，表示该会话不在密钥的工作流或状态范围内。没有媒体访问权限的密钥会将图片、视频和 PDF 的 URL
        返回为 null；没有会话写入权限的密钥会将会话链接和令牌返回为 null。请参阅
        https://docs.didit.me/console/api-keys。

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.