현금영수증 발행

처리 흐름

현금영수증 발행이나 취소 요청을 보내면 API가 202 Accepted와 issuanceKey를 먼저 반환합니다. 최종 결과는 웹훅이나 상태 조회 API로 확인하세요.

웹훅 - 등록한 URL로 결과 이벤트를 전송합니다. 별도 조회 없이 결과를 받으려면 웹훅을 등록하세요.
상태 조회 API - Bolta-Client-Reference-Id로 현재 상태를 조회합니다.

202는 요청 접수를 뜻하며 발행이나 취소 성공을 보장하지 않습니다.

최종 상태와 웹훅 시점은 키와 처리 결과에 따라 다릅니다.

TEST 키 - 요청 처리 후 최종 상태를 바로 조회할 수 있습니다. 자동 웹훅은 요청 접수 시각부터 최소 10초 뒤에 전송합니다.
LIVE 키 - 처리 중이거나 발행 결과 확인이 필요한 요청은 요청일 다음 날 17:00(KST) 이후에 최종 상태가 확정될 수 있습니다. 웹훅은 최종 상태가 바뀐 뒤 전송합니다.

웹훅 발송 시점은 웹훅 발송 시간을 확인하세요.

요금

현금영수증 발행은 포인트를 차감하지 않습니다. 대량 발행이 필요하면 볼타 담당자와 협의하세요.

발행

POST /v1/cashReceipts로 발행을 요청합니다.

현금영수증을 발행하려면 발급자 등록 API로 공급자를 등록하고 공동인증서를 등록하세요. 등록 방법은 인증서 등록 연동을 참고하세요.

헤더	필수	설명
`Authorization`	O	`Basic {apiKey}` 형식으로 입력하세요. 인증 가이드를 참고하세요
`Bolta-Client-Reference-Id`	O	요청자 관리번호이자 멱등키입니다. 1~255자로 입력하세요
`Bolta-Webhook-Test-Code`	X	테스트 키에서 실패 웹훅을 재현할 때만 입력하세요

같은 API 키와 요청자 관리번호로 요청 내용과 유형까지 동일하게 다시 호출하면 API가 기존 접수 건의 issuanceKey를 담은 202 Accepted 응답을 반환합니다. 요청 내용이나 유형이 다르면 409 Conflict와 IDEMPOTENCY_CONFLICT를 반환합니다. 이 규칙은 발행과 취소 요청에 모두 적용됩니다.

curl -X POST https://xapi.bolta.io/v1/cashReceipts \
  -H "Authorization: Basic {apiKey}" \
  -H "Bolta-Client-Reference-Id: your-unique-reference-id" \
  -H "Content-Type: application/json" \
  -d '{
    "itemName": "서비스 이용료",
    "issuer": {
      "businessRegistrationNumber": "1234567890",
      "organizationName": "공급자 상호",
      "representativeName": "공급자대표",
      "telephone": "02-1234-5678"
    },
    "recipient": { "type": "PHONE", "value": "010-1234-5678" },
    "amount": { "supplyAmount": 100, "vatAmount": 10, "taxFreeAmount": 0 }
  }'

API가 발행 식별 키(issuanceKey)를 반환합니다. 취소 요청에 사용할 수 있도록 저장하세요.

{ "issuanceKey": "MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I" }

수취인 유형

recipient.type에 맞춰 recipient.value를 입력하세요.

유형(`type`)	의미	`value`
`SELF`	자진발급(수취인 정보 없이 발행)	생략(또는 `null`)
`PHONE`	휴대폰번호	`010-1234-5678` 형식 휴대폰번호
`BUSINESS_REGISTRATION_NUMBER`	사업자등록번호(지출증빙)	하이픈 없는 10자리 사업자등록번호

{ "type": "SELF" }

{ "type": "PHONE", "value": "010-1234-5678" }

{ "type": "BUSINESS_REGISTRATION_NUMBER", "value": "0987654321" }

공급자 정보

