매출/매입 내역 조회

무엇을 조회하나요

볼타에 쌓인 내 사업자의 매출과 매입을 대시보드의 매출/매입 목록과 같은 단위로 조회합니다. 조회 대상은 API 키가 속한 사업자 한 곳입니다. 필요하면 수집을 앞당겨 달라고 요청할 수 있습니다.

경로	용도
`GET /v1/revenues`	매출 변경 내역 (cursor 기반)
`GET /v1/expenses`	매입 변경 내역 (cursor 기반)
`POST /v1/revenues:sync`	매출 동기화 요청
`POST /v1/expenses:sync`	매입 동기화 요청

응답에는 세금계산서와 계산서가 실립니다(type이 HOMETAX_TAX_INVOICE). 볼타에서 발행한 문서와 홈택스에서 수집한 문서가 모두 들어갑니다. 현금영수증은 볼타에서 발행한 것도 싣지 않습니다.

이용 조건

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

홈택스 매출/매입 연동은 볼타 대시보드에서 먼저 하세요. 연동 방법은 홈택스에 등록된 매출세금계산서 가져오기와 홈택스에 등록된 매입세금계산서 가져오기를 참고하세요.

연동하지 않고 볼타에서 발행만 한 사업자도 발행한 세금계산서는 매출로 조회할 수 있습니다. 연동을 해제해도 이미 쌓인 매출/매입은 계속 조회됩니다. 네 경로 모두 발급자 등록, 공동인증서, 요청자 관리번호(Bolta-Client-Reference-Id)가 필요 없습니다. Authorization 헤더에 Basic {apiKey}만 넣으면 됩니다. 인증은 인증 가이드를 참고하세요.

주요 제한

항목	제한
동기화 요청	사업자마다, 매출과 매입 각각 30분에 1번, 24시간에 12번
응답 반영	볼타에서 바뀐 뒤 약 5분
홈택스 수집 문서 반영	보통 수집 뒤 1~2시간
한 번에 받는 건수 (`limit`)	최대 200건, 기본 100건

매출/매입 목록

두 경로의 파라미터와 응답 모양은 같습니다. 매출인지 매입인지는 경로가 정합니다.

curl "https://xapi.bolta.io/v1/revenues?limit=100" \
  -H "Authorization: Basic {apiKey}"

파라미터	필수	설명
`from`	X	거래일 시작. `YYYY-MM-DD` (KST, 포함). 세금계산서는 작성일자
`to`	X	거래일 끝. `YYYY-MM-DD` (KST, 포함)
`type`	X	`HOMETAX_TAX_INVOICE`
`cursor`	X	이전 응답의 `nextCursor`
`limit`	X	1부터 200까지. 기본 100

기간을 주지 않으면 쌓인 전체 내역을 조회합니다. 아래는 테스트 키로 cursor 없이 호출한 매출 응답에서 102와 103을 뺀 예시입니다.

{
  "items": [
    {
      "status": "ACTIVE",
      "id": "101",
      "type": "HOMETAX_TAX_INVOICE",
      "taxInvoice": {
        "ntsTransactionId": "20260901-10000000-00000101",
        "invoiceType": "TAX_INVOICE",
        "purpose": "CLAIM",
        "writtenDate": "2026-09-01",
        "issuedAt": "2026-09-01T05:12:00Z",
        "supplier": {
          "identificationNumberType": "BUSINESS",
          "identificationNumber": "1234567890",
          "taxRegistrationId": null,
          "organizationName": "주식회사 볼타테스트",
          "representativeName": "정대표",
          "address": "서울특별시 테스트구 테스트로 1",
          "businessType": "서비스",
          "businessItem": "소프트웨어 개발",
          "manager": {
            "name": "홍길동",
            "email": "tax@example.com",
            "telephone": "02-0000-0000"
          }
        },
        "supplied": {
          "identificationNumberType": "BUSINESS",
          "identificationNumber": "1111111111",
          "taxRegistrationId": null,
          "organizationName": "주식회사 테스트고객",
          "representativeName": "테스트대표",
          "address": "경기도 테스트시 샘플로 2",
          "businessType": "도매",
          "businessItem": "도소매",
          "manager": {
            "name": "김담당",
            "email": "buyer@example.com",
            "telephone": null
          }
        },
        "trustee": null,
        "totalSupplyCost": 1000000,
        "totalTax": 100000,
        "totalAmount": 1100000,
        "paymentMeans": {
          "cash": null,
          "check": null,
          "bankBill": null,
          "accountReceivable": 1100000
        },
        "description": null,
        "amendReason": null,
        "importDeclaration": null,
        "items": [
          {
            "date": "2026-09-01",
            "name": "컨설팅",
            "specification": null,
            "quantity": 1,
            "unitPrice": 600000,
            "supplyCost": 600000,
            "tax": 60000,
            "description": null
          },
          {
            "date": "2026-09-01",
            "name": "교육",
            "specification": null,
            "quantity": 2,
            "unitPrice": 200000,
            "supplyCost": 400000,
            "tax": 40000,
            "description": null
          }
        ]
      }
    },
    {
      "status": "REMOVED",
      "id": "104"
    }
  ],
  "nextCursor": "djI6MTc4ODU3MzYwMDAwMDAwMDoxMDQ6MXVpMmNn",
  "hasMore": false
}

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

