웹훅 이벤트
현금영수증에서 발생하는 웹훅 이벤트입니다.
실제 고객사 서버로 전송된 웹훅 이벤트 정보는 [Webhook 실행내역 확인] 을 참고하여 주시기 바랍니다.
웹훅 헤더
| 순번 | 변수명 | 필수 | 설명 | 예시 |
|---|---|---|---|---|
| Pb-Webhook-Type | Y | Webhook 유형 | CASHBILL.STATE | |
| Pb-Webhook-MID | Y | 이벤트 식별값 | 016120000002-1777d55c2c41492ab06826d | |
| Pb-Webhook-Corpnum | Y | 팝빌 사업자번호 | 6798700433 | |
| Content-Type | Y | Webhook 메시지 Body 타입 | application/json | |
| Authorization | N | Base64 인코딩한 BASIC 인증정보 |
Basic VEVTVDoxMjM=
HTTP 인증 사용하는 경우 추가 항목
|
|
| X-Api-Key | N | API Key 인증정보 |
TESTAPIKEY
HTTP 인증 사용하는 경우 추가 항목
|
|
| Pb-Webhook-EventType | N | Webhook 메시지 Event 타입 | Issue |
팝빌은 기본으로 제공되는 Header 필드 외 프로그램 공급사 운영환경에 맞춘 커스텀 필드 지원이 가능합니다.
커스텀 필드 추가가 필요한 경우 팝빌 기술지원센터(1600-9854)로 문의주시기 바랍니다.
문서 상태 - 단건발행
현금영수증 단건발행에서 발생하는 웹훅 이벤트입니다.
각 이벤트 발생시점은 [발행유형]의 상태확인 내용에서 확인 가능합니다.
| 이벤트 유형 | 설명 |
|---|---|
| Issue | 현금영수증 발행 |
| NTS | 현금영수증 국세청 전송상태 |
팝빌 사이트에서 “Webhook 실행” 버튼을 클릭하여 웹훅을 전송하는 경우, eventType으로 “MANUAL”이 반환됩니다.
Issue - 발행
가맹점이 현금영수증을 작성하여 발행을 완료한 시점에 실행됩니다.
이벤트 본문
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| corpNum | string | 10 | Y | 팝빌회원 사업자번호 ('-' 제외) | |
| franchiseCorpNum | string | 10 | Y |
가맹점 사업자번호
팝빌회원 사업자번호 ('-' 제외)
|
|
| itemKey | string | 18 | Y | 팝빌에서 현금영수증 관리 목적으로 할당한 식별번호 | |
| tradeDate | string | 8 | Y |
거래일자
형식 : yyyyMMdd
|
|
| confirmNum | string | 9 | Y |
국세청승인번호
현금영수증 발행 시점에 팝빌에서 자동으로 할당
|
|
| ntssendDT | string | 14 | N |
국세청 전송일시
형식 : yyyyMMddHHmmss
|
|
| ntsresultDT | string | 14 | N |
국세청 처리결과 수신일시
형식 : yyyyMMddHHmmss
|
|
| ntsresultCode | string | 4 | N | 국세청 결과코드 | |
| stateCode | number | 3 | Y | 상태코드 | |
| stateDT | string | 14 | Y |
상태 변경일시
형식 : yyyyMMddHHmmss
|
|
| issueDT | string | 14 | Y |
발행일시
형식 : yyyyMMddHHmmss
|
|
| mgtKey | string | 24 | N |
문서번호
파트너가 할당하는 식별번호
|
|
| eventDT | string | 14 | Y |
이벤트 실행일시
형식 : yyyyMMddHHmmss
|
|
| eventType | string | 30 | Y |
이벤트 유형
Issue
NTS
|
|
| interOPYN | boolean | - | Y |
연동문서 여부
trueAPI를 통해 발행한 연동문서
false팝빌 사이트를 통해 발행한 문서
|
이벤트 예시
{
"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 | string | 10 | Y | 팝빌회원 사업자번호 ('-' 제외) | |
| franchiseCorpNum | string | 10 | Y |
가맹점 사업자번호
팝빌회원 사업자번호 ('-' 제외)
|
|
| itemKey | string | 18 | Y | 팝빌에서 현금영수증 관리 목적으로 할당한 식별번호 | |
| tradeDate | string | 8 | Y |
거래일자
형식 : yyyyMMdd
|
|
| confirmNum | string | 9 | Y |
국세청승인번호
현금영수증 발행 시점에 팝빌에서 자동으로 할당
|
|
| ntssendDT | string | 14 | N |
국세청 전송일시
형식 : yyyyMMddHHmmss
|
|
| ntsresultDT | string | 14 | N |
국세청 처리결과 수신일시
형식 : yyyyMMddHHmmss
|
|
| ntsresultCode | string | 4 | N | 국세청 결과코드 | |
| stateCode | number | 3 | Y | 상태코드 | |
| stateDT | string | 14 | Y |
상태 변경일시
형식 : yyyyMMddHHmmss
|
|
| issueDT | string | 14 | Y |
발행일시
형식 : yyyyMMddHHmmss
|
|
| mgtKey | string | 24 | N |
문서번호
파트너가 할당하는 식별번호
|
|
| eventDT | string | 14 | Y |
이벤트 실행일시
형식 : yyyyMMddHHmmss
|
|
| eventType | string | 30 | Y |
이벤트 유형
Issue
NTS
|
|
| interOPYN | boolean | - | Y |
연동문서 여부
trueAPI를 통해 발행한 연동문서
false팝빌 사이트를 통해 발행한 문서
|
이벤트 예시
{
"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
}문서 상태 - 대량발행
현금영수증 대량발행에서 발생하는 웹훅 이벤트입니다.
각 이벤트 발생시점은 [발행유형]의 상태확인 내용에서 확인 가능합니다.
| 이벤트 유형 | 설명 |
|---|---|
| BULK.RESULT | 현금영수증 대량발행 접수결과 |
| NTS | 현금영수증 국세청 전송 처리결과 |
팝빌 사이트에서 “Webhook 실행” 버튼을 클릭하여 웹훅을 전송하는 경우, eventType으로 “MANUAL”이 반환됩니다.
BULK.RESULT - 접수결과
가맹점이 현금영수증을 대량 접수 완료한 시점에 실행됩니다.
이벤트 본문
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 | ||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| corpNum | string | 10 | Y | 팝빌회원 사업자번호 ('-' 제외) | |||||||||||||||||||||||||||||||||||||||||||
| franchiseCorpNum | string | 10 | Y | 현금영수증 대량 접수 시 입력한 사업자번호 | |||||||||||||||||||||||||||||||||||||||||||
| submitID | string | 36 | Y | 접수 시점에 고객사에서 할당한 제출아이디 | |||||||||||||||||||||||||||||||||||||||||||
| receiptID | string | 36 | Y |
접수 아이디
접수 시점에 팝빌에서 자동으로 할당
|
|||||||||||||||||||||||||||||||||||||||||||
| receiptDT | string | 14 | Y |
접수일시
형식 : yyyyMMddHHmmss
|
|||||||||||||||||||||||||||||||||||||||||||
| eventType | string | - | Y |
이벤트 유형
BULK.RESULT
|
|||||||||||||||||||||||||||||||||||||||||||
| eventDT | string | 14 | Y |
이벤트 실행 일시
형식 : yyyyMMddHHmmss
|
|||||||||||||||||||||||||||||||||||||||||||
| submitCount | number | - | Y | 현금영수증 접수 건수 | |||||||||||||||||||||||||||||||||||||||||||
| successCount | number | - | Y | 현금영수증 발행 성공 건수 | |||||||||||||||||||||||||||||||||||||||||||
| failCount | number | - | Y | 현금영수증 발행 실패 건수 | |||||||||||||||||||||||||||||||||||||||||||
| txState | number | 1 | Y |
접수상태
0접수
1처리중
2처리완료
|
|||||||||||||||||||||||||||||||||||||||||||
| txResultCode | number | - | N |
접수 결과코드
- 성공 : 1 - 실패 : 음의 정수 8자리 숫자값 [참고] 오류코드 |
|||||||||||||||||||||||||||||||||||||||||||
| txStartDT | string | 14 | N |
발행처리 시작일시
형식 : yyyyMMddHHmmss
|
|||||||||||||||||||||||||||||||||||||||||||
| txEndDT | string | 14 | N |
발행처리 완료일시
형식 : yyyyMMddHHmmss
|
|||||||||||||||||||||||||||||||||||||||||||
| issueResult | array | 100 | N | 접수된 현금영수증 발행 결과 | |||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||
이벤트 예시
{
"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 | object | - | Y | header | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| body | object | - | Y | body | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
이벤트 예시
[
{
"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
}
}
]