이벤트 데이터 - Single

전자세금계산서 단건발행(Single) 웹훅에서 발생하는 이벤트입니다.

이벤트 타입	설명
Issue	전자세금계산서 발행(전자서명)
CnacelIssue	전자세금계산서 발행취소
CLOSEDOWN	공급받는자 휴폐업조회 결과
NTS	전자세금계산서 국세청 전송상태
OPEN	공급받는자 발행 안내 메일 확인
Request	공급받는자 역발행요청
CancelRequest	공급받는자 역발행요청 취소
Refuse	공급자 역발행요청 거부

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

Webhook - Header

필드명	설명	필수	예시
Pb-Webhook-Type	Webhook 유형	Y	TAXINVOICE.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	전자세금계산서 발행 유형별 작성자 사업자번호 정발행 : 공급자 사업자번호 위수탁발행 : 수탁자 사업자번호
itemKey	String	18	Y	팝빌에서 세금계산서 관리 목적으로 할당한 식별번호
ntsConfirmNum	String	24	Y	국세청승인번호 세금계산서 발행 시점에 팝빌에서 자동으로 할당
ntssendDT	String	14	N	국세청 전송일시 형식 : yyyyMMddHHmmss
ntsresultDT	String	14	N	국세청 결과 수신일시 형식 : yyyyMMddHHmmss
ntssendErrCode	String	6	N	결과코드 [참고] 국세청 결과코드
stateCode	Number	3	Y	상태코드 [참고] 팝빌 상태코드
stateDT	String	14	Y	상태 변경일시 형식 : yyyyMMddHHmmss
issueDT	String	14	Y	발행일시 형식 : yyyyMMddHHmmss
invoicerMgtKey	String	24	N	공급자 문서번호 파트너가 할당한 문서번호
invoiceeMgtKey	String	24	N	공급받는자 문서번호 파트너가 할당한 문서번호
trusteeMgtKey	String	24	N	수탁자 문서번호 파트너가 할당한 문서번호
eventDT	String	14	Y	이벤트 실행일시 형식 : yyyyMMddHHmmss
eventType	String	30	Y	이벤트 유형 Issue CancelIssue CLOSEDOWN NTS OPEN Request CancelRequest Refuse
closeDownState	Number	1	N	공급받는자 휴폐업상태 null미확인 0미등록 1사업중 2폐업 3휴업 4확인실패
closeDownStateDate	String	8	N	공급받는자 휴폐업일자 형식 : yyyyMMdd
interOPYN	Boolean	-	Y	연동문서 여부 trueAPI로 발행한 연동문서 false팝빌 사이트에서 발행한 일반문서
stateMemo	String	200	N	상태메모

이벤트 예시

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

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

Issue
CancelIssue
CLOSEDOWN
NTS
OPEN
Request
CancelRequest
Refuse

발행

공급자(또는 수탁자)가 세금계산서를 작성하여 인증서로 발행(전자서명) 완료한 시점에 실행됩니다.

{
  "corpNum": "1234567890",
  "itemKey": "022101816220700001",
  "ntsconfirmNum": "202210188888888800000019",
  "stateCode": 300,
  "stateDT": "20221018162207",
  "issueDT": "20221018162207",
  "invoicerMgtKey": "20221018-001",
  "eventDT": "20221018162207",
  "eventType": "Issue",
  "interOPYN": true,
  "stateMemo": "memo"
}

발행취소

공급자(또는 수탁자)가 전자세금계산서를 발행취소한 시점에 실행됩니다.

{
  "corpNum": "1234567890",
  "itemKey": "022101816232400001",
  "ntsconfirmNum": "20221018888888880000001a",
  "stateCode": 600,
  "stateDT": "20221018162332",
  "issueDT": "20221018162324",
  "invoicerMgtKey": "20221018-002",
  "eventDT": "20221018162332",
  "eventType": "CancelIssue",
  "closeDownState": 0,
  "interOPYN": true,
  "stateMemo": "cancelIssue memo"
}

휴폐업조회 결과

공급받는자 휴페업조회가 완료된 시점에 실행됩니다.

{
  "corpNum": "1234567890",
  "itemKey": "022101816232400001",
  "ntsconfirmNum": "20221018888888880000001a",
  "stateCode": 300,
  "stateDT": "20221018162325",
  "issueDT": "20221018162324",
  "invoicerMgtKey": "20221018-002",
  "eventDT": "20221018162324",
  "eventType": "CLOSEDOWN",
  "closeDownState": 0,
  "interOPYN": true,
  "stateMemo": "memo"
}

국세청 전송상태

전자세금계산서의 국세청 전송전(stateCode : 301), 전송완료(stateCode : 304), 전송실패(stateCode : 305) 시점에 실행됩니다.

{
  "corpNum": "1234567890",
  "itemKey": "022101816220700001",
  "ntsconfirmNum": "202210188888888800000019",
  "ntssendDT": "20221018162207",
  "ntsresultDT": "20221018162707",
  "ntssendErrCode": "SUC001",
  "stateCode": 304,
  "stateDT": "20221018162207",
  "issueDT": "20221018162207",
  "invoicerMgtKey": "20221018-001",
  "eventDT": "20221018162707",
  "eventType": "NTS",
  "closeDownState": 0,
  "interOPYN": true,
  "stateMemo": "memo"
}

발행 안내 메일 확인

공급받는자가 발행 안내 메일의 '전자세금계산서 보기' 버튼을 클릭하는 시점에 실행됩니다.

{
  "corpNum": "1234567890",
  "itemKey": "022102113485500001",
  "ntsconfirmNum": "20221021888888880000000d",
  "stateCode": 300,
  "stateDT": "20221021134858",
  "issueDT": "20221021134858",
  "eventDT": "20221021135006",
  "eventType": "OPEN",
  "closeDownState": 0,
  "interOPYN": false
}

역발행요청

공급받는자가 공급자에게 역발행요청 하는 시점에 실행됩니다.

{
  "corpNum": "1234567890",
  "itemKey": "022111411142600001",
  "stateCode": 200,
  "stateDT": "20221114111429",
  "invoiceeMgtKey": "20221114-TEST",
  "eventDT": "20221114111429",
  "eventType": "Request",
  "interOPYN": false
}

역발행요청 취소

공급받는자가 역발행요청을 취소하는 시점에 실행됩니다.

{
  "corpNum": "1234567890",
  "itemKey": "022111411142600001",
  "stateCode": 500,
  "stateDT": "20221114111547",
  "invoiceeMgtKey": "20221114-TEST",
  "eventDT": "20221114111547",
  "eventType": "CancelRequest",
  "interOPYN": false
}

역발행요청 거부

공급자가 역발행요청을 거부하는 시점에 실행됩니다.

{
  "corpNum": "1234567890",
  "itemKey": "022102716565000001",
  "stateCode": 400,
  "stateDT": "20221114110048",
  "eventDT": "20221114110048",
  "eventType": "Refuse",
  "interOPYN": false
}