> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bolta.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 현금영수증 발행

> 현금영수증 발행·상태 조회·취소 API의 흐름과 입력 규칙을 안내합니다.

## 처리 흐름

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

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

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

## 발행

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

<Info>
  현금영수증을 발행하려면 공급자 인증서를 먼저 등록하세요. 인증서가 없으면 발행이 실패합니다. 등록 방법은 [인증서 등록 연동](/docs/api-introduction/certificate-registration)을 참고하세요.
</Info>

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

```bash theme={"dark"}
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`)를 반환합니다. 취소 요청에 사용할 수 있도록 저장하세요.

```json theme={"dark"}
{ "issuanceKey": "MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I" }
```

### 수취인 유형

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

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

```json theme={"dark"}
{ "type": "SELF" }
```

```json theme={"dark"}
{ "type": "PHONE", "value": "010-1234-5678" }
```

```json theme={"dark"}
{ "type": "BUSINESS_REGISTRATION_NUMBER", "value": "1234567890" }
```

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

### 공급자 정보

`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`로 처리 상태를 조회합니다.

```bash theme={"dark"}
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`를 입력하세요.

```bash theme={"dark"}
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"
```

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

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

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

```bash theme={"dark"}
-H "Bolta-Webhook-Test-Code: INVALID_RECIPIENT_IDENTIFIER"
```

실패 코드 목록은 [에러 코드](/docs/api-introduction/error-codes#현금영수증-웹훅)를 참고하세요.

## 관련 문서

* [웹훅 이벤트](/docs/api-introduction/webhook-events) - 현금영수증 결과 이벤트 페이로드
* [에러 코드](/docs/api-introduction/error-codes) - 현금영수증 실패 코드
* [인증 가이드](/docs/api-introduction/authentication) - `Authorization`·`Supplier-Key`·`Bolta-Client-Reference-Id`
* [API 문서](/api-reference/현금영수증/현금영수증-발행) - 요청·응답 스키마