bolta

Bolta API CLI - 한국 전자세금계산서, 현금영수증, 홈택스 국세 증명 서류, 법인등기사항전부증명서 발급/조회 도구

AI 에이전트(Claude Code 등)가 세금계산서, 현금영수증, 국세 증명 서류 업무를 자동화할 때 사용할 수 있도록 설계되었습니다.

설치

cURL (macOS / Linux)

curl -fsSL https://cli.boltacorp.com/install.sh | bash

Node.js

npm install -g @bolta-io/cli

PowerShell (Windows)

irm https://cli.boltacorp.com/install.ps1 | iex

사용법

인증 설정

Bolta API를 사용하려면 API 키가 필요합니다. 환경변수 또는 CLI 명령으로 설정합니다.

# 방법 1: 환경변수 (권장)
export BOLTA_API_KEY="test_your_key"

# 방법 2: CLI 명령 (영구 저장 - ~/.bolta/config.json)
bolta config set api-key test_your_key

# 연결 테스트
bolta config test

인증 해결 우선순위: CLI 플래그(--api-key) > 환경변수(BOLTA_API_KEY) > 설정 파일(~/.bolta/config.json)

커맨드 전체 목록

발급자 관리

# 발급자 등록
bolta issuer create --data '{
  "identificationNumber": "1234567890",
  "organizationName": "주식회사 테스트",
  "representativeName": "홍길동"
}'

# 발급자 조회
bolta issuer get <issuerId>

인증서 관리

# 인증서 등록 URL 조회
bolta certificate url <issuerId>

# 인증서 등록 상태 조회
bolta certificate status <issuerId>

# 인증서 해제
bolta certificate deregister <issuerId>

issuerId는 발급자와 인증서 관리에만 사용합니다. 발행 요청은 본문의 사업자등록번호로 발급자를 찾습니다.

세금계산서 발행/조회

# 세금계산서 정발행
bolta invoice issue --reference-id inv-2026-001 --data '{
  "date": "2026-03-25",
  "purpose": "CLAIM",
  "taxType": "TAXABLE",
  "supplier": {
    "identificationNumber": "1234567890",
    "organizationName": "공급자 주식회사",
    "representativeName": "김공급",
    "manager": { "email": "[email protected]" }
  },
  "supplied": {
    "identificationNumber": "0987654321",
    "organizationName": "공급받는자 주식회사",
    "representativeName": "이고객",
    "managers": [{ "email": "[email protected]" }]
  },
  "items": [{
    "date": "2026-03-25",
    "name": "소프트웨어 개발 용역",
    "supplyCost": 1000000,
    "tax": 100000
  }]
}'

# 외국인등록번호 공급받는자는 정발행에서만 지원합니다.
# supplied.identificationNumber에 외국인등록번호 13자리를 넣고, 최상위 description은 빼거나 null로 둡니다.
# 여권번호는 아직 지원하지 않습니다.
bolta examples invoice-issue-foreign-supplied

# 세금계산서 역발행 요청 (공급받는자는 사업자등록번호만 허용)
bolta invoice issue-request --reference-id inv-2026-002 --data '{...}'

# 세금계산서 조회
bolta invoice get <issuanceKey>

# Bolta-Client-Reference-Id로 상태 조회
bolta invoice status --reference-id <id>

# 발행을 마친 세금계산서 PDF 저장 (디렉터리를 주면 API가 준 파일 이름 사용)
bolta invoice pdf <issuanceKey> --output ./invoices/

# 작성일자로 발행 마감일 조회
bolta invoice due-date 2026-09-30

세금계산서의 --reference-id는 선택 사항입니다. 앞뒤 공백 없는 출력 가능한 ASCII 1~255자를 입력하세요. 같은 API 키의 정발행·역발행·수정발행에서 이미 사용한 값은 요청 내용이나 명령이 달라도 다시 사용할 수 없습니다. 중복이면 API가 400 INVALID_REQUEST를 반환합니다.

응답을 받지 못했거나 응답 본문을 읽지 못했다면 같은 요청을 다시 보내지 마세요. 요청에 사용한 값으로 bolta invoice status --reference-id <id>를 실행해 접수 여부를 확인하세요. 새 발행 요청에는 사용하지 않은 값을 입력합니다.

정발행과 역발행은 작성일자가 발행 마감일을 지나면 400 INVALID_REQUEST를 반환합니다. 발행 전에 bolta invoice due-date <작성일자>로 마감일을 확인하세요. 마감일은 작성일자가 속한 달의 다음 달 10일입니다. 10일이 주말이나 공휴일이면 다음 영업일로 늦춰지고, 국세청이 기한을 연장한 달은 연장된 날짜를 따릅니다. 마감일 당일까지는 기한 안입니다. 이 조회는 발급자와 인증서가 필요 없고 포인트도 차감하지 않습니다. 볼타가 마감일을 관리하지 않는 달을 요청하면 400 INVALID_REQUEST입니다.