`status`	뜻	담는 필드
`ACTIVE`	볼타 대시보드에 보이는 매출/매입	`status`, `id`, `type`, `type`에 맞는 하위 객체
`REMOVED`	보관하거나 비활성이 되어 대시보드에서 안 보이게 된 매출/매입	`status`, `id`

필드	형식	설명
`items[].status`	string	`ACTIVE`, `REMOVED`
`items[].id`	string	매출 또는 매입 식별자. 경로 안에서 유일
`items[].type`	string	증빙 종류. `HOMETAX_TAX_INVOICE`
`items[].taxInvoice`	object	`type`이 `HOMETAX_TAX_INVOICE`일 때의 세금계산서 원문
`nextCursor`	string	다음 호출에 넘길 cursor
`hasMore`	boolean	지금 바로 이어 받을 내역이 더 있는지 여부

id는 세금계산서가 아니라 매출 또는 매입 한 건의 식별자입니다. HOMETAX_TAX_INVOICE는 국세청에 등록된 세금계산서와 계산서를 뜻합니다. 볼타에서 발행한 문서도 같은 값을 씁니다.

세금계산서 원문

taxInvoice는 매출과 매입이 같은 모양입니다.

필드	형식	설명
`ntsTransactionId`	string	국세청 승인번호
`invoiceType`	string	국세청 문서 구분. 문서 구분 참고
`purpose`	string 또는 null	`RECEIPT` 영수, `CLAIM` 청구
`writtenDate`	string	작성일자 `YYYY-MM-DD` (KST)
`issuedAt`	string	발급 시각 (UTC). 상세를 채울 수 없는 문서는 발급일 00:00(KST)
`supplier`	object	공급자. 당사자 참고
`supplied`	object	공급받는자
`trustee`	object 또는 null	수탁자. 위수탁 문서일 때만
`totalSupplyCost`	integer	공급가액 합계
`totalTax`	integer 또는 null	세액 합계. 계산서처럼 세액이 없는 문서는 null
`totalAmount`	integer	합계 금액
`paymentMeans.cash`	integer 또는 null	현금
`paymentMeans.check`	integer 또는 null	수표
`paymentMeans.bankBill`	integer 또는 null	어음
`paymentMeans.accountReceivable`	integer 또는 null	외상미수금
`description`	string 또는 null	비고
`amendReason`	string 또는 null	국세청 수정 사유. 수정 사유 참고. 수정세금계산서가 아니면 null
`importDeclaration`	object 또는 null	수입신고 정보. 수입 세금계산서일 때만
`importDeclaration.declarationNumber`	string 또는 null	수입신고번호
`importDeclaration.periodStartDate`	string 또는 null	과세기간 시작일 (KST)
`importDeclaration.periodEndDate`	string 또는 null	과세기간 종료일 (KST)
`importDeclaration.itemCount`	integer 또는 null	수입 건수
`items`	array	품목. 상세를 채울 수 없는 문서는 빈 배열
`items[].date`	string 또는 null	공급일자 (KST)
`items[].name`	string 또는 null	품목명
`items[].specification`	string 또는 null	규격
`items[].quantity`	number 또는 null	수량
`items[].unitPrice`	number 또는 null	단가
`items[].supplyCost`	integer	공급가액
`items[].tax`	integer 또는 null	세액
`items[].description`	string 또는 null	비고

