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

# 입출금내역 조회

> 볼타에 연결한 입출금 계좌와 입출금내역을 조회하고 동기화를 요청하는 API의 이용 조건과 cursor 사용법을 안내합니다.

## 무엇을 조회하나요

볼타에 연결한 내 사업자의 입출금 계좌와 입출금내역을 조회합니다. 볼타가 은행에서 가져와 적재한 내역을 그대로 돌려주고, 필요하면 동기화를 요청할 수 있어요. 조회 대상은 API 키가 속한 사업자 한 곳이며, 다른 사업자의 계좌는 조회할 수 없습니다.

| 경로                                  | 용도                     |
| ----------------------------------- | ---------------------- |
| `GET /v1/bankAccounts`              | 연결된 입출금 계좌와 계좌별 동기화 상태 |
| `GET /v1/bankAccounts/transactions` | 적재된 입출금내역 (cursor 기반)  |
| `POST /v1/bankAccounts:sync`        | 입출금내역 동기화 요청           |

## 이용 조건

포인트를 차감하지 않습니다. 대신 **스탠다드 플랜 이상**을 구독해야 합니다. 무료체험 중이어도 체험 중인 플랜이 스탠다드 이상이면 이용할 수 있습니다.

플랜이 모자라면 세 경로 모두 `402`와 `PLAN_UPGRADE_REQUIRED`를 반환합니다. 볼타 대시보드의 결제 메뉴에서 플랜을 업그레이드한 뒤 다시 호출하세요.

<Info>
  API로는 계좌를 연결하지 않습니다. [은행 계좌 연동/해지](/docs/bank/account-management)를 참고해 볼타 대시보드에서 계좌를 먼저 연결하세요.
</Info>

세 경로 모두 발급자 등록, 공동인증서, 요청자 관리번호(`Bolta-Client-Reference-Id`)가 필요 없습니다. `Authorization` 헤더에 `Basic {apiKey}`만 넣으면 됩니다. 자세한 내용은 [인증 가이드](/docs/api-introduction/authentication)를 참고하세요.

## 계좌 목록

```bash theme={"dark"}
curl https://xapi.bolta.io/v1/bankAccounts \
  -H "Authorization: Basic {apiKey}"
```

```json theme={"dark"}
{
  "items": [
    {
      "id": "1",
      "bank": "KB_STAR",
      "bankName": "국민은행",
      "accountNumber": "123456-01-234567",
      "name": "운영자금",
      "currencyCode": "KRW",
      "lastSyncedAt": "2026-09-18T00:00:12Z",
      "syncStatus": "IDLE"
    }
  ]
}
```

| 필드              | 형식             | 설명                              |
| --------------- | -------------- | ------------------------------- |
| `id`            | string         | 계좌 식별자                          |
| `bank`          | string         | 은행 코드                           |
| `bankName`      | string         | 은행 이름                           |
| `accountNumber` | string         | 하이픈을 포함한 계좌번호                   |
| `name`          | string         | 대시보드에서 붙인 별칭. 없으면 은행 계좌명        |
| `currencyCode`  | string         | 통화 코드                           |
| `lastSyncedAt`  | string 또는 null | 마지막으로 완료한 동기화 시각 (UTC)          |
| `syncStatus`    | string         | `IDLE`, `IN_PROGRESS`, `FAILED` |

`id`는 숫자처럼 보여도 문자열로 다루세요. 식별자 형식은 바뀔 수 있습니다. `bank`에는 새 은행 코드가 추가될 수 있으니 화면에는 `bankName`을 보여 주세요.

## 입출금내역

```bash theme={"dark"}
curl "https://xapi.bolta.io/v1/bankAccounts/transactions?limit=100" \
  -H "Authorization: Basic {apiKey}"
```