bolta invoice pdf는 정발행, 역발행, 수정세금계산서 중 발행을 마친 건의 PDF를 받습니다. 역발행은 공급자가 승인한 뒤에 받을 수 있습니다. 발행을 요청한 API 키로 실행하세요. 첫 호출이 PDF 생성을 시작하고, CLI가 Retry-After를 따라 최대 120초 기다립니다. 그 안에 준비되지 않으면 status: PENDING과 retryAfterSeconds를 출력합니다. 기다리지 않으려면 --no-wait를 주세요. --output이 없으면 5분 동안 유효한 downloadUrl과 filename을 출력하고, 있으면 PDF를 저장한 뒤 경로를 savedTo로 알려 줍니다. 주소에는 서명값이 들어 있으니 로그에 남기지 마세요. 공급받는자가 개인이면 주민등록번호가 PDF에 그대로 나옵니다. 포인트는 차감하지 않고, 테스트 키는 바로 샘플 PDF를 돌려줍니다.

수정발행

# 수정발행: 계약 해제
bolta invoice amend termination <issuanceKey> --date 2026-03-25 --reference-id amend-2026-001

# 수정발행: 공급가액 변동
bolta invoice amend change-supply-cost <issuanceKey> --reference-id amend-2026-002 --data '{
  "date": "2026-03-25",
  "taxType": "TAXABLE",
  "items": [{
    "date": "2026-03-25",
    "name": "가격 조정",
    "supplyCost": -200000,
    "tax": -20000
  }]
}'

# 수정발행: 착오에 의한 이중발급 (입력 데이터 불필요)
bolta invoice amend double-issuance <issuanceKey> --reference-id amend-2026-003

현금영수증

현금영수증 발행과 취소는 비동기입니다. API가 요청을 접수하면 issuanceKey를 반환하며, 최종 결과는 status 명령으로 확인합니다. 현금영수증 발행은 포인트를 차감하지 않습니다. 대량 발행이 필요하면 볼타 담당자와 협의하세요.

# 휴대폰번호로 현금영수증 발행
bolta cash-receipt issue --reference-id cash-2026-001 --data '{
  "itemName": "서비스 이용료",
  "issuer": {
    "businessRegistrationNumber": "5648102684",
    "organizationName": "(주) 볼타코퍼레이션",
    "representativeName": "이문혁",
    "telephone": "02-1234-5678"
  },
  "recipient": {
    "type": "PHONE",
    "value": "010-1234-5678"
  },
  "amount": {
    "supplyAmount": 100,
    "vatAmount": 10,
    "taxFreeAmount": 0
  }
}'

# 발행 상태 확인
bolta cash-receipt status --reference-id cash-2026-001

# 발행 완료 건 전액 취소
bolta cash-receipt cancel <issuanceKey> --reference-id cash-2026-001-cancel

# 취소 상태 확인
bolta cash-receipt status --reference-id cash-2026-001-cancel

PENDING과 REQUEST_SUCCESS는 처리 중입니다. ISSUED 또는 CANCELED 상태를 확인한 뒤 성공으로 처리하세요. 부분 취소는 지원하지 않습니다.

원본 발행 요청이 아직 PENDING이면 취소 요청이 409 ORIGINAL_ISSUANCE_PENDING으로 실패합니다. 원본 상태가 바뀐 뒤 다시 요청하세요. 같은 원본에 진행 중이거나 완료된 취소 요청이 있으면 409 CANCELLATION_ALREADY_REQUESTED입니다. 새 reference-id로 보내도 같으니 기존 취소 요청의 상태를 조회하세요. 볼타 밖(예: 홈택스)에서 먼저 취소된 원본을 취소하면 API가 202로 접수하지만 CANCEL_FAILED로 끝나고, failure.code는 CANCELLATION_TARGET_NOT_FOUND입니다.

사업자등록 상태 조회

사업자등록번호의 등록 상태와 과세유형을 조회합니다. 발급자 등록과 공동인증서가 필요 없습니다.

이전 명령어 bolta business-status도 계속 동작하지만 deprecated입니다. 실행하면 경고를 출력하니 bolta business-registration-status로 바꾸세요.

bolta business-registration-status check 1000000014
bolta business-registration-status check 100-00-00014   # 하이픈 허용

{
  "success": true,
  "data": {
    "businessRegistrationNumber": "1000000014",
    "registration": { "status": "ACTIVE", "closedOn": null },
    "taxation": { "type": "GENERAL", "changedOn": "2026-01-01" }
  }
}

