# 웹훅 이벤트

현금영수증에서 발생하는 웹훅 이벤트입니다.

> 실제 고객사 서버로 전송된 웹훅 이벤트 정보는 [\[Webhook 실행내역 확인\]](https://developers.popbill.com/reference/cashbill/dotnet/webhook/introduction#check) 을 참고하여 주시기 바랍니다.

## 1. 웹훅 헤더

|  순번 | 변수명                  |  필수 | 설명                     | 예시                                         |
| :-: | -------------------- | :-: | ---------------------- | ------------------------------------------ |
|  1  | Pb-Webhook-Type      |  Y  | Webhook 유형             | CASHBILL.STATE                             |
|  2  | Pb-Webhook-MID       |  Y  | 이벤트 식별값                | 016120000002-1777d55c2c41492ab06826d       |
|  3  | Pb-Webhook-Corpnum   |  Y  | 팝빌 사업자번호               | 6798700433                                 |
|  4  | Content-Type         |  Y  | Webhook 메시지 Body 타입    | application/json                           |
|  5  | Authorization        |  N  | Base64 인코딩한 BASIC 인증정보 | Basic VEVTVDoxMjM= → HTTP 인증 사용하는 경우 추가 항목 |
|  6  | X-Api-Key            |  N  | API Key 인증정보           | TESTAPIKEY → HTTP 인증 사용하는 경우 추가 항목         |
|  7  | Pb-Webhook-EventType |  N  | Webhook 메시지 Event 타입   | Issue                                      |

> 팝빌은 기본으로 제공되는 Header 필드 외 프로그램 공급사 운영환경에 맞춘 커스텀 필드 지원이 가능합니다.\
> 커스텀 필드 추가가 필요한 경우 팝빌 기술지원센터(1600-9854)로 문의주시기 바랍니다.

## 2. 문서 상태 - 단건발행

현금영수증 단건발행에서 발생하는 웹훅 이벤트입니다.\
각 이벤트 발생시점은 [\[발행유형\]](https://developers.popbill.com/guide/cashbill/introduction/issue-type) 의 상태확인 내용에서 확인 가능합니다.

| 이벤트 유형                                                                                                              | 설명             |
| ------------------------------------------------------------------------------------------------------------------- | -------------- |
| [Issue](https://developers.popbill.com/reference/cashbill/dotnet/webhook/webhook-event#cashbill-state-single-issue) | 현금영수증 발행       |
| [NTS](https://developers.popbill.com/reference/cashbill/dotnet/webhook/webhook-event#cashbill-state-single-nts)     | 현금영수증 국세청 전송상태 |

> 팝빌 사이트에서 “Webhook 실행” 버튼을 클릭하여 웹훅을 전송하는 경우, eventType으로 “MANUAL”이 반환됩니다.

### Issue - 발행

가맹점이 현금영수증을 작성하여 발행을 완료한 시점에 실행됩니다.

**이벤트 본문**

- corpNum `type: string` `length: 10` `required: Y` `description: 팝빌회원 사업자번호 ('-' 제외)`
- franchiseCorpNum `type: string` `length: 10` `required: Y` `description: 가맹점 사업자번호`
  - 팝빌회원 사업자번호 ('-' 제외)
- itemKey `type: string` `length: 18` `required: Y` `description: 팝빌에서 현금영수증 관리 목적으로 할당한 식별번호`
- tradeDate `type: string` `length: 8` `required: Y` `description: 거래일자`
  - 형식 : yyyyMMdd
- confirmNum `type: string` `length: 9` `required: Y` `description: 국세청승인번호`
  - 현금영수증 발행 시점에 팝빌에서 자동으로 할당
- ntssendDT `type: string` `length: 14` `required: N` `description: 국세청 전송일시`
  - 형식 : yyyyMMddHHmmss
- ntsresultDT `type: string` `length: 14` `required: N` `description: 국세청 처리결과 수신일시`
  - 형식 : yyyyMMddHHmmss
- ntsresultCode `type: string` `length: 4` `required: N` `description: 국세청 결과코드`
  - [\[참고\] 국세청 결과코드](https://developers.popbill.com/reference/cashbill/dotnet/response-code#nts-result)
- stateCode `type: number` `length: 3` `required: Y` `description: 상태코드`
  - [\[참고\] 팝빌 상태코드](https://developers.popbill.com/reference/cashbill/dotnet/response-code#state-code)
- stateDT `type: string` `length: 14` `required: Y` `description: 상태 변경일시`
  - 형식 : yyyyMMddHHmmss
- issueDT `type: string` `length: 14` `required: Y` `description: 발행일시`
  - 형식 : yyyyMMddHHmmss
- mgtKey `type: string` `length: 24` `required: N` `description: 문서번호 파트너가 할당하는 식별번호`
- eventDT `type: string` `length: 14` `required: Y` `description: 이벤트 실행일시`
  - 형식 : yyyyMMddHHmmss
- eventType `type: string` `length: 30` `required: Y` `description: 이벤트 유형`
  - `Issue`
  - `NTS`
- interOPYN `type: boolean` `length: -` `required: Y` `description: 연동문서 여부`
  - `true`: API를 통해 발행한 연동문서
  - `false`: 팝빌 사이트를 통해 발행한 문서

**이벤트 예시**

```json
{
    "corpNum": "1234567890",
    "franchiseCorpNum": "1234567890",
    "itemKey": "022122116193800001",
    "tradeDate": "20221221",
    "confirmNum": "TB0001147",
    "stateCode": 300,
    "stateDT": "20221221161938",
    "issueDT": "20221221161938",
    "mgtKey": "2021121-002",
    "eventDT": "20221221161938",
    "eventType": "Issue",
    "interOPYN": true
}
```

### NTS - 국세청 전송상태

현금영수증의 국세청 전송완료(stateCode : 304), 전송실패(stateCode : 305) 시점에 실행됩니다.

**이벤트 본문**

- corpNum `type: string` `length: 10` `required: Y` `description: 팝빌회원 사업자번호 ('-' 제외)`
- franchiseCorpNum `type: string` `length: 10` `required: Y` `description: 가맹점 사업자번호`
  - 팝빌회원 사업자번호 ('-' 제외)
- itemKey `type: string` `length: 18` `required: Y` `description: 팝빌에서 현금영수증 관리 목적으로 할당한 식별번호`
- tradeDate `type: string` `length: 8` `required: Y` `description: 거래일자`
  - 형식 : yyyyMMdd
- confirmNum `type: string` `length: 9` `required: Y` `description: 국세청승인번호`
  - 현금영수증 발행 시점에 팝빌에서 자동으로 할당
- ntssendDT `type: string` `length: 14` `required: N` `description: 국세청 전송일시`
  - 형식 : yyyyMMddHHmmss
- ntsresultDT `type: string` `length: 14` `required: N` `description: 국세청 처리결과 수신일시`
  - 형식 : yyyyMMddHHmmss
- ntsresultCode `type: string` `length: 4` `required: N` `description: 국세청 결과코드`
  - [\[참고\] 국세청 결과코드](https://developers.popbill.com/reference/cashbill/dotnet/response-code#nts-result)
- stateCode `type: number` `length: 3` `required: Y` `description: 상태코드`
  - [\[참고\] 팝빌 상태코드](https://developers.popbill.com/reference/cashbill/dotnet/response-code#state-code)
- stateDT `type: string` `length: 14` `required: Y` `description: 상태 변경일시`
  - 형식 : yyyyMMddHHmmss
- issueDT `type: string` `length: 14` `required: Y` `description: 발행일시`
  - 형식 : yyyyMMddHHmmss
- mgtKey `type: string` `length: 24` `required: N` `description: 문서번호 파트너가 할당하는 식별번호`
- eventDT `type: string` `length: 14` `required: Y` `description: 이벤트 실행일시`
  - 형식 : yyyyMMddHHmmss
- eventType `type: string` `length: 30` `required: Y` `description: 이벤트 유형`
  - `Issue`
  - `NTS`
- interOPYN `type: boolean` `length: -` `required: Y` `description: 연동문서 여부`
  - `true`: API를 통해 발행한 연동문서
  - `false`: 팝빌 사이트를 통해 발행한 문서

**이벤트 예시**

```json
{
    "corpNum": "1234567890",
    "franchiseCorpNum": "1234567890",
    "itemKey": "022122116191200001",
    "tradeDate": "20221221",
    "confirmNum": "TB0001146",
    "ntssendDT": "20221222000000",
    "ntsresultDT": "20221222100033",
    "ntsresultCode": "0000",
    "stateCode": 304,
    "stateDT": "20221221161912",
    "issueDT": "20221221161912",
    "mgtKey": "20221221-001",
    "eventDT": "20221222100033",
    "eventType": "NTS",
    "interOPYN": true
}
```

## 3. 문서 상태 - 대량발행

현금영수증 대량발행에서 발생하는 웹훅 이벤트입니다.\
각 이벤트 발생시점은 [\[발행유형\]](https://developers.popbill.com/guide/cashbill/introduction/issue-type) 의 상태확인 내용에서 확인 가능합니다.

| 이벤트 유형                                                                                                                   | 설명                |
| ------------------------------------------------------------------------------------------------------------------------ | ----------------- |
| [BULK.RESULT](https://developers.popbill.com/reference/cashbill/dotnet/webhook/webhook-event#cashbill-state-bulk-result) | 현금영수증 대량발행 접수결과   |
| [NTS](https://developers.popbill.com/reference/cashbill/dotnet/webhook/webhook-event#cashbill-state-bulk-nts)            | 현금영수증 국세청 전송 처리결과 |

> 팝빌 사이트에서 “Webhook 실행” 버튼을 클릭하여 웹훅을 전송하는 경우, eventType으로 “MANUAL”이 반환됩니다.

### BULK.RESULT - 접수결과

가맹점이 현금영수증을 대량 접수 완료한 시점에 실행됩니다.

**이벤트 본문**

- corpNum `type: string` `length: 10` `required: Y` `description: 팝빌회원 사업자번호 ('-' 제외)`
- franchiseCorpNum `type: string` `length: 10` `required: Y` `description: 현금영수증 대량 접수 시 입력한 사업자번호`
- submitID `type: string` `length: 36` `required: Y` `description: 접수 시점에 고객사에서 할당한 제출아이디`
- receiptID `type: string` `length: 36` `required: Y` `description: 접수 아이디`
  - 접수 시점에 팝빌에서 자동으로 할당
- receiptDT `type: string` `length: 14` `required: Y` `description: 접수일시`
  - 형식 : yyyyMMddHHmmss
- eventType `type: string` `length: -` `required: Y` `description: 이벤트 유형`
  - `BULK.RESULT`
- eventDT `type: string` `length: 14` `required: Y` `description: 이벤트 실행 일시`
  - 형식 : yyyyMMddHHmmss
- submitCount `type: number` `length: -` `required: Y` `description: 현금영수증 접수 건수`
- successCount `type: number` `length: -` `required: Y` `description: 현금영수증 발행 성공 건수`
- failCount `type: number` `length: -` `required: Y` `description: 현금영수증 발행 실패 건수`
- txState `type: number` `length: 1` `required: Y` `description: 접수상태`
  - `0`: 접수
  - `1`: 처리중
  - `2`: 처리완료
- txResultCode `type: number` `length: -` `required: N` `description: 접수 결과코드`
  - 성공 : 1
  - 실패 : 음의 정수 8자리 숫자값 [\[참고\] 오류코드](https://developers.popbill.com/error-code)
- txStartDT `type: string` `length: 14` `required: N` `description: 발행처리 시작일시`
  - 형식 : yyyyMMddHHmmss
- txEndDT `type: string` `length: 14` `required: N` `description: 발행처리 완료일시`
  - 형식 : yyyyMMddHHmmss
- issueResult `type: array` `length: 100` `required: N` `description: 접수된 현금영수증 발행 결과`
  - code `type: number` `length: -` `required: Y` `description: API 처리에 대한 응답코드`
    - 성공 : 1
    - 실패 : 음의 정수 8자리 숫자값 [\[참고\] 오류코드](https://developers.popbill.com/error-code)
  - message `type: string` `length: -` `required: N` `description: API처리에 대한 응답 메시지`
  - confirmNum `type: string` `length: 9` `required: N` `description: 국세청승인번호`
    - 현금영수증 발행 시점에 팝빌에서 자동으로 할당
  - tradeDate `type: string` `length: 8` `required: N` `description: 거래일자`
    - 형식 : yyyyMMdd
  - issueDT `type: string` `length: 14` `required: N` `description: 발행일시`
    - 형식 : yyyyMMddHHmmss
  - mgtKey `type: string` `length: 24` `required: N` `description: 문서번호 파트너가 할당한 문서번호`

**이벤트 예시**

```json
{
    "corpNum": "1234567890",
    "franchiseCorpNum": "1234567890",
    "submitID": "20221221-BULK",
    "receiptID": "0221222-0ffafb03af714057b7a77658fc75",
    "receiptDT": "20221222100306",
    "eventType": "BULK.RESULT",
    "eventDT": "20221222100306",
    "submitCount": 2,
    "successCount": 2,
    "failCount": 0,
    "txState": 2,
    "txResultCode": 1,
    "txStartDT": "20221222100306",
    "txEndDT": "20221222100306",
    "issueResult": [
        {
            "code": 1,
            "confirmNum": "TB0000023",
            "tradeDate": "20221222",
            "issueDT": "20221222100306",
            "mgtKey": "20221221-BULK~,-_1"
        }
    ]
}
```

### NTS - 국세청 전송 처리결과

대량 접수된 현금영수증 국세청 전송처리 완료 시점에 처리된 순서대로 최대 500건씩 리스트로 묶여 실행 됩니다.

**이벤트 본문**

- header `type: object` `length: -` `required: Y` `description: header`
  - QMNum `type: string` `length: 24` `required: Y` `description: 팝빌이 생성한 현금영수증 국세청 신고를 위한 고유번호`
  - CORPNUM `type: string` `length: 10` `required: Y` `description: 현금영수증 대량 접수 시 입력한 사업자번호`
  - TYPE `type: string` `length: -` `required: Y` `description: Webhook 유형`
    - `CASHBILL.STATE`
- body `type: object` `length: -` `required: Y` `description: body`
  - corpNum `type: string` `length: 10` `required: Y` `description: 현금영수증 대량 접수 시 입력한 사업자번호`
  - itemKey `type: string` `length: 18` `required: Y` `description: 팝빌에서 현금영수증 관리 목적으로 할당한 식별번호`
  - confirmNum `type: string` `length: 9` `required: Y` `description: 국세청승인번호`
    - 현금영수증 발행 시점에 팝빌에서 자동으로 할당
  - ntssendDT `type: string` `length: 14` `required: N` `description: 국세청 전송일시`
    - 형식 : yyyyMMddHHmmss
  - ntsresultDT `type: string` `length: 14` `required: N` `description: 국세청 결과 수신일시`
    - 형식 : yyyyMMddHHmmss
  - ntsresultCode `type: string` `length: -` `required: N` `description: 국세청 결과코드`
    - [\[참고\] 국세청 결과코드](https://developers.popbill.com/reference/cashbill/dotnet/response-code#nts-result)
  - stateCode `type: number` `length: 3` `required: Y` `description: 상태코드`
    - [\[참고\] 팝빌 상태코드](https://developers.popbill.com/reference/cashbill/dotnet/response-code#state-code)
  - stateDT `type: string` `length: 14` `required: Y` `description: 상태 변경일시`
    - 형식 : yyyyMMddHHmmss
  - issueDT `type: string` `length: 14` `required: Y` `description: 발행일시`
    - 형식 : yyyyMMddHHmmss
  - mgtKey `type: string` `length: 24` `required: N` `description: 문서번호 파트너가 할당한 문서번호`
  - eventDT `type: string` `length: 14` `required: Y` `description: 이벤트 실행일시`
    - 형식 : yyyyMMddHHmmss
  - eventType `type: string` `length: 30` `required: Y` `description: 이벤트 유형`
    - `NTS`
  - interOPYN `type: boolean` `length: -` `required: Y` `description: 연동문서 여부`
    - `true`: API로 발행한 연동문서
    - `false`: 팝빌 사이트에서 발행한 일반문서

**이벤트 예시**

```json
[
    {
        "header": {
            "QMNum": "TB0000045",
            "CORPNUM": "1234567890",
            "TYPE": "CASHBILL.STATE"
        },
        "body": {
            "corpNum": "1234567890",
            "itemKey": "022110814151400002",
            "confirmNum": "TB0000045",
            "ntssendDT": "20221109000207",
            "ntsresultDT": "20221109100017",
            "ntsresultCode": "0000",
            "ntsresultMessage": "더미승인",
            "stateCode": 304,
            "stateDT": "20221108141514",
            "issueDT": "20221108141514",
            "mgtKey": "20221108-JSP-BULK-2",
            "eventDT": "20221109100017",
            "eventType": "NTS",
            "interOPYN": true
        }
    }
]
```