| 파라미터              | 필수 | 설명                             |
| ----------------- | -- | ------------------------------ |
| `from`            | X  | 거래일 시작. `YYYY-MM-DD` (KST, 포함) |
| `to`              | X  | 거래일 끝. `YYYY-MM-DD` (KST, 포함)  |
| `bankAccountId`   | X  | 계좌 목록의 `id`                    |
| `transactionType` | X  | `DEPOSIT`, `WITHDRAW`, `OTHER` |
| `cursor`          | X  | 이전 응답의 `nextCursor`            |
| `limit`           | X  | 1부터 500까지. 기본 100              |

모든 조건은 선택입니다. 기간을 주지 않으면 적재된 전체 내역을 조회합니다.

```json theme={"dark"}
{
  "items": [
    {
      "status": "ACTIVE",
      "id": "1",
      "bankAccountId": "1",
      "bank": "KB_STAR",
      "accountNumber": "123456-01-234567",
      "transactionAt": "2026-09-01T00:30:00Z",
      "transactionType": "DEPOSIT",
      "amount": 1100000,
      "balanceAfterTransaction": 5100000,
      "description": "주식회사볼타",
      "currencyCode": "KRW"
    },
    {
      "status": "REMOVED",
      "id": "6"
    }
  ],
  "nextCursor": "djE6MTc4ODU3MDAwMDAwMDAwMDo2",
  "hasMore": false
}
```

항목은 `status`에 따라 모양이 다릅니다.

| `status`  | 뜻                                  | 담는 필드          |
| --------- | ---------------------------------- | -------------- |
| `ACTIVE`  | 볼타 대시보드에 보이는 거래                    | 아래 표의 모든 필드    |
| `REMOVED` | 계좌 연동 해제, 보관 등으로 대시보드에서 안 보이게 된 거래 | `status`, `id` |

| 필드                                | 형식             | 설명                                       |
| --------------------------------- | -------------- | ---------------------------------------- |
| `items[].status`                  | string         | `ACTIVE`, `REMOVED`                      |
| `items[].id`                      | string         | 거래 식별자                                   |
| `items[].bankAccountId`           | string         | 계좌 `id`                                  |
| `items[].bank`                    | string         | 은행 코드                                    |
| `items[].accountNumber`           | string         | 하이픈을 포함한 계좌번호                            |
| `items[].transactionAt`           | string         | 거래 시각 (UTC)                              |
| `items[].transactionType`         | string         | `DEPOSIT`, `WITHDRAW`, `OTHER`           |
| `items[].amount`                  | number         | 거래 금액. 0 이상이며 방향은 `transactionType`으로 구분 |
| `items[].balanceAfterTransaction` | number         | 거래 후 잔액                                  |
| `items[].description`             | string 또는 null | 은행 적요                                    |
| `items[].currencyCode`            | string         | 통화 코드                                    |
| `nextCursor`                      | string         | 다음 호출에 넘길 cursor                         |
| `hasMore`                         | boolean        | 지금 바로 이어 받을 내역이 더 있는지 여부                 |

`amount`와 `balanceAfterTransaction`은 소수점 아래의 불필요한 0을 뗀 숫자입니다. `OTHER`는 은행이 입금액과 출금액을 모두 0으로 준 거래이며 `amount`가 0입니다.

## 순서와 cursor

API는 **볼타에서 거래가 바뀐 순서**로 돌려줍니다. 거래 시각 순서가 아닙니다. 새로 적재된 거래, 다시 보이게 된 거래, 안 보이게 된 거래가 모두 바뀐 시점에 맞춰 뒤에 붙습니다.

볼타는 직전 동기화 구간과 하루를 겹쳐 다시 가져오므로 과거 시각의 거래가 나중에 적재될 수 있습니다. 계좌를 다시 연결하면 예전 거래가 같은 `id`로 다시 보이기도 합니다. 바뀐 순서로 받아야 이런 거래를 놓치지 않아요. 화면에 최신순으로 보여 주려면 받은 뒤 `transactionAt`으로 정렬하세요.