• registration.status: ACTIVE(계속), SUSPENDED(휴업), CLOSED(폐업), NOT_REGISTERED(미등록), UNKNOWN(위 네 가지에 속하지 않는 기타 등록 상태)
• registration.closedOn: 폐업자만 YYYY-MM-DD, 나머지는 null
• taxation.type: 국세청 과세유형. GENERAL(일반), SIMPLIFIED_RECEIPT_ISSUER(간이, 세금계산서 발행 불가), SIMPLIFIED_TAX_INVOICE_ISSUER(간이, 세금계산서 발행 가능), SPECIAL_TAXPAYER(과세특례), TAX_FREE(면세), NONPROFIT(비영리), UNIQUE_NUMBER_ORGANIZATION(고유번호 단체) 중 하나입니다. 처음 보는 값은 기타로 처리하세요. 세금계산서 요청의 taxType과 뜻이 다릅니다.
• taxation.changedOn: 과세유형 전환일 YYYY-MM-DD. 전환한 적이 없으면 null입니다.
• taxation: 국세청이 과세유형을 주지 않으면 null입니다. 계속사업자는 항상 값이 있고, 미등록과 기타 상태는 항상 null입니다. 휴업자와 폐업자는 국세청이 마지막 과세유형을 주면 값이 있고, 주지 않으면 null입니다.

거래처 목록은 한 번에 최대 100건까지 일괄 조회할 수 있습니다. 중복 번호는 하이픈 표기가 달라도 하나로 줄입니다.

bolta business-registration-status check-bulk 1000000014 100-00-00028 1000000071
bolta business-registration-status check-bulk --file numbers.json   # {"businessRegistrationNumbers": [...]}

{
  "success": true,
  "data": {
    "results": [
      {
        "businessRegistrationNumber": "1000000014",
        "status": {
          "businessRegistrationNumber": "1000000014",
          "registration": { "status": "ACTIVE", "closedOn": null },
          "taxation": { "type": "GENERAL", "changedOn": "2026-01-01" }
        }
      },
      { "businessRegistrationNumber": "1000000028", "status": null }
    ]
  }
}

results는 요청 순서를 따릅니다. status가 null인 항목은 이번에 확인하지 못한 번호이고 포인트를 차감하지 않습니다. 그 번호만 나중에 다시 조회하세요. 한 건도 확인하지 못하면 503 LOOKUP_UNAVAILABLE이나 429 RATE_LIMITED로 실패합니다.

통신 실패는 UNKNOWN으로 돌려주지 않습니다. 사업자등록 상태를 확인할 수 없으면 503 LOOKUP_UNAVAILABLE입니다. 라이브 키는 상태를 확인한 번호마다 10포인트를 차감합니다. 호출 한도는 API 키 모드별 24시간 10,000건이고, 요청 수가 아니라 조회한 번호 수로 셉니다. 볼타 서비스 전체의 일일 조회 한도에 도달해도 429 RATE_LIMITED를 받습니다. CLI는 이 조회를 자동 재시도하지 않습니다. 테스트 키로 조회할 수 있는 고정 번호는 bolta guide business-registration-status로 확인하세요.

사업자등록증 인식과 진위확인

사업자등록증 파일 한 건에서 사업자등록번호, 상호, 대표자명, 개업일, 주소, 업종을 읽습니다. 읽은 사업자등록번호, 첫 번째 대표자명, 개업일로 국세청 진위확인을 하고 결과를 validation에 담습니다. 발급자 등록, 공동인증서, 요청자 관리번호가 모두 필요 없고 구독 플랜 제한도 없습니다.

bolta business-registration-certificate extract ./certificate.pdf
bolta business-registration-certificate extract ./photo.jpg --dry-run   # 업로드 없이 파일 정보만 확인

PDF, JPG, PNG, WebP 파일 한 개를 보내세요. 5MB 이하, PDF는 5쪽 이하입니다. 빈 파일과 5MB를 넘는 파일은 CLI가 업로드 전에 막습니다. 형식은 서버가 파일 내용으로 판별하며, 사업자등록증이 아니거나 사업자등록번호를 읽지 못하면 400 INVALID_FILE입니다. 이때 error.message는 사용자에게 그대로 보여 줘도 됩니다. 홈택스에서 내려받은 PDF를 가장 정확하게 읽습니다.

validation이 MATCHED나 NOT_MATCHED면 100포인트를 차감합니다. UNAVAILABLE(국세청 장애), 오류 응답, 테스트 키는 차감하지 않습니다. 멱등 키가 없어 같은 파일을 다시 보내면 다시 차감하며, CLI는 이 요청을 자동으로 재전송하지 않습니다. validation이 MATCHED이고 inputQuality가 SUFFICIENT면 입력 화면에 값을 미리 채워도 되지만, 저장하기 전에는 사용자가 확인하게 하세요. 상호, 주소, 업종은 진위확인 대상이 아닙니다.

