> ## 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의 은행 연결 목록 조회 엔드포인트는 상태, 접근 권한, 은행, 국가, 자체 참조 값, 동의 종료일로 필터링한 연결 목록을 반환합니다.

Didit의 List Bank Connections endpoint는 상태, 액세스, 은행, 국가, 자체 참조 및 동의 만료일을 기준으로 필터링된 연결 목록을 반환합니다.
`consent_expires_before`를 사용하면 갱신이 필요한 동의를 찾을 수 있고, `end_user_reference`를 사용하면 한 클라이언트의 연결을 찾을 수 있습니다.
목록은 `cursor`를 사용해 페이지 단위로 나뉩니다.


## OpenAPI

````yaml ko/openapi-25.json GET /v3/bank/connections/
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`)이 있는 키가 필요합니다. 읽기에는 read, 무언가를 변경하는
      작업에는 write 권한이 필요합니다. 계정 확인은 예외입니다. 이 경우에는 은행 데이터 권한이 아니라 세션에 대한 write 액세스
      또는 전체 액세스가 필요합니다. 은행 데이터는 전체 액세스에 포함되지 않습니다. 전체 액세스 키는 거부되며, 해당 권한이 있는 키를
      생성할 때까지 호출은 `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/:
    get:
      tags:
        - Bank Data
      summary: 은행 연결 나열
      description: >-
        애플리케이션의 연결을 최신순으로 나열하며, 커서 기반 페이지네이션을 사용합니다. 모든 필터는 애플리케이션과 환경 안에서
        적용됩니다.


        뱅크 데이터 권한(`bank-data`)이 있는 API 키가 필요합니다. 이 작업에 대해서는 읽기 권한이어야 합니다. 전체 액세스
        키에는 이 권한이 포함되지 않으므로, 키를 생성할 때 명시적으로 부여해야 합니다. 그렇지 않으면 호출은 `403
        bank_data_access_denied`로 응답합니다.


        이 목록에서 `sync.budgets`에는 이미 존재하는 예산만 표시됩니다. 오늘의 예산은 `GET
        /v3/bank/connections/{id}/`로 확인합니다.
      operationId: listBankConnections
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - pending
              - active
              - renewal_required
              - paused
              - revoked
              - deleted
              - failed
          description: 이 상태의 연결만 해당합니다.
        - name: access
          in: query
          required: false
          schema:
            type: string
            enum:
              - one_time
              - ongoing
          description: 이 액세스 모드만 해당합니다.
        - name: institution_id
          in: query
          required: false
          schema:
            type: string
            maxLength: 64
          description: 이 은행만 해당합니다.
        - name: country
          in: query
          required: false
          schema:
            type: string
            pattern: ^[A-Z]{3}$
          description: 이 국가의 은행만 해당합니다.
        - name: vendor_data
          in: query
          required: false
          schema:
            type: string
            maxLength: 255
          description: 이 `vendor_data`를 가진 연결만 해당합니다.
        - name: end_user_reference
          in: query
          required: false
          schema:
            type: string
            maxLength: 255
          description: 이 `end_user.reference`를 가진 연결만 해당합니다.
        - name: consent_expires_before
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: 동의가 이 시간 이전에 종료되는 연결만 해당합니다. 예를 들어 갱신 링크를 보낼 때 사용합니다.
        - name: created_after
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: 이 시간 이후에 생성된 연결만 해당합니다.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 500
          description: 페이지 크기이며, 1~500 사이입니다. 기본값은 100입니다.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: 이전 페이지의 `next_cursor` 값인 불투명 커서입니다.
      responses:
        '200':
          description: 연결 페이지입니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankConnectionList'
              examples:
                Page:
                  summary: 연결 하나
                  value:
                    items:
                      - id: 5e1d2a70-3b94-4c1f-8a6e-d2f07b9c1e35
                        environment: live
                        access: ongoing
                        status: active
                        status_reason: null
                        institution:
                          id: es-banco-norte
                          name: Banco Norte
                          country: ESP
                          logo_url: https://static.example.com/banks/es-banco-norte.png
                        segment: business
                        data:
                          - accounts
                          - balances
                          - transactions
                        consent:
                          status: granted
                          version: 1
                          granted_at: '2026-11-21T12:04:11Z'
                          expires_at: '2027-05-20T12:04:11Z'
                          days_granted: 180
                          renewed_count: 0
                          scopes_requested:
                            - accounts
                            - balances
                            - transactions
                          scopes_granted:
                            - accounts
                            - balances
                            - transactions
                          accounts_granted:
                            - a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                            - c3d84e19-2a7b-4f60-b5e1-9a0c6d3f8e72
                          renewal_action: bank_auth
                          renew_by: '2027-05-20T12:04:11Z'
                          reconfirm_by: null
                          renewable_until: null
                          retain_until: null
                          ended_at: null
                          ended_by: null
                        sync:
                          status: ok
                          initial_status: succeeded
                          initial_complete: true
                          history_complete: true
                          last_synced_at: '2026-11-21T12:04:40Z'
                          next_sync_at: '2026-11-22T06:00:00Z'
                          budgets:
                            - scope: connection
                              resource: all
                              limit: 4
                              remaining: 3
                              resets_at: '2026-11-22T00:00:00Z'
                          last_error: null
                          frequency_per_day: 1
                          live_syncs_left_today: 3
                        accounts:
                          - id: a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                            name: Cuenta negocio
                            type: current
                            usage: business
                            currency: EUR
                            iban_last4: '1332'
                            status: open
                          - id: c3d84e19-2a7b-4f60-b5e1-9a0c6d3f8e72
                            name: Cuenta de ahorro
                            type: savings
                            usage: business
                            currency: EUR
                            iban_last4: '7708'
                            status: open
                        ownership:
                          compare: none
                          match: null
                          check_id: null
                          result: null
                        end_user:
                          reference: client-7731
                        manage_url: null
                        billing:
                          unit: connection_month
                          price_usd: '0.9000'
                          billed_through: '2026-11-30'
                        possible_duplicate_of: null
                        erasure: null
                        vendor_data: client-7731
                        created_at: '2026-11-21T12:03:02Z'
                        updated_at: '2026-11-21T12:04:40Z'
                    next_cursor: null
        '400':
          description: 파라미터가 잘못되었습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Invalid cursor:
                  summary: 잘못된 커서
                  value:
                    code: invalid_cursor
                    message: The cursor or page token is not valid.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: cursor
                    next_action: null
                    retry_after: null
                Invalid request:
                  summary: 잘못된 요청
                  value:
                    code: invalid_request
                    message: The request is not valid.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: limit
                    next_action: null
                    retry_after: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BankDataAccessDenied'
        '429':
          $ref: '#/components/responses/RateLimitedRead'
        '500':
          $ref: '#/components/responses/BankDataInternalError'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: >-
            curl
            'https://verification.didit.me/v3/bank/connections/?status=active&country=ESP&limit=50'
            \
              -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.list_connections()
            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.listConnections();
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Bank.ListConnections(ctx, didit.BankListConnectionsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: |-
            import me.didit.Didit;

            // Reads DIDIT_API_KEY.
            Didit client = new Didit();

            var result = client.bank().listConnections();
            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->listConnections();
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

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

            result = didit.bank.list_connections
            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.ListConnectionsAsync();
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    BankConnectionList:
      type: object
      description: 연결 페이지입니다.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BankConnection'
        next_cursor:
          type: string
          description: 다음 페이지를 조회하려면 `cursor`로 전달합니다. 마지막 페이지에서는 `null`입니다.
          nullable: true
      required:
        - items
        - next_cursor
    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: 이 요청의 ID입니다. 지원팀에 문의할 때 이 값을 알려 주십시오.
        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
    BankConnection:
      type: object
      description: >-
        애플리케이션이 한 은행의 데이터를 읽을 수 있도록 사용자가 부여한 권한입니다. 갱신하면 연결 ID와 모든 계정 ID가 유지됩니다.
        삭제된 연결은 `id`, `status`, `status_reason`, `created_at`, `erasure`만 응답하며,
        다른 모든 필드는 없고 은행, 사용자 또는 계정 데이터는 남지 않습니다.
      properties:
        id:
          type: string
          description: 연결의 ID입니다.
          format: uuid
        environment:
          type: string
          enum:
            - live
            - sandbox
        access:
          type: string
          enum:
            - one_time
            - ongoing
        status:
          type: string
          enum:
            - pending
            - active
            - renewal_required
            - paused
            - revoked
            - deleted
            - failed
          description: >-
            `pending`: 첫 동기화가 진행 중입니다. `active`: 동의가 유효합니다. `renewal_required`:
            동의가 종료되었거나 은행이 최종 사용자에게 다시 로그인하도록 요구합니다. 데이터는 마지막 동기화 상태로 읽을 수 있으며
            요금은 부과되지 않습니다. `paused`: 해당 월의 잔액이 부족합니다. `revoked`: 최종 사용자, 은행 또는
            귀사에 의해 접근이 중단되었습니다. `deleted`: `id`, `status`, `status_reason`,
            `created_at`, `erasure`만 남습니다. `failed`: 첫 동기화가 한 번도 성공하지 못했습니다.
        status_reason:
          type: string
          enum:
            - collection_complete
            - consent_expired
            - consent_lapsed
            - bank_requires_sign_in
            - revoked_by_end_user
            - revoked_by_bank
            - revoked_by_customer
            - insufficient_balance
            - paused_by_customer
            - first_sync_failed
            - deleted_by_customer
            - retention_elapsed
            - application_deleted
            - null
          description: >-
            연결이 이 상태에 있는 이유입니다. `paused_by_customer`는 예약되어 있습니다. `deleted` 연결의
            경우 `deleted_by_customer`, `consent_lapsed`, `retention_elapsed` 또는
            `application_deleted`입니다.
          nullable: true
        institution:
          $ref: '#/components/schemas/BankInstitutionSummary'
        segment:
          type: string
          enum:
            - personal
            - business
            - null
          nullable: true
        data:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
          description: 사용자가 수락한 스코프입니다.
        consent:
          $ref: '#/components/schemas/BankConnectionConsent'
        sync:
          $ref: '#/components/schemas/BankConnectionSync'
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/BankConnectionAccountSummary'
          description: 연결에 포함된 모든 계좌의 요약입니다. 계좌의 전체 정보는 `get_account`로 조회합니다.
        ownership:
          $ref: '#/components/schemas/BankConnectionOwnership'
        end_user:
          type: object
          properties:
            reference:
              type: string
              description: 해당 개인 또는 회사에 대한 귀사의 ID입니다.
              nullable: true
          required:
            - reference
        manage_url:
          type: string
          description: 사용자 본인의 액세스 페이지입니다. 액세스 페이지를 사용할 수 있을 때까지 `null`입니다.
          nullable: true
          format: uri
        billing:
          $ref: '#/components/schemas/BankConnectionBilling'
        possible_duplicate_of:
          type: string
          description: >-
            이 연결이 다른 활성 연결과 중복될 수 있지만 `end_user.reference`로 확실한 일치를 판단할 수 없는 경우
            설정됩니다.
          format: uuid
          nullable: true
        erasure:
          allOf:
            - $ref: '#/components/schemas/BankConnectionErasure'
          nullable: true
          description: '`delete_connection` 이후에 설정되며, 그 외에는 `null`입니다.'
        vendor_data:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - status
        - status_reason
        - created_at
        - erasure
    RateLimitBudgetError:
      type: object
      description: >-
        속도 제한 미들웨어 예산 거부 응답에만 반환됩니다. 멱등성 충돌과 엔드포인트별 상한을 포함한 다른 429 오류는 이 메타데이터
        필드를 보장하지 않습니다.
      required:
        - detail
        - reference
        - limit
        - remaining
        - reset
        - window_seconds
      properties:
        detail:
          type: string
          description: 기존의 사람이 읽을 수 있는 예산 거부 메시지입니다.
        reference:
          type: string
          pattern: ^RL-[0-9a-f]{32}$
          description: 불투명한 지원 참조 번호입니다. RL- 뒤에 소문자 UUID 16진수 문자 32자가 이어집니다.
        limit:
          type: integer
          description: 초과된 범위의 예산입니다. X-RateLimit-Limit 값과 같습니다.
        remaining:
          type: integer
          minimum: 0
          description: 남은 예산이며 0 미만으로 내려가지 않습니다. X-RateLimit-Remaining과 같습니다.
        reset:
          type: integer
          format: int64
          description: Unix 초 단위의 윈도우 재설정 시간이며 X-RateLimit-Reset 값과 같습니다.
        window_seconds:
          type: integer
          description: 고정 윈도우 기간(초 단위)이며, 남은 대기 시간이 아닙니다. 재시도하기 전에 Retry-After 값을 준수해야 합니다.
      example:
        detail: >-
          Write request rate limit exceeded. You can make up to 300 requests per
          minute.
        reference: RL-00000000000040008000000000000001
        limit: 300
        remaining: 0
        reset: 1794358860
        window_seconds: 60
    BankInstitutionSummary:
      type: object
      description: 연결 또는 링크의 대상 은행입니다.
      properties:
        id:
          type: string
          description: 은행을 식별하는 Didit 식별자이며 안정적인 슬러그입니다. `institution_id`로 사용하세요.
          example: es-banco-norte
        name:
          type: string
          description: 은행 이름입니다.
          example: Banco Norte
        country:
          type: string
          description: 은행의 국가이며 ISO 3166-1 alpha-3 형식입니다.
          pattern: ^[A-Z]{3}$
          example: ESP
        logo_url:
          type: string
          description: 은행 로고 또는 `null`입니다.
          nullable: true
          format: uri
      required:
        - id
        - name
        - country
        - logo_url
    BankConnectionConsent:
      type: object
      description: 이 연결에 대한 사용자의 동의입니다.
      properties:
        status:
          type: string
          enum:
            - granted
            - expired
            - revocation_pending
            - revoked
            - revocation_failed
          description: >-
            은행이 동의 종료를 확인할 때까지는 `revocation_pending`이며, 그 후 `revoked`가 됩니다.
            `revocation_failed`는 자동으로 재시도됩니다. 철회가 요청되는 즉시 은행 데이터 조회가 중단됩니다.
        version:
          type: integer
          description: 동의의 버전입니다. 갱신하면 같은 연결에서 다음 버전이 생성됩니다.
        granted_at:
          type: string
          format: date-time
          nullable: true
        expires_at:
          type: string
          description: 은행의 동의가 종료되는 시점입니다. 은행이 `consent_days`를 넘지 않는 범위에서 설정합니다.
          format: date-time
          nullable: true
        days_granted:
          type: integer
          description: 은행이 부여한 동의 기간을 일 단위로 나타냅니다.
          nullable: true
        renewed_count:
          type: integer
          description: 동의가 갱신된 횟수입니다.
        scopes_requested:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
        scopes_granted:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
        accounts_granted:
          type: array
          items:
            type: string
            format: uuid
          description: 사용자가 공유하는 계정의 ID입니다.
        renewal_action:
          type: string
          enum:
            - reconfirm
            - bank_auth
            - null
          description: >-
            갱신 방식입니다. `reconfirm`은 은행과 해당 국가의 규정이 허용하는 경우에 한해, 은행 로그인 없이 사용자가
            Didit 화면에서 본인을 확인하는 방식입니다. `bank_auth`는 은행 로그인입니다.
          nullable: true
        renew_by:
          type: string
          description: 동의의 종료 시점입니다. 공백 없이 이어지도록 그 전에 갱신하십시오.
          format: date-time
          nullable: true
        reconfirm_by:
          type: string
          description: '`renewal_action`이 `reconfirm`일 때 설정됩니다. 재확인해야 하는 마지막 시점입니다.'
          format: date-time
          nullable: true
        renewable_until:
          type: string
          description: >-
            동의가 종료된 후 같은 연결을 다시 활성화할 수 있는 마지막 시점입니다. 이 시점 이후에는 사용자가 다시 연결해야 합니다.
            `retain_until`과 같은 값입니다.
          format: date-time
          nullable: true
        retain_until:
          type: string
          description: 접근이 종료되면 설정됩니다. 저장된 데이터를 계속 읽을 수 있는 기간이며, 애플리케이션의 보존 설정에 따라 정해집니다.
          format: date-time
          nullable: true
        ended_at:
          type: string
          format: date-time
          nullable: true
        ended_by:
          type: string
          enum:
            - end_user
            - bank
            - customer
            - unknown
            - null
          description: 접근 권한을 종료한 주체이며, 증거에 따라 설정됩니다. 은행과 동기화 모두 알 수 없는 경우 `unknown`입니다.
          nullable: true
      required:
        - status
        - version
        - granted_at
        - expires_at
        - days_granted
        - renewed_count
        - scopes_requested
        - scopes_granted
        - accounts_granted
        - renewal_action
        - renew_by
        - reconfirm_by
        - renewable_until
        - retain_until
        - ended_at
        - ended_by
    BankConnectionSync:
      type: object
      description: 연결의 동기화 상태입니다.
      properties:
        status:
          type: string
          enum:
            - pending
            - ok
            - failing
          description: >-
            24시간 동안 시도가 실패하면 `failing`이 됩니다. 실패한 시도는 점진적 간격으로 재시도됩니다. 은행이 최종
            사용자에게 다시 로그인하도록 요청하면 대신 연결이 `renewal_required`가 됩니다.
        initial_status:
          type: string
          enum:
            - pending
            - succeeded
            - partial
            - failed
          description: >-
            첫 동기화의 결과입니다. `succeeded` 또는 `partial`이면 연결이 `active`가 되고, 성공한 계좌가
            하나도 없으면 `failed`가 됩니다.
        initial_complete:
          type: boolean
          description: >-
            `initial_status`가 `succeeded`인 경우에만 `true`입니다. 이때 계정, 잔액, 최근 거래를 조회할
            수 있습니다.
        history_complete:
          type: boolean
          description: >-
            사유와 관계없이 이력 백필이 종료되면 `true`입니다. 가져오지 못한 범위는 각 계정의
            `history_coverage.missing_ranges`에 나타납니다.
        last_synced_at:
          type: string
          description: 사용자가 마지막으로 조회한 시점이 아니라, 은행에서 데이터를 마지막으로 가져온 시점입니다.
          format: date-time
          nullable: true
        next_sync_at:
          type: string
          description: >-
            다음 자동 동기화가 예정된 시점입니다. 자동 동기화는 은행에 따라 하루 1회에서 4회 사이로
            실행됩니다(`frequency_per_day` 참조).
          format: date-time
          nullable: true
        budgets:
          type: array
          items:
            $ref: '#/components/schemas/BankSyncBudget'
          description: 사용자가 없는 상태에서 이루어지는 조회에 대한 은행의 한도입니다.
        last_error:
          allOf:
            - $ref: '#/components/schemas/BankSyncError'
          nullable: true
          description: 마지막 동기화 오류이며, 없으면 `null`입니다.
        frequency_per_day:
          type: integer
          minimum: 1
          maximum: 4
          description: >-
            이 연결에 대해 자동 동기화가 하루에 실행되는 횟수이며, 은행에 따라 1회에서 4회입니다. 은행이 사용자 없이 더 많은
            읽기를 허용하는 경우에도 실시간 동기화를 위해 하루 최소 2회는 항상 남겨집니다.
        live_syncs_left_today:
          type: integer
          minimum: 0
          description: >-
            오늘 은행 한도 내에서 남은 실시간 동기화(`refresh_connection`) 횟수입니다. 가장 엄격한 예산의
            `remaining` 값입니다. 은행이 한도를 설정하지 않는 경우 `null`입니다. 실시간 동기화는 월 요금에
            포함됩니다.
          nullable: true
      required:
        - status
        - initial_status
        - initial_complete
        - history_complete
        - last_synced_at
        - next_sync_at
        - budgets
        - last_error
        - frequency_per_day
        - live_syncs_left_today
    BankConnectionAccountSummary:
      type: object
      description: 연결 내 계정의 간략한 형식입니다.
      properties:
        id:
          type: string
          description: 계정 ID입니다. 갱신을 포함하여 연결의 수명 동안 안정적으로 유지됩니다.
          format: uuid
        name:
          type: string
          nullable: true
        type:
          type: string
          enum:
            - current
            - savings
            - card
            - loan
            - investment
            - other
        usage:
          type: string
          enum:
            - personal
            - business
            - unknown
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: ISO 4217 통화 코드입니다.
        iban_last4:
          type: string
          description: 계좌에 IBAN이 있는 경우 IBAN의 마지막 네 자리입니다.
          nullable: true
        status:
          type: string
          enum:
            - open
            - closed
            - access_removed
      required:
        - id
        - name
        - type
        - usage
        - currency
        - iban_last4
        - status
    BankConnectionOwnership:
      type: object
      description: 계좌 명의인을 개인 또는 기업과 비교하는 선택 사항입니다.
      properties:
        compare:
          type: string
          enum:
            - none
            - person
            - business
        match:
          type: string
          enum:
            - any_holder
            - all_holders
            - null
          nullable: true
        check_id:
          type: string
          description: 비교를 요청한 경우 소유권 결과의 ID입니다.
          format: uuid
          nullable: true
        result:
          type: string
          enum:
            - match
            - close_match
            - no_match
            - unknown
            - null
          description: >-
            판정 결과입니다. 누락된 명의자 증거로 결과가 달라질 수 있는 경우와 은행이 명의자를 공유하지 않는 경우에는
            `unknown`입니다.
          nullable: true
      required:
        - compare
        - match
        - check_id
        - result
    BankConnectionBilling:
      type: object
      description: 이 연동의 비용입니다. 샌드박스는 어떤 경우에도 요금이 부과되지 않습니다.
      properties:
        unit:
          type: string
          description: 청구 단위입니다. 지속적인 접근은 `connection_month`, 그 외에는 `one_time`입니다.
          enum:
            - connection_month
            - one_time
        price_usd:
          type: string
          description: >-
            오늘 기준으로 귀사의 애플리케이션과 국가에 적용되는 월별 미터 가격입니다. 애플리케이션과 국가에 따라 USD로 표시되며,
            소수점 4자리의 십진수 문자열입니다. 허용된 모든 범위에서 해당 월에 적어도 하나의 계정에 대한 데이터가 게시된 경우에만
            해당 월의 연결에 요금이 부과됩니다. 일회성 연결과 샌드박스에서는 `null`입니다. 지속적인 접근은 활성 연결당 월별로
            과금되며, 현재 가격은 요금 페이지(https://docs.didit.me/getting-started/pricing)에
            있습니다. 예시의 금액은 설명용이며, 국가별 가격은 요금 페이지에 표시됩니다.
          pattern: ^-?\d+(\.\d+)?$
          nullable: true
        billed_through:
          type: string
          description: 이미 정산된 가장 최근 월말
          format: date
          nullable: true
      required:
        - unit
        - price_usd
        - billed_through
    BankConnectionErasure:
      type: object
      description: 요청한 삭제의 진행 상황입니다.
      properties:
        status:
          type: string
          enum:
            - pending
            - erased
            - failed
          description: >-
            `pending` while deletion runs, `erased` when no stored copy and no
            access at the bank remain, `failed` when it could not be confirmed
            within 24 hours. A failed deletion keeps the connection's data
            closed, is retried, and Didit is alerted.
        requested_at:
          type: string
          format: date-time
        erased_at:
          type: string
          format: date-time
          nullable: true
          description: 삭제가 완료된 시점입니다. `status`가 `erased`가 되기 전까지는 `null`입니다.
      required:
        - status
        - requested_at
        - erased_at
    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
    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
    RateLimitedRead:
      description: 미들웨어 읽기 예산을 초과했습니다. 재시도하기 전에 Retry-After를 따르세요.
      headers:
        Retry-After:
          $ref: '#/components/headers/BudgetRetryAfter'
        X-RateLimit-Scope:
          $ref: '#/components/headers/BudgetXRateLimitScope'
        X-RateLimit-Limit:
          $ref: '#/components/headers/BudgetXRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/BudgetXRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/BudgetXRateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitBudgetError'
          example:
            detail: >-
              GET request rate limit exceeded. You can make up to 600 requests
              per minute.
            reference: RL-00000000000040008000000000000001
            limit: 600
            remaining: 0
            reset: 1794358860
            window_seconds: 60
    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
  headers:
    BudgetRetryAfter:
      description: 다음 윈도우까지 기다려야 하는 시간(초)을 올림한 값입니다. 미들웨어 예산 거부 응답에 포함됩니다.
      schema:
        type: integer
    BudgetXRateLimitScope:
      description: 예산을 초과한 범위입니다. 미들웨어 예산 거부 응답에 포함됩니다.
      schema:
        type: string
    BudgetXRateLimitLimit:
      description: 초과된 범위의 예산입니다. 본문 한도와 같습니다. 미들웨어 예산 거부 응답에 포함됩니다.
      schema:
        type: integer
    BudgetXRateLimitRemaining:
      description: 남은 예산이며 0 미만으로 내려가지 않습니다. 본문의 remaining과 같습니다. 미들웨어 예산 거부 응답에만 있습니다.
      schema:
        type: integer
    BudgetXRateLimitReset:
      description: Unix 초 단위의 재설정 시간이며 본문의 reset 값과 같습니다. 미들웨어 예산 거부 응답에 포함됩니다.
      schema:
        type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        귀사 애플리케이션의 API 키입니다. Business Console의 Developers -> API keys에서 확인할 수
        있습니다. 기본 키는 모든 권한을 가집니다. 명명된 키는 범위를 지정할 수 있습니다. 리소스별로 권한 없음, 읽기 또는 쓰기를
        설정할 수 있고, 일부 워크플로나 승인된 세션으로 제한할 수 있으며, 허용된 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.