인증 - 볼타 사용 가이드

API 키 인증 (Basic Auth)

볼타 API는 HTTP Basic Authentication을 사용합니다. API 키를 Base64로 인코딩해 Authorization 헤더에 넣으세요.

Authorization: Basic {Base64(API_KEY:)}

API 키 뒤에 콜론(:)을 붙인 뒤 Base64로 인코딩하세요.

예시

# API 키가 test_abc123인 경우
# Base64("test_abc123:") = dGVzdF9hYmMxMjM6

curl -X POST https://xapi.bolta.io/v1/taxInvoices/issue \
  -H "Authorization: Basic dGVzdF9hYmMxMjM6" \
  -H "Content-Type: application/json"

테스트 키 vs 라이브 키

구분	접두사	용도
테스트 키	`test_`	샌드박스 환경, 국세청 미연동
라이브 키	`live_`	실제 환경, 국세청 연동

개발과 테스트에는 테스트 키를 사용하세요.

API 키 발급 방법은 API 키 가이드를 참고하세요.

요청 헤더

Client-Reference-Id

Bolta-Client-Reference-Id는 발행 요청을 구분하는 요청자 관리번호입니다. 세금계산서, 현금영수증, 서류 발급의 중복 요청 처리 방식이 다릅니다.

세금계산서

정발행, 수정발행, 역발행 요청을 구분하려면 1~255자의 비어 있지 않은 값을 입력하세요. 이 헤더는 선택 사항입니다.

Bolta-Client-Reference-Id: your-unique-reference-id

같은 API 키로 이미 사용한 값은 요청 내용이나 API 경로와 관계없이 다시 쓸 수 없습니다. 중복 요청이면 API가 HTTP 400과 INVALID_REQUEST를 반환합니다. 네트워크 오류 등으로 응답을 받지 못했다면 같은 요청을 다시 보내지 마세요. 요청에 사용한 값을 clientReferenceId에 넣어 처리 상태를 조회하세요.

curl "https://xapi.bolta.io/v1/taxInvoices/issue/status?clientReferenceId=your-unique-reference-id" \
  -H "Authorization: Basic {apiKey}"

현금영수증

현금영수증 발행과 취소 요청에는 이 헤더가 필수입니다. 1~255자의 값을 입력하세요. 같은 API 키와 요청자 관리번호로 요청 내용과 유형까지 동일하게 다시 호출하면 API가 기존 접수 건의 issuanceKey를 담은 202 Accepted 응답을 반환합니다. 요청 내용이나 유형이 다르면 409 Conflict와 IDEMPOTENCY_CONFLICT를 반환합니다. 취소 요청에는 발행 요청과 다른 값을 사용하세요. 요청 흐름은 현금영수증 발행 가이드를 참고하세요.

서류 발급

서류 발급 요청에는 이 헤더가 필수입니다. 1~255자의 값을 입력하세요. 같은 값과 같은 본문으로 다시 보내면 API가 기존 요청을 반환합니다. 본문이 다르면 409 Conflict와 IDEMPOTENCY_CONFLICT를 반환합니다. 요청 흐름은 서류 발급을 참고하세요.

API 소개

API 가이드

사용 사례

SDK/노코드 연동

인증

API 키 인증 (Basic Auth)

테스트 키 vs 라이브 키

요청 헤더

Client-Reference-Id

세금계산서

현금영수증

서류 발급

​API 키 인증 (Basic Auth)

​테스트 키 vs 라이브 키

​요청 헤더

​Client-Reference-Id

​세금계산서

​현금영수증

​서류 발급

API 키 인증 (Basic Auth)

테스트 키 vs 라이브 키

요청 헤더

Client-Reference-Id

세금계산서

현금영수증

서류 발급