처리에 최대 약 45초가 걸리고 CLI는 90초까지 기다립니다. 라이브 키는 파트너당 한 번에 한 건만 처리하니(429 TOO_MANY_IN_FLIGHT) 앞 요청의 응답을 받은 뒤 보내세요. 하루 처리 한도는 24시간 1,000건이며 테스트 키와 라이브 키는 따로 셉니다(429 RATE_LIMITED). 테스트 키는 파일과 관계없이 고정 결과(1000000014, MATCHED)를 돌려줍니다. 자세한 내용은 bolta guide business-registration-certificate로 확인하세요.

매출/매입 내역 조회

볼타로 발행했거나 홈택스에서 수집한 세금계산서와 계산서를 매출과 매입으로 나눠 변경분 단위로 조회합니다. 발급자 등록과 공동인증서가 필요 없습니다. API로는 홈택스를 연결할 수 없으니 볼타 대시보드에서 먼저 연결하세요. 볼타로 발행한 세금계산서는 연결하지 않아도 매출로 나옵니다. 포인트는 차감하지 않지만 스탠다드 플랜 이상이 필요합니다(아니면 402 PLAN_UPGRADE_REQUIRED).

bolta revenue list --from 2026-09-01 --to 2026-09-30   # 매출 변경분 한 페이지
bolta revenue list --all --limit 200                   # hasMore가 false가 될 때까지 이어서 조회
bolta expense list --cursor <저장한 nextCursor> --all    # 저장한 지점 뒤 매입 변경분만
bolta revenue sync                                     # 매출 즉시 동기화 요청
bolta expense sync                                     # 매입 즉시 동기화 요청

list는 작성일자 순서가 아니라 볼타에서 바뀐 순서로 돌려줍니다. 받은 순서대로 반영하세요. ACTIVE는 같은 id를 덮어쓰고, REMOVED는 같은 id를 지웁니다. 현금영수증과 볼타 전용 관리 정보(결제 상태, 메모, 라벨, 담당자)는 오지 않습니다. hasMore가 false여도 nextCursor는 항상 있으니 저장해 두고 다음 수집 때 --cursor로 넘기세요. cursor는 명령(revenue, expense), 조회 조건(--from, --to, --type), API 키 종류에 묶입니다. 매출과 매입, 조건마다 cursor를 따로 저장하세요. 다르면 400 INVALID_CURSOR입니다. --limit은 1~200이고 바꿔도 됩니다. 503 FEED_UNAVAILABLE이면 cursor가 넘어가지 않았으니 같은 cursor로 다시 조회하세요.

거래처는 매출이면 taxInvoice.supplied, 매입이면 taxInvoice.supplier에 있습니다. 공급받는자의 identificationNumberType이 RESIDENT면 identificationNumber가 주민등록번호 원문이니 암호화해 저장하고 로그에 남기지 마세요. 볼타가 type, invoiceType, amendReason 값과 필드를 예고 없이 늘릴 수 있으니 모르는 type은 건너뛰고 모르는 값에 실패하지 마세요.

sync는 명령마다 30분에 한 번, 24시간에 12번까지 요청할 수 있고 매출과 매입 한도를 따로 셉니다. CLI는 자동으로 다시 요청하지 않습니다. 202는 접수만 뜻하고 수집 상태를 확인하는 API는 없습니다. 기다리지 말고 저장한 cursor로 list를 이어서 조회하세요. 테스트 키가 돌려주는 고정 매출과 매입은 bolta guide revenue-expense로 확인하세요.

입출금내역 조회

볼타 대시보드에 연결한 계좌의 목록과 거래 변경분을 조회합니다. 발급자 등록과 공동인증서가 필요 없습니다. API로는 계좌를 연결할 수 없으니 대시보드에서 먼저 연결하세요. 포인트는 차감하지 않지만 스탠다드 플랜 이상이 필요합니다(아니면 402 PLAN_UPGRADE_REQUIRED).

bolta bank-account list                                             # 연결된 계좌 목록
bolta bank-account transactions --from 2026-09-01 --to 2026-09-30   # 거래 변경분 한 페이지
bolta bank-account transactions --all --limit 500                   # hasMore가 false가 될 때까지 이어서 조회
bolta bank-account transactions --cursor <저장한 nextCursor> --all    # 저장한 지점 뒤 변경분만
bolta bank-account sync                                             # 즉시 동기화 요청

transactions는 거래 시각 순서가 아니라 볼타에서 거래가 바뀐 순서로 돌려줍니다. 받은 순서대로 반영하세요. ACTIVE는 같은 id를 덮어쓰고, REMOVED는 같은 id를 지웁니다. hasMore가 false여도 nextCursor는 항상 있으니 저장해 두고 다음 수집 때 --cursor로 넘기세요. cursor는 받을 때의 조회 조건(--from, --to, --bank-account-id, --type)과 API 키에 묶입니다. 조건마다 cursor를 따로 저장하고, 조건을 바꿨거나 테스트 키에서 라이브 키로 옮겼다면 cursor 없이 처음부터 다시 조회하세요. 다르면 400 INVALID_CURSOR입니다. --limit은 바꿔도 됩니다.