금액은 원 단위 정수이고, 수정세금계산서는 음수일 수 있습니다. 수량과 단가는 정수면 소수점 없이, 소수면 소수 자리까지 옵니다.

당사자

supplier, supplied, trustee는 같은 모양입니다.

필드	형식	설명
`identificationNumberType`	string	`BUSINESS` 사업자, `RESIDENT` 개인, `FOREIGN` 외국인
`identificationNumber`	string	하이픈 없는 식별번호
`taxRegistrationId`	string 또는 null	종사업장번호
`organizationName`	string 또는 null	상호
`representativeName`	string 또는 null	대표자
`address`	string 또는 null	주소
`businessType`	string 또는 null	업태
`businessItem`	string 또는 null	종목
`manager`	object 또는 null	담당자. 이름, 이메일, 전화번호가 모두 없으면 null
`manager.name`	string 또는 null	이름
`manager.email`	string 또는 null	이메일
`manager.telephone`	string 또는 null	전화번호

`identificationNumberType`	`identificationNumber`
`BUSINESS`	사업자등록번호 10자리
`RESIDENT`	주민등록번호 13자리
`FOREIGN`	외국인 식별번호

공급자와 수탁자는 항상 BUSINESS입니다. 공급받는자만 RESIDENT나 FOREIGN일 수 있고, 이때 taxRegistrationId, businessType, businessItem은 null입니다. 공급받는자에게 담당자가 둘이면 첫 번째 담당자를 manager에 싣습니다.

RESIDENT의 identificationNumber는 주민등록번호 원문입니다. 받은 값은 암호화해 저장하고 로그에 남기지 마세요.

문서 구분

`invoiceType`	문서
`TAX_INVOICE`	전자세금계산서
`ZERO_RATED_TAX_INVOICE`	영세율 전자세금계산서
`INVOICE`	전자계산서 (면세)
`IMPORT_TAX_INVOICE`	수입 전자세금계산서 (납부유예 포함)

위수탁 문서는 따로 구분하지 않습니다. trustee가 채워져 있으면 위수탁 문서입니다.

수정 사유

`amendReason`	사유
`MISSPELLED`	기재사항 착오 정정
`CHANGE_SUPPLY_COST`	공급가액 변동
`RETURNED`	환입
`TERMINATION`	계약의 해제
`LOCAL_LETTER_OF_CREDIT`	내국신용장 사후 개설
`DOUBLE_ISSUANCE`	착오에 의한 이중발급

기재사항 착오 정정과 내국신용장 사후 개설은 취소분과 수정분 두 장이 한 쌍으로 발급됩니다. API는 두 장을 같은 사유로 보냅니다.

응답에 싣는 문서

API는 상세를 채우는 중인 문서를 돌려주지 않습니다. 홈택스에서 수집한 문서는 승인번호, 당사자, 금액을 먼저 받고 발급 시각, 주소, 업태, 담당자, 품목을 나중에 채웁니다. 볼타에서 발행한 세금계산서는 바로 나옵니다. 홈택스에서 수집한 문서는 작성일자 최신순으로 상세를 채운 뒤 나오므로, 과거 문서가 많으면 오래된 작성일자 문서가 뒤늦게 이어서 나옵니다. 상세 조회가 끝내 실패한 문서는 목록 조회 값만 싣고 items를 비웁니다. 주소, 업태, 종목, 담당자도 null일 수 있습니다. 나중에 상세가 채워지면 같은 id로 다시 옵니다. ntsTransactionId, issuedAt, invoiceType은 항상 채워져 있습니다. 입금이나 지급 완료 여부, 메모, 라벨, 담당자 배정처럼 볼타 안에서만 쓰는 관리 정보는 싣지 않습니다.

순서와 cursor

