웹훅 이벤트

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

실제 고객사 서버로 전송된 웹훅 이벤트 정보는 [Webhook 실행내역 확인] 을 참고하여 주시기 바랍니다.

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. 문서 상태 - 단건발행

현금영수증 단건발행에서 발생하는 웹훅 이벤트입니다.
각 이벤트 발생시점은 [발행유형] 의 상태확인 내용에서 확인 가능합니다.

이벤트 유형	설명
Issue	현금영수증 발행
NTS	현금영수증 국세청 전송상태

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

Issue - 발행

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

이벤트 본문

순번	변수명	타입	길이	필수	설명
1	`corpNum`	string	10	Y	팝빌회원 사업자번호 ('-' 제외)
2	`franchiseCorpNum`	string	10	Y	가맹점 사업자번호 팝빌회원 사업자번호 ('-' 제외)
3	`itemKey`	string	18	Y	팝빌에서 현금영수증 관리 목적으로 할당한 식별번호
4	`tradeDate`	string	8	Y	거래일자 형식 : yyyyMMdd
5	`confirmNum`	string	9	Y	국세청승인번호 현금영수증 발행 시점에 팝빌에서 자동으로 할당
6	`ntssendDT`	string	14	N	국세청 전송일시 형식 : yyyyMMddHHmmss
7	`ntsresultDT`	string	14	N	국세청 처리결과 수신일시 형식 : yyyyMMddHHmmss
8	`ntsresultCode`	string	4	N	국세청 결과코드 [참고] 국세청 결과코드
9	`stateCode`	number	3	Y	상태코드 [참고] 팝빌 상태코드
10	`stateDT`	string	14	Y	상태 변경일시 형식 : yyyyMMddHHmmss
11	`issueDT`	string	14	Y	발행일시 형식 : yyyyMMddHHmmss
12	`mgtKey`	string	24	N	문서번호 파트너가 할당하는 식별번호
13	`eventDT`	string	14	Y	이벤트 실행일시 형식 : yyyyMMddHHmmss
14	`eventType`	string	30	Y	이벤트 유형 `Issue` `NTS`
15	`interOPYN`	boolean	-	Y	연동문서 여부 `true` API를 통해 발행한 연동문서 `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) 시점에 실행됩니다.

이벤트 본문

순번	변수명	타입	길이	필수	설명
1	`corpNum`	string	10	Y	팝빌회원 사업자번호 ('-' 제외)
2	`franchiseCorpNum`	string	10	Y	가맹점 사업자번호 팝빌회원 사업자번호 ('-' 제외)
3	`itemKey`	string	18	Y	팝빌에서 현금영수증 관리 목적으로 할당한 식별번호
4	`tradeDate`	string	8	Y	거래일자 형식 : yyyyMMdd
5	`confirmNum`	string	9	Y	국세청승인번호 현금영수증 발행 시점에 팝빌에서 자동으로 할당
6	`ntssendDT`	string	14	N	국세청 전송일시 형식 : yyyyMMddHHmmss
7	`ntsresultDT`	string	14	N	국세청 처리결과 수신일시 형식 : yyyyMMddHHmmss
8	`ntsresultCode`	string	4	N	국세청 결과코드 [참고] 국세청 결과코드
9	`stateCode`	number	3	Y	상태코드 [참고] 팝빌 상태코드
10	`stateDT`	string	14	Y	상태 변경일시 형식 : yyyyMMddHHmmss
11	`issueDT`	string	14	Y	발행일시 형식 : yyyyMMddHHmmss
12	`mgtKey`	string	24	N	문서번호 파트너가 할당하는 식별번호
13	`eventDT`	string	14	Y	이벤트 실행일시 형식 : yyyyMMddHHmmss
14	`eventType`	string	30	Y	이벤트 유형 `Issue` `NTS`
15	`interOPYN`	boolean	-	Y	연동문서 여부 `true` API를 통해 발행한 연동문서 `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
}

3. 문서 상태 - 대량발행

현금영수증 대량발행에서 발생하는 웹훅 이벤트입니다.
각 이벤트 발생시점은 [발행유형] 의 상태확인 내용에서 확인 가능합니다.

