> ## 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의 Sync Transactions 엔드포인트는 커서 이후 연결된 은행 거래에서 추가, 수정, 삭제된 내역을 반환합니다.

Didit의 Sync Transactions endpoint는 커서 이후 연결된 계좌의 거래 중 변경된 내용을 반환합니다: `added`, `modified`, `removed`.
커서를 비워 두면 `reset: true`와 함께 모든 거래가 반환됩니다.
`has_more: false`가 포함된 응답을 받은 후에만 `next_cursor`를 저장해야 합니다.
[회계를 위한 지속적인 은행 거래 피드](https://docs.didit.me/ko/use-cases/bank-data-for-accounting.md)를 참조하십시오.


## OpenAPI

````yaml ko/openapi-25.json GET /v3/bank/connections/{id}/transactions/sync/
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/{id}/transactions/sync/:
    get:
      tags:
        - Bank Data
      summary: 거래 동기화(변경 피드)
      description: >-
        `cursor` 이후 연결의 거래에서 변경된 내용을 반환합니다. 여기에는 `added`, `modified`,
        `removed`(`reason` 포함)가 포함되며, 연결의 모든 계정을 대상으로 합니다. 빈 cursor를 보내면 현재의 모든
        거래를 `added`로 반환하고 `reset: true`를 설정합니다. 이때는 기존 복사본에 추가하지 말고 이 결과로
        교체하십시오.


        첫 번째 읽기는 실제 스냅샷입니다. 첫 번째 읽기(cursor 없음, 또는 `reset` 이후의 읽기)는 읽기가 시작된 시점에
        연결에 있던 모든 거래를 각각 정확히 한 번씩 현재 상태 그대로 `added`로 반환합니다. 페이지를 넘기는 동안 동기화가
        실행되더라도 마찬가지입니다. 페이지를 넘기는 동안 발생한 변경 사항은 `next_cursor`로 시작하는 다음 읽기에서
        전달됩니다. 이미 받은 거래는 `modified`로 다시 오고, 새로운 거래는 `added`로 옵니다. `modified`는
        `id` 기준의 업서트로 적용하고, 가지고 있지 않은 `removed`의 id는 무시하십시오. 하나의 읽기에 속한 모든 페이지는
        같은 시점을 반영합니다. `has_more`가 `true`인 동안에는 `page_token`으로 계속 페이지를 요청하고,
        `has_more: false`인 응답을 받은 후에만 `next_cursor`를 저장하십시오. 페이지 요청 도중 실패하면 저장해
        둔 cursor부터 다시 시작하십시오.


        변경 로그는 90일 동안 재생할 수 있습니다. 그보다 오래된 cursor는 `410 cursor_expired`와
        `bootstrap: true`로 응답합니다. 이 경우 빈 cursor로 다시 시작하십시오. 연결이 존재하는 동안 저장된 이력은
        만료되지 않습니다. 확정된 대기 거래는 `added`에 나타나고, 대기 상태였던 거래는 `reason:
        pending_booked`와 함께 `removed`에 나타납니다. webhook `bank.data.updated`는 호출
        시점을 알려 줍니다.


        은행 데이터 권한(`bank-data`)이 있는 API 키가 필요하며, 이 작업에는 읽기 권한이 적용됩니다. 전체 권한 키에는 이
        권한이 포함되지 않으므로, 키를 생성할 때 명시적으로 부여해야 합니다. 그렇지 않으면 호출은 `403
        bank_data_access_denied`로 응답합니다. 샌드박스 애플리케이션은 API 키만으로 Test Bank 데이터를
        읽습니다. API 키 없이(클라이언트 자격 증명) 보낸 요청은 원시 데이터에 대해 동일한 `403`으로 거부됩니다.
      operationId: syncBankTransactions
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: 연결 ID입니다.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: 저장해 둔 `next_cursor`입니다. 비어 있거나 생략하면 처음부터 시작합니다.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 500
          description: 페이지 크기이며, 1~500 사이입니다. 기본값은 100입니다.
        - name: page_token
          in: query
          required: false
          schema:
            type: string
          description: '`has_more`가 `true`인 동안 같은 읽기를 계속합니다.'
      responses:
        '200':
          description: 변경 사항 페이지입니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransactionChanges'
              examples:
                Changes:
                  summary: 보류 거래가 확정되었고 새 거래가 추가되었습니다.
                  value:
                    added:
                      - id: 8f2b6d41-9c3a-4e57-b0d8-1a7e5c4f2963
                        account_id: a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                        status: booked
                        pending_id: null
                        reverses_id: null
                        booking_date: '2026-11-19'
                        value_date: '2026-11-20'
                        transaction_date: null
                        effective_date: '2026-11-19'
                        amount: '-1210.00'
                        currency: EUR
                        direction: debit
                        description: RECIBO SEGURIDAD SOCIAL
                        counterparty:
                          name: ENTIDAD PUBLICA DE EJEMPLO
                          iban: ES0000000000000000005766
                          bic: null
                        remittance:
                          unstructured:
                            - RECIBO SEGURIDAD SOCIAL 10/2026
                          structured: null
                          reference: '0028123456789'
                        bank_transaction_code: PMNT-RDDT-ESDD
                        bank_reference: '2026111900012345'
                        identity_quality: bank_reference
                        end_to_end_id: NOTPROVIDED
                        mandate_id: ES-SS-000123
                        creditor_id: ES00ZZZ00000000
                        merchant_category_code: null
                        exchange: null
                        balance_after: '18250.34'
                        category: taxes_and_social_security
                        first_seen_at: '2026-11-20T06:00:12Z'
                        updated_at: '2026-11-20T06:00:12Z'
                    modified: []
                    removed:
                      - id: e5b1f8a3-0d47-4c92-a6e0-7f3c2d9b1845
                        reason: pending_booked
                    has_more: false
                    next_page_token: null
                    next_cursor: cur_01HZX9K4M2W7B3T8
                    reset: false
                Bootstrap:
                  summary: 빈 커서에서 다시 읽기
                  value:
                    added:
                      - id: 8f2b6d41-9c3a-4e57-b0d8-1a7e5c4f2963
                        account_id: a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                        status: booked
                        pending_id: null
                        reverses_id: null
                        booking_date: '2026-11-19'
                        value_date: '2026-11-20'
                        transaction_date: null
                        effective_date: '2026-11-19'
                        amount: '-1210.00'
                        currency: EUR
                        direction: debit
                        description: RECIBO SEGURIDAD SOCIAL
                        counterparty:
                          name: ENTIDAD PUBLICA DE EJEMPLO
                          iban: ES0000000000000000005766
                          bic: null
                        remittance:
                          unstructured:
                            - RECIBO SEGURIDAD SOCIAL 10/2026
                          structured: null
                          reference: '0028123456789'
                        bank_transaction_code: PMNT-RDDT-ESDD
                        bank_reference: '2026111900012345'
                        identity_quality: bank_reference
                        end_to_end_id: NOTPROVIDED
                        mandate_id: ES-SS-000123
                        creditor_id: ES00ZZZ00000000
                        merchant_category_code: null
                        exchange: null
                        balance_after: '18250.34'
                        category: taxes_and_social_security
                        first_seen_at: '2026-11-20T06:00:12Z'
                        updated_at: '2026-11-20T06:00:12Z'
                      - id: 2c9e7a05-6b14-4d38-8f2a-b3d51e0c9a67
                        account_id: a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                        status: booked
                        pending_id: null
                        reverses_id: null
                        booking_date: '2026-11-18'
                        value_date: '2026-11-18'
                        transaction_date: null
                        effective_date: '2026-11-18'
                        amount: '3450.00'
                        currency: EUR
                        direction: credit
                        description: TRANSFERENCIA FACTURA 2026-0418
                        counterparty:
                          name: CLIENTE DE EJEMPLO SL
                          iban: ES0000000000000000007891
                          bic: null
                        remittance:
                          unstructured:
                            - FRA 2026-0418
                          structured: null
                          reference: null
                        bank_transaction_code: PMNT-RCDT-ESCT
                        bank_reference: '2026111800009876'
                        identity_quality: bank_reference
                        end_to_end_id: 2026-0418
                        mandate_id: null
                        creditor_id: null
                        merchant_category_code: null
                        exchange: null
                        balance_after: '19460.34'
                        category: income
                        first_seen_at: '2026-11-19T06:00:10Z'
                        updated_at: '2026-11-19T06:00:10Z'
                    modified: []
                    removed: []
                    has_more: false
                    next_page_token: null
                    next_cursor: cur_01HZX9K4M2W7B3T8
                    reset: true
          headers:
            Cache-Control:
              description: '`no-store`.'
              schema:
                type: string
        '400':
          description: 커서 또는 페이지 토큰이 유효하지 않거나 파라미터가 허용 범위를 벗어났습니다. `field`에 해당 항목이 표시됩니다.
          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
                Token for another read:
                  summary: 다른 조회를 위한 토큰
                  value:
                    code: page_token_mismatch
                    message: >-
                      The page token belongs to a different read. Restart with
                      the same filters.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: page_token
                    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'
        '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`).
          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
        '410':
          description: >-
            커서가 변경 로그를 보관하는 90일보다 오래되었거나 페이지 토큰이 만료되었습니다. `cursor_expired`인 경우
            본문에 `bootstrap: true`가 포함됩니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataCursorError'
              examples:
                Cursor expired:
                  summary: 빈 cursor부터 다시 시작
                  value:
                    code: cursor_expired
                    message: >-
                      The cursor is older than the change log. Read again from
                      an empty cursor.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: cursor
                    next_action: restart_from_cursor
                    retry_after: null
                    bootstrap: true
                Page expired:
                  summary: 마지막으로 저장된 커서부터 읽기를 다시 시작합니다
                  value:
                    code: page_expired
                    message: The page token expired. Restart the read.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: page_token
                    next_action: restart_read
                    retry_after: null
        '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/5e1d2a70-3b94-4c1f-8a6e-d2f07b9c1e35/transactions/sync/?cursor=cur_01HZX9K4M2W7B3T8'
            \
              -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.sync_transactions(
                "11111111-2222-3333-4444-555555555555",
            )
            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.syncTransactions("11111111-2222-3333-4444-555555555555");

            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Bank.SyncTransactions(ctx, \"11111111-2222-3333-4444-555555555555\", didit.BankSyncTransactionsParams{})\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().syncTransactions("11111111-2222-3333-4444-555555555555");

            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->syncTransactions('11111111-2222-3333-4444-555555555555');

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


            # Reads DIDIT_API_KEY.

            didit = Didit::Client.new


            result =
            didit.bank.sync_transactions("11111111-2222-3333-4444-555555555555")

            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.SyncTransactionsAsync("11111111-2222-3333-4444-555555555555");

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    BankTransactionChanges:
      type: object
      description: >-
        커서 이후 연결 거래 내역의 변경 사항입니다. 빈 커서를 사용하면 현재 모든 거래가 `added`로 반환됩니다. 한 번의 읽기에서
        가져온 모든 페이지는 동일한 스냅샷을 반영하며, 그 사이에 발생한 변경 사항은 다음 읽기에서 전달됩니다.
      properties:
        added:
          type: array
          items:
            $ref: '#/components/schemas/BankTransaction'
          description: >-
            추가할 거래입니다. 첫 번째 조회(커서가 없거나 `reset` 이후)에서는 조회가 시작될 때 연결에 있던 모든 거래가
            포함되며, 페이지를 넘기는 동안 동기화가 실행되더라도 각 거래는 정확히 한 번, 현재 상태로 담깁니다. 이후 조회에서는
            커서 이후 새로 생긴 거래와 대기 중인 거래를 대체하는 확정 거래가 포함됩니다.
        modified:
          type: array
          items:
            $ref: '#/components/schemas/BankTransaction'
          description: >-
            커서 이후 변경된 거래를 현재 상태 그대로 담습니다. 각 거래를 `id` 기준으로 upsert하여 적용하십시오. 첫 번째
            조회를 페이지 단위로 받는 동안 이미 받은 거래라도 그사이에 변경되었다면 여기에 다시 나타나며, 은행의 정정 내역도 여기에
            도착합니다.
        removed:
          type: array
          items:
            $ref: '#/components/schemas/BankRemovedTransaction'
          description: >-
            더 이상 존재하지 않는 거래이며 `reason`이 함께 제공됩니다. 보유하지 않은 `id`는 무시하십시오. 첫 번째 조회를
            페이지 단위로 받는 동안 삭제된 거래는 여전히 `added`로 한 번 전달되었고, 다음 조회에서 여기에 도착합니다.
        has_more:
          type: boolean
          description: >-
            다음 페이지가 더 있는 동안 `true`입니다. `has_more: false`인 응답을 받은 후에만
            `next_cursor`를 저장하십시오. 페이징 도중 실패하면 저장해 둔 커서부터 다시 시작하십시오.
        next_page_token:
          type: string
          description: '`has_more`가 `true`인 동안 이 읽기를 계속합니다.'
          nullable: true
        next_cursor:
          type: string
          description: >-
            피드의 영속적인 체크포인트이며, 마지막 페이지에서만 반환됩니다. 불투명한 값이며 애플리케이션, 환경 및 연결에
            바인딩됩니다. 90일 동안 재생할 수 있습니다. 첫 번째 읽기에서는 읽기가 시작된 시점을 표시하므로, 그 사이에 변경된
            내용은 다음 읽기에서 전달됩니다.
          nullable: true
        reset:
          type: boolean
          description: >-
            빈 커서에서 시작하는 모든 초기 조회(부트스트랩)에서는 `true`입니다. 결과를 기존 복사본에 추가하지 말고 복사본을
            결과로 교체하십시오.
      required:
        - added
        - modified
        - removed
        - has_more
        - next_page_token
        - next_cursor
        - reset
    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
    BankDataCursorError:
      allOf:
        - $ref: '#/components/schemas/BankDataError'
        - type: object
          properties:
            bootstrap:
              type: boolean
              description: >-
                `cursor_expired`와 함께 표시되며 항상 `true`입니다. 빈 `cursor`로 다시 시작하고, 저장해
                둔 사본을 결과로 교체해야 합니다.
      description: >-
        변경 피드의 `410` 응답 본문입니다. `cursor_expired`인 경우 `bootstrap: true`가 포함됩니다.
        이때는 빈 커서로 피드를 다시 읽고, 연결 거래 내역의 기존 사본에 추가하지 않고 그 결과로 교체하십시오.
        `page_expired`인 경우에는 `bootstrap`이 없으며, 마지막으로 저장한 커서부터 다시 시작하십시오.
    BankTransaction:
      type: object
      description: >-
        계좌의 거래 한 건입니다. 은행이 보내지 않는 필드는 `null`입니다. 기관 기능에서 은행이 보내는 것으로 알려진 필드를 확인할
        수 있습니다.
      properties:
        id:
          type: string
          description: >-
            Didit이 처음 확인될 때 저장되는 불투명한 ID입니다. 같은 거래는 조회, 동기화, 갱신 전반에서 동일한 ID를
            유지합니다. `identity_quality`는 이 보장의 강도를 나타냅니다.
          format: uuid
        account_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - booked
            - pending
          description: >-
            보류 거래는 고유 ID를 가집니다. 은행이 해당 거래를 확정하면, 은행이 둘을 연결한 경우 확정된 거래에
            `pending_id`가 포함되며, 보류 거래는 `reason: pending_booked`와 함께 `removed`에
            나타납니다.
        pending_id:
          type: string
          description: 이 거래가 대체한 대기 중 거래입니다. 은행이 두 거래를 연결한 경우에만 설정되며, 추측으로 설정되지 않습니다.
          format: uuid
          nullable: true
        reverses_id:
          type: string
          description: 은행이 연결하는 경우 이 거래가 취소하는 거래입니다. 취소 거래는 새로운 거래입니다.
          format: uuid
          nullable: true
        booking_date:
          type: string
          format: date
          nullable: true
        value_date:
          type: string
          format: date
          nullable: true
        transaction_date:
          type: string
          format: date
          nullable: true
        effective_date:
          type: string
          description: >-
            날짜 필터가 사용하는 날짜로, 은행이 자체 시간대 기준으로 보고한 값을 변환하지 않고 그대로 사용합니다. 기장된 거래는
            기장일, 없으면 가치일, 없으면 처음 확인된 날짜를 사용합니다. 대기 중인 거래는 거래일, 없으면 처음 확인된 날짜를
            사용합니다.
          format: date
        amount:
          type: string
          description: 부호 있는 10진수 문자열로 표시된 금액입니다. 음수는 출금을 의미합니다.
          pattern: ^-?\d+(\.\d+)?$
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: ISO 4217 통화 코드입니다.
        direction:
          type: string
          enum:
            - credit
            - debit
          description: '`amount`의 부호를 그대로 반복합니다.'
        description:
          type: string
          nullable: true
        counterparty:
          $ref: '#/components/schemas/BankTransactionCounterparty'
        remittance:
          $ref: '#/components/schemas/BankTransactionRemittance'
        bank_transaction_code:
          type: string
          nullable: true
        bank_reference:
          type: string
          description: 은행이 제공하는 경우 은행의 변경 불가능한 항목 참조값입니다. 그렇지 않으면 `null`이며, 임의로 생성하지 않습니다.
          nullable: true
        identity_quality:
          type: string
          enum:
            - bank_reference
            - route_id
            - derived
          description: >-
            `id`가 매칭된 방식입니다. `bank_reference`와 `route_id`는 안정적입니다. `derived`는
            내용으로 매칭됩니다. 은행이 해당 항목을 변경되지 않은 것으로 계속 보고하는 동안에는 안정적이지만, 은행이 정정하면
            `removed` 하나와 `added` 하나로 나타날 수 있습니다.
        end_to_end_id:
          type: string
          nullable: true
        mandate_id:
          type: string
          nullable: true
        creditor_id:
          type: string
          nullable: true
        merchant_category_code:
          type: string
          nullable: true
        exchange:
          type: object
          nullable: true
          description: 은행이 제공하는 경우 환전 세부 정보입니다.
          properties:
            source_amount:
              type: string
              pattern: ^-?\d+(\.\d+)?$
              nullable: true
            source_currency:
              type: string
              nullable: true
            rate:
              type: string
              pattern: ^-?\d+(\.\d+)?$
              nullable: true
        balance_after:
          type: string
          description: 은행이 제공하는 경우, 해당 거래 이후의 잔액입니다.
          pattern: ^-?\d+(\.\d+)?$
          nullable: true
        category:
          type: string
          description: 해당하는 경우 Didit 고유의 분류입니다.
          nullable: true
        first_seen_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - account_id
        - status
        - pending_id
        - reverses_id
        - booking_date
        - value_date
        - transaction_date
        - effective_date
        - amount
        - currency
        - direction
        - description
        - counterparty
        - remittance
        - bank_transaction_code
        - bank_reference
        - identity_quality
        - end_to_end_id
        - mandate_id
        - creditor_id
        - merchant_category_code
        - exchange
        - balance_after
        - category
        - first_seen_at
        - updated_at
    BankRemovedTransaction:
      type: object
      properties:
        id:
          type: string
          description: 더 이상 현재 상태가 아닌 거래의 ID.
          format: uuid
        reason:
          type: string
          enum:
            - pending_booked
            - pending_expired
            - bank_removed
            - access_removed
          description: >-
            `pending_booked`: 은행이 거래를 계정에 반영했으며, 반영된 거래는 `added`에 있습니다.
            `pending_expired`: 은행이 더 이상 보고하지 않는 보류 거래입니다. `bank_removed`: 은행이
            거래를 삭제했습니다. `access_removed`: 계정이 동의 범위에서 벗어났습니다.
      required:
        - id
        - reason
    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
    BankTransactionCounterparty:
      type: object
      properties:
        name:
          type: string
          nullable: true
        iban:
          type: string
          nullable: true
        bic:
          type: string
          nullable: true
      required:
        - name
        - iban
        - bic
    BankTransactionRemittance:
      type: object
      properties:
        unstructured:
          type: array
          items:
            type: string
        structured:
          type: string
          nullable: true
        reference:
          type: string
          nullable: true
      required:
        - unstructured
        - structured
        - reference
  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.