API는 볼타에서 매출/매입이 바뀐 순서로 돌려줍니다. 작성일자나 수집 순서가 아닙니다. 과거 작성일자 문서, 상세 반영, 보관과 보관 해제가 뒤늦게 일어나도 놓치지 않으려면 이 순서대로 받으세요. 화면에 작성일자순으로 보여 주려면 받은 뒤 writtenDate로 정렬하세요. 같은 id가 여러 번 올 수 있습니다. 받은 순서대로 id 기준으로 반영하세요.

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

매입은 볼타가 지급 완료 여부를 다시 판정할 때도 순서가 뒤로 옮겨집니다. 그래서 내용이 같은 매입이 한 번 더 올 수 있습니다. 덮어쓰면 됩니다.

수집 절차

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

items가 비어 있어도 hasMore가 true일 수 있습니다. items가 아니라 hasMore를 보고 이어 호출하세요.

cursor는 받은 값 그대로 보내세요. cursor를 받을 때와 경로, 조건, 키 모드가 다르면 API가 400과 INVALID_CURSOR를 반환합니다. type을 넣고 받은 cursor와 빼고 받은 cursor도 서로 다른 조건입니다. 조건을 바꿨거나 테스트 키에서 라이브 키로 옮겼다면 cursor 없이 처음부터 받으세요. limit은 페이지마다 바꿔도 됩니다.

새 값 처리

볼타는 새 type, 새 필드, invoiceType이나 amendReason의 새 값을 예고 없이 더할 수 있습니다. 현금영수증 같은 새 증빙은 같은 경로에 새 type과 그에 맞는 하위 객체로 싣습니다.

모르는 type의 항목은 건너뛰고 처리를 이어가세요.
모르는 필드는 무시하세요.
모르는 열거 값을 받아도 실패하지 말고 처리를 이어가세요.

REMOVED는 type 없이 오므로 id 기준으로 그대로 반영하면 됩니다.

동기화 요청

볼타는 매출/매입을 주기적으로 수집합니다. 대시보드에서 처음 연동할 때도 첫 수집을 바로 시작합니다. 방금 국세청에 올라간 문서가 급할 때만 동기화를 요청하세요.

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

{
  "acceptedAt": "2026-09-18T03:00:00Z",
  "nextAvailableAt": "2026-09-18T03:30:00Z"
}

경로	수집 대상
`POST /v1/revenues:sync`	대시보드에서 연동한 매출 전부
`POST /v1/expenses:sync`	대시보드에서 연동한 매입 전부

API가 202 Accepted로 접수만 하고 수집은 비동기로 진행합니다. 수집 상태를 조회하는 경로는 없습니다. 수집이 끝나기를 기다리지 말고 저장한 cursor로 목록을 이어 받으세요. 요청 한도는 주요 제한을 참고하세요. 409와 422로 거절한 요청은 한도를 차감하지 않습니다. nextAvailableAt은 30분 간격만 반영하고 24시간 횟수는 반영하지 않습니다.

상태 코드	에러 코드	뜻
`202`	-	접수
`409`	`SYNC_IN_PROGRESS`	같은 경로의 수집이 이미 진행 중. 볼타의 정기 수집도 포함하며, 끝난 뒤 다시 요청하세요
`422`	`NO_SOURCE_CONNECTED`	매출이나 매입을 가져올 연동이 대시보드에 없음
`429`	`SYNC_RATE_LIMITED`	요청 한도 초과. `Retry-After` 초만큼 기다리세요
`503`	`SYNC_UNAVAILABLE`	일시적으로 판정할 수 없음. 잠시 후 다시 요청하세요

테스트 키

테스트 키는 구독과 관계없이 고정 샘플을 5분 지연 없이 돌려줍니다. 동기화를 요청해도 수집하지 않고 접수 응답만 돌려주며, 한도를 차감하지 않습니다. 샘플의 내 사업자는 주식회사 볼타테스트(1234567890)입니다. 매출 (GET /v1/revenues)

