현금영수증 발행

처리 흐름

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

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

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

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

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

최종 상태가 바뀐 뒤 결과 웹훅을 전송하므로, 17시 정각에 웹훅 수신까지 보장하지는 않습니다. 자세한 시점은 웹훅 발송 시간을 확인하세요.

발행

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" }

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

공급자 정보

필드	규칙
`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보다 커야 합니다. 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에서 확인하세요. TEST 키는 요청 처리 후 상태가 먼저 확정되고 자동 웹훅은 최소 10초 뒤에 올 수 있습니다.

status	의미
`PENDING`	요청을 접수했고 처리를 시작하기 전 상태. 같은 요청을 다시 보내지 않음
`REQUEST_SUCCESS`	요청 전달 완료. 최종 결과를 뜻하지 않음
`ISSUED`	발행 성공
`CANCELED`	취소 성공
`EXTERNALLY_CANCELED`	외부 취소(볼타 외부에서 취소됨)
`REQUEST_FAILURE`, `ISSUE_FAILED`, `CANCEL_FAILED`	실패(`failure` 확인)

발행에 성공하면 API가 현금영수증 승인번호(cashReceiptApprovalNumber)를 함께 반환합니다. LIVE 키에서 PENDING 또는 REQUEST_SUCCESS가 계속되더라도 바로 재접수하지 마세요. 처리 중이거나 발행 결과 확인이 필요한 요청은 요청일 다음 날 17:00(KST) 이후에 최종 상태가 확정될 수 있습니다. 최종 결과는 상태 조회나 웹훅으로 확인하세요.

취소

발행 처리에 접수된 원본 현금영수증을 전액 취소합니다. 국세청 발급 확정 전에도 취소할 수 있지만, 원본 요청이 PENDING 상태이면 취소할 수 없습니다. 부분 취소는 지원하지 않습니다. 경로의 {issuanceKey}에 발행 응답으로 받은 issuanceKey를 입력하세요.

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에는 발행 요청과 다른 값을 입력하세요. 최종 결과는 웹훅이나 상태 조회 API로 확인하세요.

실패 웹훅 재현(테스트)

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

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

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

API 소개

API 가이드

사용 사례

SDK/노코드 연동

처리 흐름

발행

수취인 유형

공급자 정보

금액

상태 조회

취소

실패 웹훅 재현(테스트)

관련 문서

​처리 흐름

​발행

​수취인 유형

​공급자 정보

​금액

​상태 조회

​취소

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

​관련 문서

처리 흐름

발행

수취인 유형

공급자 정보

금액

상태 조회

취소

실패 웹훅 재현(테스트)

관련 문서