> ## 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 の「Refresh a Bank Connection」エンドポイントは、今すぐ同期するリクエストを受け付け、`202` と `sync_id` を返します。
`"wait": true` を送信すると、最大25秒間待機し、同期が完了した結果を1回の呼び出しで取得できます。追加料金はかかりません。
銀行は無人でのアクセスを制限しているため、呼び出しは `429 refresh_limit_reached` で応答する場合があり、その際は `Retry-After` が返されます。
[オンデマンドで銀行データを更新する](https://docs.didit.me/ja/use-cases/refresh-bank-data-on-demand.md)を参照してください。


## OpenAPI

````yaml ja/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: >-
      Bank
      Link、接続、アカウント、残高、取引、金融機関、カバレッジ。銀行データはサンドボックスアプリケーションで利用できます。本番アプリケーションの呼び出しは、本番アクセスが発表されるまで
      `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` を返し、予期しないエラーは `request_id` を伴う `500 internal_error`
      を返します。銀行データが利用できない場合、すべての操作はプラットフォームの標準 `404` を返します。これは未知のルートの場合とまったく同じです。
paths:
  /v3/bank/connections/{id}/refresh/:
    post:
      tags:
        - Bank Data
      summary: 銀行接続を更新する
      description: >-
        今すぐ同期します。銀行に問い合わせて、いつでも新しいデータを読み取ります。`202` と `sync_id`
        を返します。同期がすでに実行中の場合は、2つ目のジョブは作られず、同じ `sync_id` が返されます。リクエストボディに `"wait":
        true` を指定するか、ヘッダー `Prefer:
        wait=<seconds>`(最大25)を指定すると、呼び出しは最大25秒間待機し、完了した同期結果(`outcome`、アカウントごとの件数、`balances_changed`)を含む
        `200` を返します。これにより、1回のリクエストで最新のデータを取得できます。その時間内に銀行から応答がない場合は `202`
        を返します。その場合は、`sync_id` を指定して `get_sync_run`
        で同期を取得するか、`bank.sync.completed` を購読してください。`bank.data.updated`
        は、同期で変更が保存された場合にのみ送信されます。


        ライブ同期は、自動同期と同様に接続の月額料金に含まれるため、追加料金は発生しません。唯一の制限は銀行側の上限です。銀行は、利用者が不在の状態での読み取りを制限しており、たとえば1日4回までです(サンドボックスのDidit
        Test
        Bankも同様です)。その日の自動同期(`sync.frequency_per_day`)が先に確保され、残りをライブ同期に使えます。`sync.budgets`
        で残りの上限を、`sync.live_syncs_left_today`
        で本日残りのライブ同期の回数を確認できます。自動スケジュールは1日の最後の2回の読み取りを使わないため、ライブ同期は常に2回残ります。上限に達すると、呼び出しは
        `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>` は、ボディの `wait: true` と同様に、呼び出しを最大25秒（上限は25秒）まで保持します。'
      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: >-
        1回の操作に対して任意で指定する、再試行の安全性を確保するためのキーです。255文字まで指定でき、UUIDも使用できます。同じキー、エンドポイント、クエリ、ボディで繰り返されたリクエストには、最初のレスポンスが同じステータスと同じボディで返され、2回目は実行も課金も行われません。同じキーを別のエンドポイント、クエリ、ボディで使うと
        `409` `idempotency_key_reused` が返されます。最初のリクエストがまだ処理中の場合は、`Retry-After`
        付きの `409` `idempotency_key_in_progress` が返されます。失敗したリクエスト（`4xx` または
        `5xx`）は保存されないため、同じキーで再送できます。キーは、APIキーとアクセストークンのどちらで呼び出す場合でも、お使いのアプリケーションに属します。詳しくは
        [再試行と冪等性](/ja/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`
            を返します。そのため、1回のリクエストで最新データを取得できます。その時間内に銀行から応答がない場合、呼び出しは `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: 更新が受け付けられました。同期の実行中に2回目の呼び出しを行うと、同じ`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: エラーが1つのフィールドに関するものである場合に修正すべきリクエストフィールド。それ以外の場合は`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: 接続の1回の同期。初回、定期、リクエストによる同期のみが一覧に表示されます。
      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: 本人不在での取得に対する銀行の上限の1つの区分。
      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が銀行からデータを取得できる1日あたりの回数。これは銀行が設定する上限であり、保証ではありません。
        remaining:
          type: integer
          description: >-
            現在のウィンドウで手動更新に使用できる残りの取得回数です。自動同期用に確保された取得回数はあらかじめ差し引かれており、自動同期が1日の最後の2回の取得を使用することはありません。そのため、オンデマンドの更新は常に2回分残ります。
        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ページではなく、必ず Bank
        のエラー形式で応答されます。サポートに問い合わせる際は `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 の Developers -> API keys
        から取得できます。プライマリーキーはすべてのアクセス権を持ちます。名前付きキーは範囲を制限できます。リソースごとに
        none、read、write
        を指定でき、一部のワークフローや承認済みセッションに限定できます。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.