계좌와 거래의 bankCode는 금융결제원 3자리 은행코드(예: 004 국민은행, 088 신한은행)이고 currencyCode는 ISO 4217 통화 코드(KRW, USD, JPY)입니다. 두 값 모두 늘어날 수 있으니 모르는 값을 받아도 실패하지 말고, 화면에는 bankName을 보여 주세요. 전체 은행코드는 bolta guide bank-account로 확인하세요.

sync는 사업자마다 30분에 한 번, 하루 12번까지 요청할 수 있고 CLI는 자동으로 다시 요청하지 않습니다. 202는 접수만 뜻합니다. bolta bank-account list로 syncStatus가 IN_PROGRESS인 계좌가 없어질 때까지 확인한 뒤, 5분쯤 지나서 transactions를 조회하세요. 테스트 키가 돌려주는 고정 계좌와 거래는 bolta guide bank-account로 확인하세요.

예금주 조회

은행코드와 계좌번호로 예금주명을 조회합니다. 송금하기 전에 거래처 계좌가 맞는지 확인할 때 씁니다. 발급자 등록, 공동인증서, 요청자 관리번호가 모두 필요 없고 구독 플랜 제한도 없습니다.

bolta bank-account-holder check 088 1000000001                  # 예금주 단건 조회
bolta bank-account-holder check 088 100-0000-001                # 하이픈을 포함해도 됩니다
bolta bank-account-holder check 089 1000000004 --amount 20000   # 금액 지정형 가상계좌
bolta bank-account-holder check-bulk --data '{"accounts":[{"bankCode":"088","accountNumber":"1000000001"}]}'

예금주를 돌려준 계좌마다 50포인트를 차감합니다. 찾지 못했거나 조회에 실패한 계좌는 차감하지 않습니다. 일반 계좌는 한 요청 안에서 같은 은행코드와 계좌번호를 여러 번 넣어도 한 번만 차감합니다. 금액 지정형 가상계좌는 고유한 amount마다 차감합니다. 멱등 키가 없어 요청을 다시 보내면 다시 차감하며, CLI는 이 조회를 자동으로 재요청하지 않습니다.

bankCode는 금융결제원 3자리 은행코드입니다. 국내 26곳과 외국계 11곳을 지원하며 그 밖의 코드는 400 UNSUPPORTED_BANK입니다. 전체 목록은 bolta guide bank-account-holder로 확인하세요. accountNumber는 하이픈을 빼고 6~20자리 숫자여야 하고, 응답의 accountNumber는 하이픈을 뗀 값입니다.

입금 금액이 정해진 가상계좌는 AMOUNT_REQUIRED를 돌려줍니다. 그 계좌로 보낼 총 지급 금액을 --amount에 넣어 다시 조회하세요. 금액이 다르면 AMOUNT_MISMATCH입니다.

일괄 조회는 계좌를 1개 이상 100개 이하로 넣습니다. 항목 하나라도 형식이 틀리면 요청 전체를 400 INVALID_REQUEST로 거절합니다. results는 보낸 accounts와 같은 순서, 같은 개수이며 중복 계좌를 넣어도 줄이지 않습니다. HTTP 200으로 와도 일부 계좌는 실패할 수 있으니 항목마다 error가 null인지 확인하세요. error.code가 BANK_UNAVAILABLE인 항목은 판정하지 못한 계좌이니 잠시 후 그 계좌만 다시 조회하세요. 한 계좌도 판정하지 못하면 이 응답 대신 503 BANK_UNAVAILABLE입니다.

하루에 조회할 수 있는 계좌는 10,000개이고 요청 수가 아니라 계좌 수로 셉니다. 테스트 키와 라이브 키는 한도를 따로 셉니다. 테스트 키로 조회할 수 있는 고정 계좌는 bolta guide bank-account-holder로 확인하세요.

서류 발급 (홈택스 국세 증명 서류, 법인등기)

홈택스 국세 증명 서류 5종(사업자등록증명, 사업자등록증 재발급, 납세증명서, 부가가치세 과세표준증명, 표준재무제표증명)과 법인등기사항전부증명서(열람용, 제출용)를 발급합니다.

• 홈택스 서류는 API 키가 속한 사업자의 서류를 발급합니다. 볼타 대시보드에 해당 사업자의 공동인증서를 등록하세요.
• 법인등기는 document.corporationNumber에 넣은 법인의 등기부를 발급합니다. 공동인증서는 필요 없습니다. cancelledEntries(INCLUDE 또는 EXCLUDE)로 말소사항 포함 여부를 고르세요.

