# 웹훅 이벤트

홈택스 전자세금계산서 수집에서 발생하는 웹훅 이벤트입니다.\
팝빌은 홈택스에서 수집한 전자세금계산서 매입/매출 내역을 1시간 간격(정시)으로 고객사 서버로 자동 전달합니다.

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

## 1. 웹훅 헤더

|  순번 | 변수명                |  필수 | 설명                     | 예시                                         |
| :-: | ------------------ | :-: | ---------------------- | ------------------------------------------ |
|  1  | Pb-Webhook-Type    |  Y  | Webhook 유형             | HT.TAXINVOICEXML                           |
|  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/httaxinvoice/introduction/collect#process) 에서 확인 가능합니다.

| 이벤트 유형                                                                                                                              | 설명                 |
| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| [HT.TAXINVOICEXML](https://developers.popbill.com/reference/httaxinvoice/asp/webhook/webhook-event#httaxinvoice-state-httaxinvoice) | 전자세금계산서 매입/매출 내역수집 |

### HT.TAXINVOICEXML - 전자세금계산서 매입/매출 내역수집

팝빌이 업데이트된 데이터를 수집하여 등록된 콜백 URL에 1시간(정시) 간격으로 자동 전달하는 시점에 실행됩니다.

**이벤트 본문**

- writeDate `type: string` `length: 8` `required: Y` `description: 작성일자`
  - 형식 : yyyyMMdd
- ntsconfirmNum `type: string` `length: 24` `required: Y` `description: 국세청승인번호`
- issueDT `type: string` `length: 14` `required: Y` `description: 발행일시`
  - 형식 : yyyyMMddHHmmss
- sendDate `type: string` `length: 8` `required: Y` `description: 전송일자`
  - 형식 : yyyyMMdd
- invoiceType `type: number` `length: 3` `required: Y` `description: 전자세금계산서 종류`
  - `101`: 세금계산서
  - `102`: 영세율 세금계산서
  - `103`: 위수탁 세금계산서
  - `104`: 수입 세금계산서
  - `105`: 위수탁영세율 세금계산서
  - `201`: 수정세금계산서
  - `202`: 영세율 수정세금계산서
  - `203`: 위수탁 수정세금계산서
  - `204`: 수입 수정세금계산서
  - `205`: 위수탁영세율 수정세금계산서
  - `301`: 계산서
  - `303`: 위수탁 계산서
  - `304`: 수입 계산서
  - `401`: 수정계산서
  - `403`: 위수탁 수정계산서
  - `404`: 수입 수정계산서
- taxType `type: string` `length: 2` `required: Y` `description: 과세형태`
  - `과세`
  - `영세`
  - `면세`
- taxTotal `type: string` `length: 18` `required: Y` `description: 세액 합계`
- supplyCostTotal `type: string` `length: 18` `required: Y` `description: 공급가액 합계`
- totalAmount `type: string` `length: 18` `required: Y` `description: 합계금액`
- purposeType `type: string` `length: 2` `required: Y` `description: 영수/청구`
  - `영수`
  - `청구`
  - `없음`
- serialNum `type: string` `length: 30` `required: N` `description: 일련번호`
- cash `type: string` `length: 18` `required: N` `description: 현금`
- chkBill `type: string` `length: 18` `required: N` `description: 수표`
- credit `type: string` `length: 18` `required: N` `description: 외상`
- note `type: string` `length: 18` `required: N` `description: 어음`
- remark1 `type: string` `length: 150` `required: 조건부` `description: 비고1`
- remark2 `type: string` `length: 150` `required: N` `description: 비고2`
- remark3 `type: string` `length: 150` `required: N` `description: 비고3`
- invoicerCorpNum `type: string` `length: 10` `required: Y` `description: 공급자 사업자번호`
- invoicerMgtKey `type: string` `length: 24` `required: 조건부` `description: 공급자 문서번호`
- invoicerTaxRegID `type: string` `length: 4` `required: N` `description: 공급자 종사업장 식별번호`
  - 종사업장 식별번호는 4자리 숫자로만 구성
- invoicerCorpName `type: string` `length: 200` `required: Y` `description: 공급자 상호`
- invoicerCEOName `type: string` `length: 100` `required: Y` `description: 공급자 대표자 성명`
- invoicerAddr `type: string` `length: 300` `required: N` `description: 공급자 주소`
- invoicerBizType `type: string` `length: 100` `required: N` `description: 공급자 업태`
- invoicerBizClass `type: string` `length: 100` `required: N` `description: 공급자 종목`
- invoicerContactName `type: string` `length: 100` `required: N` `description: 공급자 담당자 성명`
- invoicerDeptName `type: string` `length: 100` `required: N` `description: 공급자 담당자 부서명`
- invoicerTEL `type: string` `length: 20` `required: N` `description: 공급자 담당자 연락처`
- invoicerEmail `type: string` `length: 100` `required: N` `description: 공급자 담당자 메일`
- invoiceeCorpNum `type: string` `length: 13` `required: Y` `description: 공급받는자 사업자번호`
- invoiceeType `type: string` `length: 3` `required: Y` `description: 공급받는자 유형`
  - `사업자`
  - `개인`
  - `외국인`
- invoiceeMgtKey `type: string` `length: 24` `required: 조건부` `description: 공급받는자 문서번호`
- invoiceeTaxRegID `type: string` `length: 4` `required: N` `description: 공급받는자 종사업장 식별번호`
  - 종사업장 식별번호는 4자리 숫자로만 구성
- invoiceeCorpName `type: string` `length: 200` `required: Y` `description: 공급받는자 상호`
- invoiceeCEOName `type: string` `length: 100` `required: Y` `description: 공급받는자 대표자 성명`
- invoiceeAddr `type: string` `length: 300` `required: N` `description: 공급받는자 주소`
- invoiceeBizType `type: string` `length: 100` `required: N` `description: 공급받는자 업태`
- invoiceeBizClass `type: string` `length: 100` `required: N` `description: 공급받는자 종목`
- invoiceeContactName1 `type: string` `length: 100` `required: N` `description: 공급받는자 주)담당자 성명`
- invoiceeDeptName1 `type: string` `length: 100` `required: N` `description: 공급받는자 주)담당자 부서명`
- invoiceeTEL1 `type: string` `length: 20` `required: N` `description: 공급받는자 주)담당자 연락처`
- invoiceeEmail1 `type: string` `length: 100` `required: N` `description: 공급받는자 주)담당자 메일`
- invoiceeContactName2 `type: string` `length: 100` `required: N` `description: 공급받는자 부)담당자 성명`
- invoiceeDeptName2 `type: string` `length: 100` `required: N` `description: 공급받는자 부)담당자 부서명`
- invoiceeTEL2 `type: string` `length: 20` `required: N` `description: 공급받는자 부)담당자 연락처`
- invoiceeEmail2 `type: string` `length: 100` `required: N` `description: 공급받는자 부)담당자 메일`
- trusteeCorpNum `type: string` `length: 10` `required: 조건부` `description: 수탁자 사업자번호`
- trusteeMgtKey `type: string` `length: 24` `required: 조건부` `description: 수탁자 문서번호`
- trusteeTaxRegID `type: string` `length: 4` `required: N` `description: 수탁자 종사업장번호`
  - 종사업장 식별번호는 4자리 숫자로만 구성
- trusteeCorpName `type: string` `length: 200` `required: 조건부` `description: 수탁자 상호`
- trusteeCEOName `type: string` `length: 100` `required: 조건부` `description: 수탁자 대표자 성명`
- trusteeAddr `type: string` `length: 300` `required: N` `description: 수탁자 주소`
- trusteeBizType `type: string` `length: 100` `required: N` `description: 수탁자 업태`
- trusteeBizClass `type: string` `length: 100` `required: N` `description: 수탁자 종목`
- trusteeContactName `type: string` `length: 100` `required: N` `description: 수탁자 담당자 성명`
- trusteeDeptName `type: string` `length: 100` `required: N` `description: 수탁자 담당자 부서명`
- trusteeTEL `type: string` `length: 20` `required: N` `description: 수탁자 담당자 연락처`
- trusteeEmail `type: string` `length: 100` `required: N` `description: 수탁자 담당자 메일`
- modifyCode `type: number` `length: 1` `required: 조건부` `description: 수정 사유코드`
  - `1`: 기재사항 착오정정
  - `2`: 공급가액 변동
  - `3`: 환입
  - `4`: 계약의 해지
  - `5`: 내국신용장 사후개설
  - `6`: 착오에 의한 이중발행
- orgNTSConfirmNum `type: string` `length: 24` `required: 조건부` `description: 당초 국세청승인번호`
- detailList `type: array` `length: 99` `required: N` `description: 품목 상세정보`
  - serialNum `type: number` `length: 2` `required: Y` `description: 일련번호`
  - purchaseDT `type: string` `length: 8` `required: N` `description: 거래일자`
    - 형식 : yyyyMMdd
  - itemName `type: string` `length: 100` `required: N` `description: 품명`
  - spec `type: string` `length: 60` `required: N` `description: 규격`
  - qty `type: string` `length: 12` `required: N` `description: 수량`
  - unitCost `type: string` `length: 18` `required: N` `description: 단가`
  - supplyCost `type: string` `length: 18` `required: N` `description: 공급가액`
  - tax `type: string` `length: 18` `required: N` `description: 세액`
  - remark `type: string` `length: 100` `required: N` `description: 비고`

**이벤트 예시**

```json
{
    "writeDate": "20221111",
    "sendDate": "20221111",
    "issueDT": "20221111112809",
    "invoiceType": 101,
    "taxType": "과세",
    "invoicerCorpNum": "6798700433",
    "invoicerCorpName": "(주)링크허브",
    "invoicerCEOName": "공급자 대표",
    "invoicerAddr": "공급자 주소",
    "invoicerBizType": "공급자 업태",
    "invoicerBizClass": "공급자  종목",
    "invoicerContactName": "공급자  담당자 성명",
    "invoicerTEL": "공급자 담당자 연락처",
    "invoicerEmail": "공급자 담당자 메일",
    "invoiceeCorpNum": "1234567890",
    "invoiceeType": "사업자",
    "invoiceeCorpName": "공급받는자 사업자",
    "invoiceeCEOName": "공급받는자 대표",
    "invoiceeAddr": "공급받는자 주소",
    "invoiceeBizType": "공급받는자 업태",
    "invoiceeBizClass": "공급받는자 종목",
    "invoiceeContactName1": "공급받는자 담당자 성명",
    "invoiceeEmail1": "공급받는자 담당자 메일",
    "taxTotal": "20000",
    "supplyCostTotal": "200000",
    "totalAmount": "220000",
    "purposeType": "청구",
    "ntsconfirmNum": "202211114100020300000777",
    "detailList": [
        {
            "serialNum": 1,
            "purchaseDT": "20221111",
            "itemName": "테스트 결제",
            "supplyCost": "200000",
            "tax": "20000"
        }
    ]
}
```