> ## 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.

# 현금영수증 웹훅

> 현금영수증 발행·취소 결과 웹훅의 이벤트 타입, 페이로드, 발송 시점을 안내합니다.

전송 방식과 방화벽 설정, 로그 확인은 [웹훅 이벤트](/docs/api-introduction/webhook-events)를 참고하세요.

## 이벤트 타입

현금영수증 발행·취소는 비동기입니다. API가 최종 결과를 다음 이벤트로 전송합니다.

| 이벤트 타입                             | 설명                 |
| ---------------------------------- | ------------------ |
| `CASH_RECEIPT_ISSUED`              | 발행 성공              |
| `CASH_RECEIPT_ISSUE_FAILED`        | 발행 실패              |
| `CASH_RECEIPT_CANCELED`            | 취소 성공              |
| `CASH_RECEIPT_CANCEL_FAILED`       | 취소 실패              |
| `CASH_RECEIPT_EXTERNALLY_CANCELED` | 외부 취소(볼타 외부에서 취소됨) |

## 페이로드

### 발행 성공

```json theme={"dark"}
{
  "eventType": "CASH_RECEIPT_ISSUED",
  "data": {
    "issuanceKey": "MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I",
    "cashReceiptApprovalNumber": "123456789012"
  }
}
```

| 필드                               | 타입     | 설명         |
| -------------------------------- | ------ | ---------- |
| `eventType`                      | string | 이벤트 타입     |
| `data.issuanceKey`               | string | 발행 식별 키    |
| `data.cashReceiptApprovalNumber` | string | 현금영수증 승인번호 |

### 발행 실패

```json theme={"dark"}
{
  "eventType": "CASH_RECEIPT_ISSUE_FAILED",
  "data": {
    "issuanceKey": "MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I",
    "cause": {
      "code": "INVALID_RECIPIENT_IDENTIFIER",
      "message": "현금영수증 발급 수단 정보를 확인해주세요."
    }
  }
}
```

| 필드                   | 타입     | 설명       |
| -------------------- | ------ | -------- |
| `eventType`          | string | 이벤트 타입   |
| `data.issuanceKey`   | string | 발행 식별 키  |
| `data.cause.code`    | string | 실패 코드    |
| `data.cause.message` | string | 실패 사유 설명 |

### 취소 성공

```json theme={"dark"}
{
  "eventType": "CASH_RECEIPT_CANCELED",
  "data": {
    "issuanceKey": "9XK21ABC5KOAEIPGK8U6UO05I3EAQPLI8OE78Z1Q",
    "originalIssuanceKey": "MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I"
  }
}
```

| 필드                         | 타입     | 설명              |
| -------------------------- | ------ | --------------- |
| `eventType`                | string | 이벤트 타입          |
| `data.issuanceKey`         | string | 취소 요청의 식별 키     |
| `data.originalIssuanceKey` | string | 취소된 원본의 발행 식별 키 |

### 취소 실패

```json theme={"dark"}
{
  "eventType": "CASH_RECEIPT_CANCEL_FAILED",
  "data": {
    "issuanceKey": "9XK21ABC5KOAEIPGK8U6UO05I3EAQPLI8OE78Z1Q",
    "originalIssuanceKey": "MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I",
    "cause": {
      "code": "ORIGINAL_ISSUANCE_FAILED",
      "message": "원본 현금영수증 발행이 실패해 취소 요청을 처리할 수 없습니다."
    }
  }
}
```

| 필드                         | 타입     | 설명                |
| -------------------------- | ------ | ----------------- |
| `eventType`                | string | 이벤트 타입            |
| `data.issuanceKey`         | string | 취소 요청의 식별 키       |
| `data.originalIssuanceKey` | string | 취소 대상 원본의 발행 식별 키 |
| `data.cause.code`          | string | 실패 코드             |
| `data.cause.message`       | string | 실패 사유 설명          |

### 외부 취소

발행된 현금영수증이 볼타 외부(예: 홈택스)에서 취소되면 이 이벤트를 전송합니다.

```json theme={"dark"}
{
  "eventType": "CASH_RECEIPT_EXTERNALLY_CANCELED",
  "data": {
    "issuanceKey": "MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I"
  }
}
```

| 필드                 | 타입     | 설명                      |
| ------------------ | ------ | ----------------------- |
| `eventType`        | string | 이벤트 타입                  |
| `data.issuanceKey` | string | 외부에서 취소된 현금영수증의 발행 식별 키 |

## 웹훅 발송 시간

발송 시점은 이벤트에 따라 다릅니다. 현금영수증 발행 내역은 홈택스에 다음 날 반영되므로, 발행 성공 웹훅은 다음 날 전송합니다.

| 이벤트                                                   | 발송 시점                                          |
| ----------------------------------------------------- | ---------------------------------------------- |
| `CASH_RECEIPT_ISSUED`                                 | 발행 요청 다음 날 17시(KST) 이후                         |
| `CASH_RECEIPT_ISSUE_FAILED`                           | 발행 실패가 확정되면 바로                                 |
| `CASH_RECEIPT_CANCELED`, `CASH_RECEIPT_CANCEL_FAILED` | 취소 결과가 확정되면 바로. 취소가 처리중으로 남으면 다음 날 17시(KST) 이후 |
| `CASH_RECEIPT_EXTERNALLY_CANCELED`                    | 외부 취소를 확인한 시점. 발행 후 7일까지 확인합니다                 |

테스트 키(`test_`)는 발행을 가상으로 처리하며, 요청 접수 후 10초 뒤에 최종 웹훅을 전송합니다.

<Warning>
  `202 Accepted`는 요청 접수만 뜻합니다. `CASH_RECEIPT_ISSUED`를 받기 전까지 발행 미확정으로 처리하세요.
</Warning>

## 웹훅이 오지 않을 때

[현금영수증 발행 상태 조회](/api-reference/현금영수증/현금영수증-발행-상태-조회)로 확인하세요. 상태가 `PENDING`이나 `REQUEST_SUCCESS`면 결과가 아직 확정되지 않았습니다. `REQUEST_SUCCESS`는 요청 전달에 성공했다는 뜻이며 발행 성공이 아닙니다.