bolta document issue --reference-id order-20260919-001 --data '{
  "document": { "type": "BUSINESS_REGISTRATION_PROOF", "language": "KO" }
}'

bolta document issue --reference-id order-20260919-002 --data '{
  "document": { "type": "CORPORATE_REGISTRY_ISSUANCE", "corporationNumber": "110111-1234567", "cancelledEntries": "EXCLUDE" }
}'

bolta document get <issuanceKey>

발급은 비동기입니다. ACCEPTED와 SUBMITTED는 처리 중이고, COMPLETED가 되면 downloadUrl을 반환합니다. 주소는 홈택스 서류 5분, 법인등기 1분 동안 유효합니다. 만료되면 document get으로 새 주소를 받으세요. 홈택스 서류는 보통 30초, 법인등기는 몇 분이 걸립니다. 기다리는 시간이 1시간을 넘기면 FAILED로 바뀝니다. ACTION_REQUIRED이면 같은 서류를 다시 요청하지 마세요.

한 건에 홈택스 서류 500포인트, 법인등기 열람용 1,000포인트, 제출용 1,500포인트를 차감하며 실패하면 차감하지 않습니다. 납세증명서는 매일 06:00~22:00(한국 시간)에만 요청할 수 있고, 그 밖의 시간에는 409 OUTSIDE_SERVICE_HOURS입니다. reference-id는 앞뒤 공백 없는 출력 가능한 ASCII 1~255자로 입력하세요. 같은 reference-id와 같은 본문은 안전하게 다시 보낼 수 있지만, 다른 본문을 보내면 409 IDEMPOTENCY_CONFLICT입니다.

테스트 키는 기관에 신청하지 않습니다. 홈택스 서류는 항상 바로 완료합니다. 법인등기는 1100000000014를 바로 완료하고 1100000000071을 바로 실패 처리하며, 다른 법인등록번호는 400 INVALID_REQUEST입니다. 자세한 입력은 bolta schema document-issue, 서류별 샘플은 bolta examples document-issue-corporate-registry-issuance 등으로 확인하세요.

설정

bolta config set <key> <value>   # api-key, base-url, update-check
bolta config show                # 현재 설정 확인
bolta config test                # API 연결 테스트

도움말

# 주요 개념 안내 (issuer, payment, workflow, cash-receipt, business-registration-status, business-registration-certificate, revenue-expense, bank-account, bank-account-holder, document, glossary)
bolta guide [topic]

# 바로 쓸 수 있는 샘플 JSON
bolta examples [command]

# JSON 입력 스키마 조회
bolta schema [command]

invoice issue, invoice issue-request, amend change-supply-cost 입력은 국세청 XML 전송 제한에 맞춰 로컬에서 먼저 검증됩니다. 필드별 길이 제한은 bolta schema invoice-issue로 확인할 수 있습니다. taxType은 TAXABLE(과세), ZERO_RATE(영세율), TAX_FREE(면세) 중 하나이며 필수입니다. ZERO_RATE은 모든 품목의 tax를 0으로, TAX_FREE는 모든 품목의 tax를 null로 전달합니다. 사업자등록 상태 일괄 조회 입력은 bolta schema business-registration-status-check-bulk로 확인할 수 있습니다. 현금영수증 입력 규칙은 bolta schema cash-receipt-issue로 확인할 수 있습니다. 수취인 유형별 예제는 bolta examples cash-receipt-issue, cash-receipt-issue-business, cash-receipt-issue-self를 사용하세요. 서류 발급 입력은 bolta schema document-issue로 확인하세요.

업데이트

# 최신 버전으로 업데이트
bolta update

# 업데이트 가능 여부 확인
bolta update check

입력 방법

데이터가 필요한 커맨드는 3가지 입력 방식을 지원합니다.

# 인라인 JSON (AI 에이전트 권장)
bolta invoice issue --data '{"date":"2026-03-25", ...}'

# 파일 참조
bolta invoice issue --file invoice.json

# 파이프 입력
cat invoice.json | bolta invoice issue --stdin

글로벌 옵션

| 옵션 | 설명 | |------|------| | --api-key <key> | API 키 오버라이드 | | --verbose | 상세 로그 출력 (stderr) | | --dry-run | API 호출 없이 요청 데이터만 출력 |

출력 형식

모든 응답은 JSON으로 stdout에 출력됩니다.

// 성공 (exit code 0)
{ "success": true, "data": { ... } }

// 실패 (exit code 1)
{ "success": false, "error": { "code": "...", "message": "...", "suggestion": "..." } }

에러 코드 참조

