문서 상태 이벤트 - 단건발행(Single)

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

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

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

Webhook - Header

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

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

Webhook - Body

필드명	타입	길이	필수	설명
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팝빌 사이트를 통해 발행한 문서

이벤트 예시

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

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

Issue
NTS

발행

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

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

국세청 전송상태

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

{
  "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)

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

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

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

Webhook - Header

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

이벤트 예시

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

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

BULK.RESULT
NTS

접수결과

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

필드명	타입	길이	필수	설명
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	Object	100	N	접수된 현금영수증 발행 결과 하단의 테이블 참고

issueResult 객체 정보

필드명	타입	길이	필수	설명
code	Number	-	Y	API 처리에 대한 응답코드 - 성공 : 1 - 실패 : 음의 정수 8자리 숫자값 [참고] 오류코드
message	String	-	N	API처리에 대한 응답 메시지
confirmNum	String	9	N	국세청승인번호 현금영수증 발행 시점에 팝빌에서 자동으로 할당
tradeDate	String	8	N	거래일자 형식 : yyyyMMdd
issueDT	String	14	N	발행일시 형식 : yyyyMMddHHmmss
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"
    },
    {
      "code": 1,
      "confirmNum": "TB0000024",
      "tradeDate": "20221222",
      "issueDT": "20221222100306",
      "mgtKey": "20221221-BULK~,-_2"
    }
  ]
}

국세청 전송 처리결과

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

header 객체 정보

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

body 객체 정보

필드명	타입	길이	필수	설명
corpNum	String	10	Y	현금영수증 대량 접수 시 입력한 사업자번호
itemKey	String	18	Y	팝빌에서 현금영수증 관리 목적으로 할당한 식별번호
confirmNum	String	9	Y	국세청승인번호 현금영수증 발행 시점에 팝빌에서 자동으로 할당
ntssendDT	String	14	N	국세청 전송일시 형식 : yyyyMMddHHmmss
ntsresultDT	String	14	N	국세청 결과 수신일시 형식 : yyyyMMddHHmmss
ntsresultCode	String	-	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	이벤트 유형 NTS
interOPYN	Boolean	-	Y	연동문서 여부 trueAPI로 발행한 연동문서 false팝빌 사이트에서 발행한 일반문서

Request 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
        }
    },
    {
        "header": {
            "QMNum": "TB0000044",
            "CORPNUM": "1234567890",
            "TYPE": "CASHBILL.STATE"
        },
        "body": {
            "corpNum": "1234567890",
            "itemKey": "022110814151400001",
            "confirmNum": "TB0000044",
            "ntssendDT": "20221109000207",
            "ntsresultDT": "20221109100017",
            "ntsresultCode": "0000",
            "ntsresultMessage": "더미승인",
            "stateCode": 304,
            "stateDT": "20221108141514",
            "issueDT": "20221108141514",
            "mgtKey": "20221108-JSP-BULK-1",
            "eventDT": "20221109100017",
            "eventType": "NTS",
            "interOPYN": true
        }
    },
    {
        "header": {
            "QMNum": "TB0000048",
            "CORPNUM": "1234567890",
            "TYPE": "CASHBILL.STATE"
        },
        "body": {
            "corpNum": "1234567890",
            "itemKey": "022110814151400005",
            "confirmNum": "TB0000048",
            "ntssendDT": "20221109000207",
            "ntsresultDT": "20221109100017",
            "ntsresultCode": "0000",
            "ntsresultMessage": "더미승인",
            "stateCode": 304,
            "stateDT": "20221108141514",
            "issueDT": "20221108141514",
            "mgtKey": "20221108-JSP-BULK-5",
            "eventDT": "20221109100017",
            "eventType": "NTS",
            "interOPYN": true
        }
    }
]