현금영수증 발행

처리 흐름

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

웹훅 - 등록한 URL로 결과 이벤트를 전송합니다. 실시간 처리에는 웹훅을 권장합니다.
상태 조회 API - Bolta-Client-Reference-Id로 현재 상태를 조회합니다.

202는 요청 접수를 뜻하며 발행·취소 성공을 보장하지 않습니다. 최종 결과를 반드시 웹훅이나 상태 조회 API로 확인하세요.

발행

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

현금영수증을 발행하려면 공급자 인증서를 먼저 등록하세요. 인증서가 없으면 발행이 실패합니다. 등록 방법은 인증서 등록 연동을 참고하세요.

헤더	필수	설명
`Authorization`	O	`Basic {apiKey}` 형식으로 입력하세요. 자세한 내용은 인증 가이드를 참고하세요
`Supplier-Key`	O	공급자 식별 키입니다. `issuer.businessRegistrationNumber`와 연결된 사업자의 키를 입력하세요
`Bolta-Client-Reference-Id`	O	요청자 관리번호이자 멱등키입니다. 1~255자로 입력하세요
`Bolta-Webhook-Test-Code`	X	테스트 키에서 실패 웹훅을 재현할 때만 입력하세요

curl -X POST https://xapi.bolta.io/v1/cashReceipts \
  -H "Authorization: Basic {apiKey}" \
  -H "Supplier-Key: SupplierKey_bf8paz" \
  -H "Bolta-Client-Reference-Id: your-unique-reference-id" \
  -H "Content-Type: application/json" \
  -d '{
    "itemName": "서비스 이용료",
    "issuer": {
      "businessRegistrationNumber": "5648102684",
      "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": "1234567890" }

SELF에는 value를 입력하지 마세요. PHONE과 BUSINESS_REGISTRATION_NUMBER에는 올바른 value가 필요합니다.

공급자 정보

issuer.businessRegistrationNumber에는 Supplier-Key에 연결된 사업자등록번호를 입력하세요.

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

금액

amount의 각 항목은 9,999,999,999 이하로 입력하세요. 총액(supplyAmount + vatAmount + taxFreeAmount)도 9,999,999,999 이하여야 하며 0보다 커야 합니다. taxFreeAmount를 생략하면 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)를 함께 반환합니다.

취소

발행이 완료된 현금영수증을 전액 취소합니다. 부분 취소는 지원하지 않습니다. 경로의 {issuanceKey}에 발행 응답으로 받은 issuanceKey를 입력하세요.

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

취소 요청의 Bolta-Client-Reference-Id에는 발행 요청과 다른 값을 입력하세요. 최종 결과는 웹훅이나 상태 조회 API로 확인하세요.

실패 웹훅 재현(테스트)

테스트 키로 발행·취소를 호출할 때 Bolta-Webhook-Test-Code 헤더에 실패 코드를 입력하세요. API가 해당 실패 웹훅을 전송합니다. 운영(라이브) 환경에서는 사용하지 마세요.

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

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

API 소개

API 가이드

사용 사례

SDK/노코드 연동

처리 흐름

발행

수취인 유형

공급자 정보

금액

상태 조회

취소

실패 웹훅 재현(테스트)

관련 문서

​처리 흐름

​발행

​수취인 유형

​공급자 정보

​금액

​상태 조회

​취소

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

​관련 문서

처리 흐름

발행

수취인 유형

공급자 정보

금액

상태 조회

취소

실패 웹훅 재현(테스트)

관련 문서