| 코드 | 원인 | 해결 | |------|------|------| | AUTH_ERROR | API 키 없음/잘못됨 | bolta config set api-key <key> | | VALIDATION_ERROR | 입력 데이터 오류 | bolta schema <command>로 스키마 확인 | | INPUT_ERROR | 명령어·옵션·입력 방식 오류 | bolta --help 또는 하위 명령의 --help로 사용법 확인 | | INVALID_REQUEST | 요청 검증 실패, 세금계산서 발행 마감일 경과 또는 요청자 관리번호 중복 | error.message와 해당 명령의 schema 확인. 세금계산서 중복이면 invoice status로 기존 요청 확인 | | HTTP_402 | 포인트 잔액 부족 | https://developers.bolta.io 에서 포인트 충전 | | HTTP_400 | 잘못된 요청 | error.message 확인 | | HTTP_404 | 리소스 없음 | issuanceKey/issuerId 확인 | | HTTP_429 | 요청 제한 초과 | 일반 요청은 자동 재시도(Retry-After 30초 이하). 관리번호가 있는 세금계산서 요청은 invoice status로 접수 여부 확인 | | RATE_LIMITED | 사업자등록 상태 조회 24시간 한도, 사업자등록증 인식 24시간 1,000건 한도, 예금주 조회 하루 10,000계좌 한도 또는 서비스 전체 일일 한도 초과 | error.details.retryAfterSeconds초 뒤 다시 실행 | | INVALID_BUSINESS_REGISTRATION_NUMBER | 사업자등록번호 체크섬 불일치 | 번호 확인 | | INVALID_FILE | 사업자등록증 인식에서 지원하지 않는 형식, 읽을 수 없는 파일, 5쪽 초과 PDF, 사업자등록증이 아니거나 사업자등록번호를 읽을 수 없는 파일 | error.message를 사용자에게 보여 주고 다른 파일로 다시 실행 | | EXTRACTION_UNAVAILABLE | 사업자등록증 인식 실패 또는 처리 시간 초과 (포인트 미차감) | 잠시 후 다시 실행 | | UNSUPPORTED_MEDIA_TYPE | 사업자등록증 인식 요청이 multipart/form-data가 아님 | bolta update로 CLI 업데이트 | | LOOKUP_UNAVAILABLE | 사업자등록 상태 확인 불가, 또는 예금주 조회와 사업자등록증 인식의 호출 한도 판정 불가 (포인트 미차감) | 잠시 후 다시 실행 | | ACCOUNT_NOT_VERIFIED | 예금주 조회에서 계좌를 확인하지 못함 (포인트 미차감) | 은행코드와 계좌번호 확인 | | ACCOUNT_NOT_AVAILABLE | 입금이 정지된 가상계좌 | 계좌를 발급한 기관에 문의 | | AMOUNT_REQUIRED | 입금 금액이 정해진 가상계좌인데 금액이 없음 | --amount에 총 지급 금액을 넣어 다시 조회 | | AMOUNT_MISMATCH | 입력한 금액이 가상계좌에 정해진 금액과 다름 | 총 지급 금액 확인 | | AMOUNT_VERIFICATION_UNAVAILABLE | 금액 지정형 가상계좌를 지금 조회할 수 없음 | 계좌를 발급한 곳에서 예금주 확인 | | UNSUPPORTED_BANK | 예금주 조회를 지원하지 않는 은행코드 | bolta guide bank-account-holder로 지원 은행 확인 | | BANK_UNAVAILABLE | 은행 점검이나 연결 오류 (포인트 미차감) | 잠시 후 해당 계좌만 다시 조회 | | PLAN_UPGRADE_REQUIRED | 입출금내역, 매출/매입 내역 API를 쓰려면 스탠다드 플랜 이상 필요 (포인트 부족과 다름) | 볼타 대시보드 결제 메뉴에서 플랜 업그레이드 | | INVALID_CURSOR | 입출금내역, 매출/매입 cursor가 손상됐거나, 받을 때와 명령, 조회 조건 또는 API 키가 다름 | 같은 명령과 조건으로 이전 응답의 nextCursor를 그대로 사용. 조건이나 키를 바꿨다면 cursor 없이 다시 조회 | | FEED_UNAVAILABLE | 매출/매입 내역을 잠시 가져올 수 없음 (cursor는 그대로) | 잠시 후 같은 --cursor로 다시 조회 | | BANK_ACCOUNT_NOT_FOUND | 없거나 내 계좌가 아닌 계좌 ID | bank-account list의 id 확인 | | BANK_ACCOUNT_NOT_CONNECTED | 연결된 계좌 없이 동기화 요청 | 볼타 대시보드에서 계좌 연결 | | SYNC_IN_PROGRESS | 입출금내역, 매출 또는 매입 동기화가 이미 진행 중 (한도 미차감) | 입출금내역은 bank-account list로 syncStatus 확인. 매출/매입은 기다리지 말고 저장한 cursor로 list 조회 | | NO_SOURCE_CONNECTED | 매출 또는 매입 수집처 연결 없이 동기화 요청 (한도 미차감) | 볼타 대시보드에서 홈택스 연결 | | SYNC_RATE_LIMITED | 동기화 한도(30분 1회, 하루 12회) 초과. 매출과 매입은 따로 셈 | error.details.retryAfterSeconds초 뒤 다시 요청 | | SYNC_UNAVAILABLE | 동기화 한도를 확인할 수 없어 요청 거절 | 잠시 후 다시 요청 | | CERTIFICATE_REQUIRED | 홈택스 서류 발급에 쓸 공동인증서가 없거나 만료됨 | 볼타 대시보드에서 API 키가 속한 사업자의 인증서 등록 | | PERIOD_NOT_CLOSED | 표준재무제표증명의 사업연도가 끝나지 않음 | 신고를 마친 사업연도로 다시 요청 | | OUTSIDE_SERVICE_HOURS | 서류의 요청 가능 시간 밖 요청 (납세증명서 06:00~22:00) | 요청 가능 시간에 다시 요청 | | TARGET_BUSY | 같은 법인, 같은 등기 서류, 같은 cancelledEntries를 다른 요청이 발급 중 | 앞 요청이 끝난 뒤 다시 요청 | | IDEMPOTENCY_CONFLICT | 같은 서류 발급이나 현금영수증 reference-id에 다른 요청 내용 사용 | 기존 본문을 다시 보내거나 새 reference-id 사용 | | CANCELLATION_ALREADY_REQUESTED | 같은 현금영수증에 진행 중이거나 완료된 취소 요청이 있음 | 새 reference-id로 보내지 말고 기존 취소 요청을 cash-receipt status로 확인 | | ORIGINAL_ISSUANCE_PENDING | 원본 현금영수증 발행 요청이 아직 PENDING이라 취소 불가 | 원본 상태가 바뀐 뒤 다시 취소 요청 | | AVAILABLE_POINTS_INSUFFICIENT | 서류 발급, 사업자등록 상태 조회, 예금주 조회, 사업자등록증 인식에서 진행 중인 다른 요청 때문에 지금 쓸 수 있는 포인트 부족 | 충전하거나 그 요청이 끝난 뒤 다시 요청 | | TOO_MANY_IN_FLIGHT | 처리 중인 서류 요청이 5건, 만드는 중인 세금계산서 PDF가 사업자당 10건이나 API 키당 20건, 또는 사업자등록증 인식이 처리 중(라이브 키 파트너당 1건) | 기존 요청이 끝난 뒤 다시 요청 | | TAX_INVOICE_RETRIEVE_NOT_AVAILABLE | 세금계산서 PDF 조회에서 발행 완료 전이거나 발행 실패. 역발행은 공급자 승인 전이거나 거절 | invoice get으로 발행 결과 확인 뒤 다시 실행 | | INVALID_DOCUMENT | 저장된 문서 정보로 세금계산서 PDF를 만들 수 없음 | issuanceKey와 함께 볼타에 문의 | | PDF_GENERATION_FAILED | 여러 번 시도했지만 세금계산서 PDF를 만들지 못함 | error.details.retryAfterSeconds초 뒤 같은 명령 재실행. 계속되면 볼타에 문의 | | DOCUMENT_ISSUANCE_NOT_FOUND | 없거나 다른 API 키의 서류 발급 요청 | issuanceKey와 API 키 확인 | | DOCUMENT_ISSUANCE_UNAVAILABLE | 지금은 서류를 발급할 수 없음 (포인트 미예약) | 잠시 후 같은 reference-id와 같은 본문으로 다시 요청 | | NETWORK_ERROR | 네트워크 오류 또는 응답 본문 읽기 실패 | 세금계산서는 invoice status로 확인. 서류 발급은 같은 reference-id와 같은 본문으로 다시 요청 |

AI 가이드

이 CLI는 AI 에이전트가 쉽게 사용할 수 있도록 다음 가이드를 제공합니다.

| 가이드 | 용도 | 접근 방법 | |--------|------|-----------| | CLAUDE.md | Claude Code가 자동으로 읽는 프로젝트 가이드 | 프로젝트 루트에 위치 | | llms.txt | 범용 AI 에이전트 참조 문서 | 프로젝트 루트에 위치 | | bolta guide | 주요 개념 및 사용법 안내 | bolta guide [topic] | | bolta examples | 바로 쓸 수 있는 샘플 JSON | bolta examples [command] | | bolta schema | JSON 입력 스키마 | bolta schema [command] | | --help | 모든 커맨드에 예시 포함 | bolta <command> --help |

# 사용 가능한 예제 목록
bolta examples

# 정발행 샘플 JSON 조회
bolta examples invoice-issue

# 정발행 입력 스키마 조회
bolta schema invoice-issue

라이선스

MIT