`id`	변경 시각 (UTC)	작성일자	`invoiceType`	공급받는자	합계	상태
`101`	2026-09-01T05:12:30Z	2026-09-01	`TAX_INVOICE`	주식회사 테스트고객	1,100,000	`ACTIVE`
`102`	2026-09-04T00:00:00Z	2026-09-03	`ZERO_RATED_TAX_INVOICE`	테스트수출 주식회사	500,000	`ACTIVE`
`103`	2026-09-05T02:00:00Z	2026-09-05	`TAX_INVOICE`	주식회사 테스트고객	-220,000	`ACTIVE`
`104`	2026-09-05T02:00:00Z	2026-09-02				`REMOVED`

101: 볼타에서 발행한 세금계산서. 품목 2개
102: 홈택스에서 수집한 영세율 세금계산서
103: 공급가액 변동 수정세금계산서(amendReason이 CHANGE_SUPPLY_COST). 금액이 음수이고 품목의 quantity, unitPrice가 null
104: 대시보드에서 보관한 매출. 103과 같은 시각에 바뀌어 id 순서로 뒤에 옴

매입 (GET /v1/expenses)

`id`	변경 시각 (UTC)	작성일자	`invoiceType`	공급자	합계	상태
`201`	2026-09-01T09:00:00Z	2026-09-01	`TAX_INVOICE`	주식회사 테스트공급	110,000	`ACTIVE`
`202`	2026-09-03T00:00:00Z	2026-09-02	`INVOICE`	테스트농산	180,000	`ACTIVE`
`203`	2026-09-06T00:30:00Z	2026-09-05	`TAX_INVOICE`	주식회사 테스트물류	330,000	`ACTIVE`

201: 홈택스에서 수집한 세금계산서
202: 면세 계산서. totalTax와 품목의 tax가 null
203: 상세를 채울 수 없는 세금계산서. 주소, 업태, 종목, manager가 null이고 items가 빈 배열

limit=2로 호출하면 cursor 넘김을 두 페이지로 확인할 수 있습니다. 기간 조건과 cursor는 라이브 키와 같은 규칙으로 동작합니다.

오류

상태 코드	에러 코드	발생 조건
`400`	`INVALID_REQUEST`	날짜 형식 오류, `from`이 `to`보다 늦음, `type`이나 `limit` 값 오류
`400`	`INVALID_CURSOR`	변조했거나 형식이 틀린 cursor, 경로나 조건이나 키 모드가 cursor를 받을 때와 다름
`401`	-	API 키 인증 실패. 응답 본문 없음
`402`	`PLAN_UPGRADE_REQUIRED`	스탠다드 플랜 미만
`409`	`SYNC_IN_PROGRESS`	같은 경로의 수집이 이미 진행 중
`422`	`NO_SOURCE_CONNECTED`	매출이나 매입을 가져올 연동이 없음
`429`	`SYNC_RATE_LIMITED`	동기화 요청 한도 초과. `Retry-After` 헤더 동반
`500`	`INTERNAL_SERVER_ERROR`	서버 내부 오류
`503`	`FEED_UNAVAILABLE`	일시적으로 내역을 불러올 수 없음. cursor가 넘어가지 않았으니 같은 cursor로 다시 호출하세요
`503`	`SYNC_UNAVAILABLE`	동기화 요청을 일시적으로 판정할 수 없음
`503`	`SERVICE_UNAVAILABLE`	일시적인 내부 API 통신 오류

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

API 소개

API 가이드

사용 사례

SDK/노코드 연동

무엇을 조회하나요

이용 조건

주요 제한

매출/매입 목록

세금계산서 원문

당사자

문서 구분

수정 사유

응답에 싣는 문서

순서와 cursor

수집 절차

새 값 처리

동기화 요청

테스트 키

오류

관련 문서

​무엇을 조회하나요

​이용 조건

​주요 제한

​매출/매입 목록

​세금계산서 원문

​당사자

​문서 구분

​수정 사유

​응답에 싣는 문서

​순서와 cursor

​수집 절차

​새 값 처리

​동기화 요청

​테스트 키

​오류

​관련 문서

무엇을 조회하나요

이용 조건

주요 제한

매출/매입 목록

세금계산서 원문

당사자

문서 구분

수정 사유

응답에 싣는 문서

순서와 cursor

수집 절차

새 값 처리

동기화 요청

테스트 키

오류

관련 문서