필드	규칙
`businessRegistrationNumber`	하이픈 없는 10자리 사업자등록번호
`organizationName`	상호명. 20자 이하
`representativeName`	대표자명. 10자 이하
`telephone`	`010-1234-5678`, `070-1234-5678` 형식, 유선번호(지역번호-3~4자리 국번-4자리) 또는 대표번호(15xx, 16xx, 18xx-4자리)

금액

amount의 각 항목은 9,999,999,999 이하로 입력하세요. 총액(supplyAmount + vatAmount + taxFreeAmount)도 9,999,999,999 이하여야 하며 0보다 커야 합니다.

필드	설명
`supplyAmount`	공급가액
`vatAmount`	부가세액
`taxFreeAmount`	면세금액(선택, 기본 0)

상태 조회

발행이나 취소 요청에 사용한 Bolta-Client-Reference-Id로 처리 상태를 조회합니다.

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

status로 성공과 실패를 판별하세요. 실패 사유는 failure에서 확인하세요.

status	의미
`PENDING`	접수 완료, 처리 시작 전
`REQUEST_SUCCESS`	요청 전달 완료. 최종 결과 아님
`ISSUED`	발행 성공
`CANCELED`	취소 성공
`EXTERNALLY_CANCELED`	볼타 외부에서 취소됨
`REQUEST_FAILURE`, `ISSUE_FAILED`, `CANCEL_FAILED`	실패(`failure` 확인)

발행에 성공하면 API가 현금영수증 승인번호(cashReceiptApprovalNumber)를 함께 반환합니다. LIVE 키에서 PENDING이나 REQUEST_SUCCESS가 이어져도 같은 요청을 다시 접수하지 마세요.

취소

발행 처리에 접수된 원본 현금영수증을 전액 취소합니다. 국세청 발급 확정 전에도 취소할 수 있습니다. 경로의 {issuanceKey}에 발행 응답으로 받은 issuanceKey를 입력하세요. 원본 요청이 PENDING 상태이면 취소할 수 없고, API가 409와 ORIGINAL_ISSUANCE_PENDING을 반환합니다. 원본 상태가 바뀐 뒤 다시 요청하세요. 같은 원본에 진행 중이거나 완료된 취소 요청이 있으면 409와 CANCELLATION_ALREADY_REQUESTED를 반환합니다. 새 요청자 관리번호로 보내도 응답은 같으니, 상태 조회로 기존 취소 결과를 확인하세요. 볼타 외부(예: 홈택스)에서 전액이나 일부가 먼저 취소된 원본을 취소해도 API는 요청을 접수하고 202 Accepted를 반환합니다. 이 취소 요청은 CANCEL_FAILED로 끝나고, 실패 코드는 CANCELLATION_TARGET_NOT_FOUND입니다. 실패 코드는 상태 조회의 failure.code나 웹훅의 data.cause.code에서 확인하세요. 원본이 이미 EXTERNALLY_CANCELED 상태여도 결과는 같습니다.

curl -X POST https://xapi.bolta.io/v1/cashReceipts/MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I/cancellation \
  -H "Authorization: Basic {apiKey}" \
  -H "Bolta-Client-Reference-Id: your-unique-reference-id-cancel"

취소 요청의 Bolta-Client-Reference-Id에는 발행 요청과 다른 값을 입력하세요.

실패 웹훅 재현(테스트)

테스트 키로 발행이나 취소를 호출할 때 Bolta-Webhook-Test-Code 헤더에 실패 코드를 입력하세요. API가 해당 실패 웹훅을 전송합니다.

-H "Bolta-Webhook-Test-Code: INVALID_RECIPIENT_IDENTIFIER"

실패 코드 목록은 에러 코드를 참고하세요.

API 소개

API 가이드

사용 사례

SDK/노코드 연동

처리 흐름

요금

발행

수취인 유형

공급자 정보

금액

상태 조회

취소

실패 웹훅 재현(테스트)

관련 문서

​처리 흐름

​요금

​발행

​수취인 유형

​공급자 정보

​금액

​상태 조회

​취소

​실패 웹훅 재현(테스트)

​관련 문서

처리 흐름

요금

발행

수취인 유형

공급자 정보

금액

상태 조회

취소

실패 웹훅 재현(테스트)

관련 문서