같은 `id`가 여러 번 올 수 있습니다. 받은 순서대로 `id` 기준으로 반영하세요.

* `ACTIVE`: 같은 `id`가 있으면 덮어쓰고, 없으면 추가하세요.
* `REMOVED`: 같은 `id`가 있으면 지우고, 없으면 무시하세요.

### 수집 절차

1. cursor 없이 호출하고, `hasMore`가 `false`가 될 때까지 `nextCursor`로 이어 호출하세요.
2. 마지막 `nextCursor`를 저장하세요. `hasMore`가 `false`여도 `nextCursor`는 항상 채워집니다.
3. 다음 수집 때 저장한 cursor로 호출하세요. 그 사이 바뀐 거래만 받습니다.

<Warning>
  `items`가 비어 있어도 `hasMore`가 `true`일 수 있습니다. 조건에 맞는 거래가 드물면 API가 한 번에 훑는 범위에서 멈추고 그 위치를 `nextCursor`로 돌려주기 때문입니다. `items`가 아니라 `hasMore`를 보고 이어 호출하세요.
</Warning>

볼타에서 바뀐 거래는 **약 5분 뒤부터** 응답에 나옵니다. 저장 도중인 변경을 건너뛰지 않으려고 최근 5분 안에 바뀐 거래는 다음 호출로 미룹니다. 동기화가 끝난 직후라면 5분쯤 기다린 뒤 이어 받으세요.

cursor는 해석하거나 직접 만들지 말고 받은 값 그대로 보내세요. 변조한 값은 `400`과 `INVALID_CURSOR`로 거절합니다. 조건(`from`, `bankAccountId` 등)을 바꿨다면 cursor 없이 처음부터 다시 받으세요.

볼타 운영자가 잘못 적재된 거래를 직접 정리하면 `REMOVED` 없이 사라질 수 있습니다. 이런 정리는 드물고, 필요하면 볼타가 따로 안내합니다.

## 동기화 요청

볼타는 입출금내역을 주기적으로 가져옵니다. 그 전에 최신 내역이 필요할 때만 동기화를 요청하세요.

```bash theme={"dark"}
curl -X POST https://xapi.bolta.io/v1/bankAccounts:sync \
  -H "Authorization: Basic {apiKey}"
```

```json theme={"dark"}
{
  "acceptedAt": "2026-09-18T03:00:00Z",
  "nextAvailableAt": "2026-09-18T03:30:00Z"
}
```

API가 `202 Accepted`로 접수만 하고 은행 조회는 비동기로 진행합니다. 진행 상황은 계좌 목록의 `syncStatus`로 확인하세요. `IN_PROGRESS`가 끝나면 저장한 cursor로 입출금내역을 이어 받으면 됩니다.

사업자마다 **30분에 1번, 24시간에 12번**까지 요청할 수 있습니다. `nextAvailableAt`은 30분 간격만 반영하고 24시간 한도는 반영하지 않습니다. 은행 조회는 계좌마다 순서대로 처리하므로 잦은 요청이 동기화를 빠르게 만들지는 않습니다.

| 상태 코드 | 에러 코드                        | 뜻                                 |
| ----- | ---------------------------- | --------------------------------- |
| `202` | -                            | 접수                                |
| `409` | `SYNC_IN_PROGRESS`           | 이미 동기화가 진행 중. 끝난 뒤 다시 요청하세요       |
| `422` | `BANK_ACCOUNT_NOT_CONNECTED` | 연결된 입출금 계좌가 없음                    |
| `429` | `SYNC_RATE_LIMITED`          | 요청 한도 초과. `Retry-After` 초만큼 기다리세요 |
| `503` | `SYNC_UNAVAILABLE`           | 일시적으로 판정할 수 없음. 잠시 후 다시 요청하세요     |

진행 중이라 거절한 요청(`409`)은 한도를 차감하지 않습니다.