이벤트 유형	설명
BULK.RESULT	현금영수증 대량발행 접수결과
NTS	현금영수증 국세청 전송 처리결과

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

BULK.RESULT - 접수결과

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

이벤트 본문

순번 변수명 타입 길이 필수 설명

corpNum

string

팝빌회원 사업자번호 ('-' 제외)

franchiseCorpNum

string

현금영수증 대량 접수 시 입력한 사업자번호

submitID

string

접수 시점에 고객사에서 할당한 제출아이디

receiptID

string

접수 아이디

접수 시점에 팝빌에서 자동으로 할당

receiptDT

string

접수일시

형식 : yyyyMMddHHmmss

eventType

string

이벤트 유형

BULK.RESULT

eventDT

string

이벤트 실행 일시

형식 : yyyyMMddHHmmss

submitCount

number

현금영수증 접수 건수

successCount

number

현금영수증 발행 성공 건수

failCount

number

현금영수증 발행 실패 건수

txState

number

접수상태

0 접수
1 처리중
2 처리완료

txResultCode

number

접수 결과코드

성공 : 1

실패 : 음의 정수 8자리 숫자값 [참고] 오류코드

txStartDT

string

발행처리 시작일시

형식 : yyyyMMddHHmmss

txEndDT

string

발행처리 완료일시

형식 : yyyyMMddHHmmss

array

100

접수된 현금영수증 발행 결과

issueResult

순번	변수명	타입	길이	필수	설명
1	`code`	number	-	Y	API 처리에 대한 응답코드 성공 : 1 실패 : 음의 정수 8자리 숫자값 [참고] 오류코드
2	`message`	string	-	N	API처리에 대한 응답 메시지
3	`confirmNum`	string	9	N	국세청승인번호 현금영수증 발행 시점에 팝빌에서 자동으로 할당
4	`tradeDate`	string	8	N	거래일자 형식 : yyyyMMdd
5	`issueDT`	string	14	N	발행일시 형식 : yyyyMMddHHmmss
6	`mgtKey`	string	24	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건씩 리스트로 묶여 실행 됩니다.

이벤트 본문

순번 변수명 타입 길이 필수 설명

object

header

header

순번	변수명	타입	길이	필수	설명
1	`QMNum`	string	24	Y	팝빌이 생성한 현금영수증 국세청 신고를 위한 고유번호
2	`CORPNUM`	string	10	Y	현금영수증 대량 접수 시 입력한 사업자번호
3	`TYPE`	string	-	Y	Webhook 유형 `CASHBILL.STATE`

object

body

body

순번	변수명	타입	길이	필수	설명
1	`corpNum`	string	10	Y	현금영수증 대량 접수 시 입력한 사업자번호
2	`itemKey`	string	18	Y	팝빌에서 현금영수증 관리 목적으로 할당한 식별번호
3	`confirmNum`	string	9	Y	국세청승인번호 현금영수증 발행 시점에 팝빌에서 자동으로 할당
4	`ntssendDT`	string	14	N	국세청 전송일시 형식 : yyyyMMddHHmmss
5	`ntsresultDT`	string	14	N	국세청 결과 수신일시 형식 : yyyyMMddHHmmss
6	`ntsresultCode`	string	-	N	국세청 결과코드 [참고] 국세청 결과코드
7	`stateCode`	number	3	Y	상태코드 [참고] 팝빌 상태코드
8	`stateDT`	string	14	Y	상태 변경일시 형식 : yyyyMMddHHmmss
9	`issueDT`	string	14	Y	발행일시 형식 : yyyyMMddHHmmss
10	`mgtKey`	string	24	N	문서번호 파트너가 할당한 문서번호
11	`eventDT`	string	14	Y	이벤트 실행일시 형식 : yyyyMMddHHmmss
12	`eventType`	string	30	Y	이벤트 유형 `NTS`
13	`interOPYN`	boolean	-	Y	연동문서 여부 `true` API로 발행한 연동문서 `false` 팝빌 사이트에서 발행한 일반문서

이벤트 예시

[
    {
        "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
        }
    }
]