입출금내역 조회

무엇을 조회하나요

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

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

이용 조건

포인트를 차감하지 않습니다. 대신 스탠다드 플랜 이상을 구독해야 합니다. 무료체험 중이어도 체험 중인 플랜이 스탠다드 이상이면 이용할 수 있습니다. 플랜이 모자라면 세 경로 모두 402와 PLAN_UPGRADE_REQUIRED를 반환합니다. 볼타 대시보드의 결제 메뉴에서 플랜을 업그레이드한 뒤 다시 호출하세요.

API로는 계좌를 연결하지 않습니다. 은행 계좌 연동/해지를 참고해 볼타 대시보드에서 계좌를 먼저 연결하세요.

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

계좌 목록

curl https://xapi.bolta.io/v1/bankAccounts \
  -H "Authorization: Basic {apiKey}"

{
  "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을 보여 주세요.

입출금내역

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

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

{
  "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가 있으면 지우고, 없으면 무시하세요.

수집 절차

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

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

볼타에서 바뀐 거래는 약 5분 뒤부터 응답에 나옵니다. 저장 도중인 변경을 건너뛰지 않으려고 최근 5분 안에 바뀐 거래는 다음 호출로 미룹니다. 동기화가 끝난 직후라면 5분쯤 기다린 뒤 이어 받으세요. cursor는 해석하거나 직접 만들지 말고 받은 값 그대로 보내세요. 변조한 값은 400과 INVALID_CURSOR로 거절합니다. 조건(from, bankAccountId 등)을 바꿨다면 cursor 없이 처음부터 다시 받으세요. 볼타 운영자가 잘못 적재된 거래를 직접 정리하면 REMOVED 없이 사라질 수 있습니다. 이런 정리는 드물고, 필요하면 볼타가 따로 안내합니다.

동기화 요청

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

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

{
  "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 통신 오류

전체 에러 코드는 에러 코드에서 확인하세요.

API 소개

API 가이드

사용 사례

SDK/노코드 연동

무엇을 조회하나요

이용 조건

계좌 목록

입출금내역

순서와 cursor

수집 절차

동기화 요청

테스트 키로 조회하기

오류

관련 문서

​무엇을 조회하나요

​이용 조건

​계좌 목록

​입출금내역

​순서와 cursor

​수집 절차

​동기화 요청

​테스트 키로 조회하기

​오류

​관련 문서

무엇을 조회하나요

이용 조건

계좌 목록

입출금내역

순서와 cursor

수집 절차

동기화 요청

테스트 키로 조회하기

오류

관련 문서