# 웹훅 이벤트

홈택스 현금영수증 수집에서 발생하는 웹훅 이벤트입니다.\
팝빌은 홈택스에서 수집한 현금영수증 매입/매출 내역을 매일 오전 8시에 고객사 서버로 자동 전달합니다.

> 홈택스수집 Webhook 실행은 파트너 센터(1600-8536)로 연락하여 홈택스 수집정보를 설정한 이후 이용 가능합니다.\
> 실제 고객사 서버로 전송된 웹훅 이벤트 정보는 [\[Webhook 실행내역 확인\]](https://developers.popbill.com/reference/htcashbill/node/webhook/introduction#check) 을 참고하여 주시기 바랍니다.

## 1. 웹훅 헤더

|  순번 | 변수명                |  필수 | 설명                     | 예시                                         |
| :-: | ------------------ | :-: | ---------------------- | ------------------------------------------ |
|  1  | Pb-Webhook-Type    |  Y  | Webhook 유형             | HT.CASHBILL                                |
|  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 인증 사용하는 경우 추가 항목         |

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

## 2. 홈택스수집

홈택스에서 수집한 현금영수증 매입/매출 내역을 전달할 때 발생하는 웹훅 이벤트입니다.\
각 이벤트 발생시점은 [\[수집 프로세스\]](https://developers.popbill.com/guide/htcashbill/introduction/collect#process) 에서 확인 가능합니다.

| 이벤트 유형                                                                                                                    | 설명               |
| ------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| [HT.CASHBILL](https://developers.popbill.com/reference/htcashbill/node/webhook/webhook-event#htcashbill-state-htcashbill) | 현금영수증 매입/매출 내역수집 |

### HT.CASHBILL - 현금영수증 매입/매출 내역수집

팝빌이 업데이트된 데이터를 수집하여 등록된 콜백 URL에 매일 오전 8시에 자동 전달하는 시점에 실행됩니다.

**이벤트 본문**

- ntsconfirmNum `type: string` `length: 9` `required: Y` `description: 국세청승인번호`
- tradeDate `type: string` `length: 8` `required: Y` `description: 거래일자`
  - 형식 : yyyyMMdd
- tradeDT `type: string` `length: 14` `required: Y` `description: 거래일시`
  - 형식 : yyyyMMddHHmmss
- tradeType `type: string` `length: 4` `required: Y` `description: 문서형태`
  - `승인거래`
  - `취소거래`
- tradeUsage `type: string` `length: 5` `required: Y` `description: 거래구분`
  - `소득공제용`
  - `지출증빙용`
- totalAmount `type: string` `length: 9` `required: Y` `description: 거래금액`
- supplyCost `type: string` `length: 9` `required: Y` `description: 공급가액`
- tax `type: string` `length: 9` `required: Y` `description: 부가세`
- serviceFee `type: string` `length: 9` `required: Y` `description: 봉사료`
- invoiceType `type: string` `length: 2` `required: Y` `description: 현금영수증 유형`
  - `매입`
  - `매출`
- franchiseCorpNum `type: string` `length: 10` `required: N` `description: 가맹점(발행자) 사업자번호`
  - {invoiceType}="매입" 경우 반환
- franchiseCorpName `type: string` `length: 200` `required: N` `description: 가맹점(발행자) 상호`
  - {invoiceType}="매입" 경우 반환
- franchiseCorpType `type: number` `length: 1` `required: N` `description: 가맹점(발행자) 사업자유형`
  - `1`: 일반과세자
  - `2`: 간이과세자
  - `3`: 과세특례자
  - `4`: 면세사업자
  - `5`: 법인사업자
  - {invoiceType}="매입" 경우 반환
- identityNum `type: string` `length: 4` `required: N` `description: 식별번호`
  - 식별번호의 마지막 4자리 숫자만 반환
- identityNumType `type: number` `length: 1` `required: Y` `description: 식별번호 유형`
  - `1`: 주민등록번호
  - `2`: 사업자번호
  - `3`: 휴대폰번호
  - `4`: 신용카드번호
- customerName `type: string` `length: 70` `required: N` `description: 구매자(고객) 성명`
- cardOwnerName `type: string` `length: 70` `required: N` `description: 카드소유자명`
- deductionType `type: number` `length: 1` `required: N` `description: 공제유형`
  - `1`: 공제
  - `2`: 공제
  - `3`: 불공제
  - `4`: 불공제

**이벤트 예시**

```json
{
        "ntsconfirmNum": "K00178490",
        "tradeDate": "20221019",
        "tradeDT": "20221019000000",
        "tradeType": "승인거래",
        "tradeUsage": "소득공제용",
        "totalAmount": "5000",
        "supplyCost": "4545",
        "tax": "455",
        "serviceFee": "0",
        "invoiceType": "매출",
        "franchiseCorpNum": "6798700433",
        "franchiseCorpType": 0,
        "identityNumType": 3,
        "identityNum": "5117",
        "customerName": "홍길동",
        "deductionType": 0
    }
```