## 테스트 키로 조회하기

테스트 키는 구독과 관계없이 고정 샘플을 돌려줍니다. 실제 계좌를 조회하지 않고, 동기화를 요청해도 은행 조회를 보내지 않으며 한도도 차감하지 않습니다.

| 계좌 `id` | 은행        | 계좌번호               |
| ------- | --------- | ------------------ |
| `1`     | `KB_STAR` | `123456-01-234567` |
| `2`     | `SHINHAN` | `110-123-456789`   |

| 거래 `id` | 계좌  | 거래 시각 (UTC)          | 유형         | 금액        | 상태        |
| ------- | --- | -------------------- | ---------- | --------- | --------- |
| `1`     | `1` | 2026-09-01T00:30:00Z | `DEPOSIT`  | 1,100,000 | `ACTIVE`  |
| `2`     | `1` | 2026-09-01T06:10:00Z | `WITHDRAW` | 55,000    | `ACTIVE`  |
| `3`     | `2` | 2026-09-02T01:00:00Z | `DEPOSIT`  | 330,000   | `ACTIVE`  |
| `4`     | `1` | 2026-09-03T08:45:00Z | `WITHDRAW` | 2,200,000 | `ACTIVE`  |
| `5`     | `2` | 2026-09-04T02:20:00Z | `DEPOSIT`  | 770,000   | `ACTIVE`  |
| `6`     | `2` | 2026-09-04T03:00:00Z | `WITHDRAW` | 12,000    | `REMOVED` |

`6`번은 보관한 거래라 `status`와 `id`만 내려갑니다. `limit=3`으로 호출하면 cursor 넘김을 두 페이지로 확인할 수 있어요. 조건과 cursor는 라이브 키와 같은 규칙으로 동작하고, 테스트 키는 5분 지연 없이 바로 돌려줍니다.

## 오류

| 상태 코드 | 에러 코드                        | 발생 조건                                                         |
| ----- | ---------------------------- | ------------------------------------------------------------- |
| `400` | `INVALID_REQUEST`            | 날짜 형식 오류, `from`이 `to`보다 늦음, `transactionType`이나 `limit` 값 오류 |
| `400` | `INVALID_CURSOR`             | 변조했거나 형식이 틀린 cursor                                           |
| `401` | -                            | API 키 인증 실패. 응답 본문 없음                                         |
| `402` | `PLAN_UPGRADE_REQUIRED`      | 스탠다드 플랜 미만                                                    |
| `404` | `BANK_ACCOUNT_NOT_FOUND`     | 없거나 내 사업자의 것이 아닌 `bankAccountId`                              |
| `409` | `SYNC_IN_PROGRESS`           | 동기화가 이미 진행 중                                                  |
| `422` | `BANK_ACCOUNT_NOT_CONNECTED` | 연결된 입출금 계좌가 없음                                                |
| `429` | `SYNC_RATE_LIMITED`          | 동기화 요청 한도 초과. `Retry-After` 헤더 동반                             |
| `500` | `INTERNAL_SERVER_ERROR`      | 서버 내부 오류                                                      |
| `503` | `SYNC_UNAVAILABLE`           | 동기화 요청을 일시적으로 판정할 수 없음                                        |
| `503` | `SERVICE_UNAVAILABLE`        | 일시적인 내부 API 통신 오류                                             |

전체 에러 코드는 [에러 코드](/docs/api-introduction/error-codes)에서 확인하세요.

## 관련 문서

* [입출금 계좌 목록 조회 API](/api-reference/입출금내역-조회/입출금-계좌-목록-조회)
* [입출금내역 조회 API](/api-reference/입출금내역-조회/입출금내역-조회)
* [입출금내역 동기화 요청 API](/api-reference/입출금내역-조회/입출금내역-동기화-요청)
* [입출금 내역 관리](/docs/bank/transaction-management)
* [인증 가이드](/docs/api-introduction/authentication)