웹훅 이벤트

전자세금계산서에서 발생하는 웹훅 이벤트입니다.

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

1. 웹훅 헤더

순번	변수명	필수	설명	예시
1	Pb-Webhook-Type	Y	Webhook 유형	TAXINVOICE.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	전자세금계산서 발행(전자서명)
CancelIssue	전자세금계산서 발행취소
CLOSEDOWN	공급받는자 사업자등록상태조회 결과
NTS	전자세금계산서 국세청 전송상태
OPEN	공급받는자 발행 안내 메일 확인
Request	공급받는자 역발행요청
CancelRequest	공급받는자 역발행요청 취소
Refuse	공급자 역발행요청 거부

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

Issue - 발행

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

이벤트 본문

순번	변수명	타입	길이	필수	설명
1	corpNum	string	10	Y	전자세금계산서 발행 유형별 작성자 사업자번호 → 정발행 : 공급자 사업자번호 위수탁 : 수탁자 사업자번호
2	itemKey	string	18	Y	팝빌에서 할당한 식별번호
3	ntsconfirmNum	string	24	Y	국세청승인번호 → 전자세금계산서 발행 시점에 팝빌에서 자동으로 할당
4	ntssendDT	string	14	N	국세청 전송일시 → 형식 : yyyyMMddHHmmss
5	ntsresultDT	string	14	N	국세청 결과 수신일시 → 형식 : yyyyMMddHHmmss
6	ntssendErrCode	string	6	N	국세청 결과코드 → [참고] 국세청 결과코드
7	stateCode	number	3	Y	상태코드 → [참고] 팝빌 상태코드
8	stateDT	string	14	Y	상태 변경일시 → 형식 : yyyyMMddHHmmss
9	issueDT	string	14	Y	발행일시 → 형식 : yyyyMMddHHmmss
10	invoicerMgtKey	string	24	N	공급자 문서번호 → 파트너가 할당한 문서번호
11	invoiceeMgtKey	string	24	N	공급받는자 문서번호 → 파트너가 할당한 문서번호
12	trusteeMgtKey	string	24	N	수탁자 문서번호 → 파트너가 할당한 문서번호
13	eventDT	string	14	Y	이벤트 실행일시 → 형식 : yyyyMMddHHmmss
14	eventType	string	30	Y	이벤트 유형 Issue
15	closeDownState	number	1	N	공급받는자 휴폐업상태 null 미확인 0 미등록 1 사업중 2 폐업 3 휴업 4 확인실패
16	closeDownStateDate	string	8	N	공급받는자 휴폐업일자 → 형식 : yyyyMMdd
17	interOPYN	boolean	-	Y	연동문서 여부 true API로 발행한 연동문서 false 팝빌 사이트에서 발행한 일반문서
18	stateMemo	string	200	N	상태메모

이벤트 예시

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

CancelIssue - 발행취소

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

이벤트 본문

순번	변수명	타입	길이	필수	설명
1	corpNum	string	10	Y	전자세금계산서 발행 유형별 작성자 사업자번호 → 정발행 : 공급자 사업자번호 위수탁 : 수탁자 사업자번호
2	itemKey	string	18	Y	팝빌에서 할당한 식별번호
3	ntsconfirmNum	string	24	Y	국세청승인번호 → 전자세금계산서 발행 시점에 팝빌에서 자동으로 할당
4	ntssendDT	string	14	N	국세청 전송일시 → 형식 : yyyyMMddHHmmss
5	ntsresultDT	string	14	N	국세청 결과 수신일시 → 형식 : yyyyMMddHHmmss
6	ntssendErrCode	string	6	N	국세청 결과코드 → [참고] 국세청 결과코드
7	stateCode	number	3	Y	상태코드 → [참고] 팝빌 상태코드
8	stateDT	string	14	Y	상태 변경일시 → 형식 : yyyyMMddHHmmss
9	issueDT	string	14	Y	발행일시 → 형식 : yyyyMMddHHmmss
10	invoicerMgtKey	string	24	N	공급자 문서번호 → 파트너가 할당한 문서번호
11	invoiceeMgtKey	string	24	N	공급받는자 문서번호 → 파트너가 할당한 문서번호
12	trusteeMgtKey	string	24	N	수탁자 문서번호 → 파트너가 할당한 문서번호
13	eventDT	string	14	Y	이벤트 실행일시 → 형식 : yyyyMMddHHmmss
14	eventType	string	30	Y	이벤트 유형 CancelIssue
15	closeDownState	number	1	N	공급받는자 휴폐업상태 null 미확인 0 미등록 1 사업중 2 폐업 3 휴업 4 확인실패
16	closeDownStateDate	string	8	N	공급받는자 휴폐업일자 → 형식 : yyyyMMdd
17	interOPYN	boolean	-	Y	연동문서 여부 true API로 발행한 연동문서 false 팝빌 사이트에서 발행한 일반문서
18	stateMemo	string	200	N	상태메모

이벤트 예시

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

CLOSEDOWN - 사업자등록상태조회 결과

공급받는자 사업자등록상태조회가 완료된 시점에 실행됩니다.

이벤트 본문

순번	변수명	타입	길이	필수	설명
1	corpNum	string	10	Y	전자세금계산서 발행 유형별 작성자 사업자번호 → 정발행 : 공급자 사업자번호 위수탁 : 수탁자 사업자번호
2	itemKey	string	18	Y	팝빌에서 할당한 식별번호
3	ntsconfirmNum	string	24	Y	국세청승인번호 → 전자세금계산서 발행 시점에 팝빌에서 자동으로 할당
4	ntssendDT	string	14	N	국세청 전송일시 → 형식 : yyyyMMddHHmmss
5	ntsresultDT	string	14	N	국세청 결과 수신일시 → 형식 : yyyyMMddHHmmss
6	ntssendErrCode	string	6	N	국세청 결과코드 → [참고] 국세청 결과코드
7	stateCode	number	3	Y	상태코드 → [참고] 팝빌 상태코드
8	stateDT	string	14	Y	상태 변경일시 → 형식 : yyyyMMddHHmmss
9	issueDT	string	14	Y	발행일시 → 형식 : yyyyMMddHHmmss
10	invoicerMgtKey	string	24	N	공급자 문서번호 → 파트너가 할당한 문서번호
11	invoiceeMgtKey	string	24	N	공급받는자 문서번호 → 파트너가 할당한 문서번호
12	trusteeMgtKey	string	24	N	수탁자 문서번호 → 파트너가 할당한 문서번호
13	eventDT	string	14	Y	이벤트 실행일시 → 형식 : yyyyMMddHHmmss
14	eventType	string	30	Y	이벤트 유형 CLOSEDOWN
15	closeDownState	number	1	N	공급받는자 휴폐업상태 null 미확인 0 미등록 1 사업중 2 폐업 3 휴업 4 확인실패
16	closeDownStateDate	string	8	N	공급받는자 휴폐업일자 → 형식 : yyyyMMdd
17	interOPYN	boolean	-	Y	연동문서 여부 true API로 발행한 연동문서 false 팝빌 사이트에서 발행한 일반문서
18	stateMemo	string	200	N	상태메모

이벤트 예시

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

NTS - 국세청 전송상태

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

이벤트 본문

순번	변수명	타입	길이	필수	설명
1	corpNum	string	10	Y	전자세금계산서 발행 유형별 작성자 사업자번호 → 정발행 : 공급자 사업자번호 위수탁 : 수탁자 사업자번호
2	itemKey	string	18	Y	팝빌에서 할당한 식별번호
3	ntsconfirmNum	string	24	Y	국세청승인번호 → 전자세금계산서 발행 시점에 팝빌에서 자동으로 할당
4	ntssendDT	string	14	N	국세청 전송일시 → 형식 : yyyyMMddHHmmss
5	ntsresultDT	string	14	N	국세청 결과 수신일시 → 형식 : yyyyMMddHHmmss
6	ntssendErrCode	string	6	N	국세청 결과코드 → [참고] 국세청 결과코드
7	stateCode	number	3	Y	상태코드 → [참고] 팝빌 상태코드
8	stateDT	string	14	Y	상태 변경일시 → 형식 : yyyyMMddHHmmss
9	issueDT	string	14	Y	발행일시 → 형식 : yyyyMMddHHmmss
10	invoicerMgtKey	string	24	N	공급자 문서번호 → 파트너가 할당한 문서번호
11	invoiceeMgtKey	string	24	N	공급받는자 문서번호 → 파트너가 할당한 문서번호
12	trusteeMgtKey	string	24	N	수탁자 문서번호 → 파트너가 할당한 문서번호
13	eventDT	string	14	Y	이벤트 실행일시 → 형식 : yyyyMMddHHmmss
14	eventType	string	30	Y	이벤트 유형 NTS
15	closeDownState	number	1	N	공급받는자 휴폐업상태 null 미확인 0 미등록 1 사업중 2 폐업 3 휴업 4 확인실패
16	closeDownStateDate	string	8	N	공급받는자 휴폐업일자 → 형식 : yyyyMMdd
17	interOPYN	boolean	-	Y	연동문서 여부 true API로 발행한 연동문서 false 팝빌 사이트에서 발행한 일반문서
18	stateMemo	string	200	N	상태메모

이벤트 예시

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

OPEN - 발행 안내 메일 확인

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

이벤트 본문

순번	변수명	타입	길이	필수	설명
1	corpNum	string	10	Y	전자세금계산서 발행 유형별 작성자 사업자번호 → 정발행 : 공급자 사업자번호 위수탁 : 수탁자 사업자번호
2	itemKey	string	18	Y	팝빌에서 할당한 식별번호
3	ntsconfirmNum	string	24	Y	국세청승인번호 → 전자세금계산서 발행 시점에 팝빌에서 자동으로 할당
4	ntssendDT	string	14	N	국세청 전송일시 → 형식 : yyyyMMddHHmmss
5	ntsresultDT	string	14	N	국세청 결과 수신일시 → 형식 : yyyyMMddHHmmss
6	ntssendErrCode	string	6	N	국세청 결과코드 → [참고] 국세청 결과코드
7	stateCode	number	3	Y	상태코드 → [참고] 팝빌 상태코드
8	stateDT	string	14	Y	상태 변경일시 → 형식 : yyyyMMddHHmmss
9	issueDT	string	14	Y	발행일시 → 형식 : yyyyMMddHHmmss
10	invoicerMgtKey	string	24	N	공급자 문서번호 → 파트너가 할당한 문서번호
11	invoiceeMgtKey	string	24	N	공급받는자 문서번호 → 파트너가 할당한 문서번호
12	trusteeMgtKey	string	24	N	수탁자 문서번호 → 파트너가 할당한 문서번호
13	eventDT	string	14	Y	이벤트 실행일시 → 형식 : yyyyMMddHHmmss
14	eventType	string	30	Y	이벤트 유형 OPEN
15	closeDownState	number	1	N	공급받는자 휴폐업상태 null 미확인 0 미등록 1 사업중 2 폐업 3 휴업 4 확인실패
16	closeDownStateDate	string	8	N	공급받는자 휴폐업일자 → 형식 : yyyyMMdd
17	interOPYN	boolean	-	Y	연동문서 여부 true API로 발행한 연동문서 false 팝빌 사이트에서 발행한 일반문서
18	stateMemo	string	200	N	상태메모

이벤트 예시

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

Request - 역발행요청

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

이벤트 본문

순번	변수명	타입	길이	필수	설명
1	corpNum	string	10	Y	전자세금계산서 발행 유형별 작성자 사업자번호 → 정발행 : 공급자 사업자번호 위수탁 : 수탁자 사업자번호
2	itemKey	string	18	Y	팝빌에서 할당한 식별번호
3	ntsconfirmNum	string	24	Y	국세청승인번호 → 전자세금계산서 발행 시점에 팝빌에서 자동으로 할당
4	ntssendDT	string	14	N	국세청 전송일시 → 형식 : yyyyMMddHHmmss
5	ntsresultDT	string	14	N	국세청 결과 수신일시 → 형식 : yyyyMMddHHmmss
6	ntssendErrCode	string	6	N	국세청 결과코드 → [참고] 국세청 결과코드
7	stateCode	number	3	Y	상태코드 → [참고] 팝빌 상태코드
8	stateDT	string	14	Y	상태 변경일시 → 형식 : yyyyMMddHHmmss
9	issueDT	string	14	Y	발행일시 → 형식 : yyyyMMddHHmmss
10	invoicerMgtKey	string	24	N	공급자 문서번호 → 파트너가 할당한 문서번호
11	invoiceeMgtKey	string	24	N	공급받는자 문서번호 → 파트너가 할당한 문서번호
12	trusteeMgtKey	string	24	N	수탁자 문서번호 → 파트너가 할당한 문서번호
13	eventDT	string	14	Y	이벤트 실행일시 → 형식 : yyyyMMddHHmmss
14	eventType	string	30	Y	이벤트 유형 Request
15	closeDownState	number	1	N	공급받는자 휴폐업상태 null 미확인 0 미등록 1 사업중 2 폐업 3 휴업 4 확인실패
16	closeDownStateDate	string	8	N	공급받는자 휴폐업일자 → 형식 : yyyyMMdd
17	interOPYN	boolean	-	Y	연동문서 여부 true API로 발행한 연동문서 false 팝빌 사이트에서 발행한 일반문서
18	stateMemo	string	200	N	상태메모

이벤트 예시

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

CancelRequest - 역발행요청 취소

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

이벤트 본문

순번	변수명	타입	길이	필수	설명
1	corpNum	string	10	Y	전자세금계산서 발행 유형별 작성자 사업자번호 → 정발행 : 공급자 사업자번호 위수탁 : 수탁자 사업자번호
2	itemKey	string	18	Y	팝빌에서 할당한 식별번호
3	ntsconfirmNum	string	24	Y	국세청승인번호 → 전자세금계산서 발행 시점에 팝빌에서 자동으로 할당
4	ntssendDT	string	14	N	국세청 전송일시 → 형식 : yyyyMMddHHmmss
5	ntsresultDT	string	14	N	국세청 결과 수신일시 → 형식 : yyyyMMddHHmmss
6	ntssendErrCode	string	6	N	국세청 결과코드 → [참고] 국세청 결과코드
7	stateCode	number	3	Y	상태코드 → [참고] 팝빌 상태코드
8	stateDT	string	14	Y	상태 변경일시 → 형식 : yyyyMMddHHmmss
9	issueDT	string	14	Y	발행일시 → 형식 : yyyyMMddHHmmss
10	invoicerMgtKey	string	24	N	공급자 문서번호 → 파트너가 할당한 문서번호
11	invoiceeMgtKey	string	24	N	공급받는자 문서번호 → 파트너가 할당한 문서번호
12	trusteeMgtKey	string	24	N	수탁자 문서번호 → 파트너가 할당한 문서번호
13	eventDT	string	14	Y	이벤트 실행일시 → 형식 : yyyyMMddHHmmss
14	eventType	string	30	Y	이벤트 유형 CancelRequest
15	closeDownState	number	1	N	공급받는자 휴폐업상태 null 미확인 0 미등록 1 사업중 2 폐업 3 휴업 4 확인실패
16	closeDownStateDate	string	8	N	공급받는자 휴폐업일자 → 형식 : yyyyMMdd
17	interOPYN	boolean	-	Y	연동문서 여부 true API로 발행한 연동문서 false 팝빌 사이트에서 발행한 일반문서
18	stateMemo	string	200	N	상태메모

이벤트 예시

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

Refuse - 역발행요청 거부

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

이벤트 본문

순번	변수명	타입	길이	필수	설명
1	corpNum	string	10	Y	전자세금계산서 발행 유형별 작성자 사업자번호 → 정발행 : 공급자 사업자번호 위수탁 : 수탁자 사업자번호
2	itemKey	string	18	Y	팝빌에서 할당한 식별번호
3	ntsconfirmNum	string	24	Y	국세청승인번호 → 전자세금계산서 발행 시점에 팝빌에서 자동으로 할당
4	ntssendDT	string	14	N	국세청 전송일시 → 형식 : yyyyMMddHHmmss
5	ntsresultDT	string	14	N	국세청 결과 수신일시 → 형식 : yyyyMMddHHmmss
6	ntssendErrCode	string	6	N	국세청 결과코드 → [참고] 국세청 결과코드
7	stateCode	number	3	Y	상태코드 → [참고] 팝빌 상태코드
8	stateDT	string	14	Y	상태 변경일시 → 형식 : yyyyMMddHHmmss
9	issueDT	string	14	Y	발행일시 → 형식 : yyyyMMddHHmmss
10	invoicerMgtKey	string	24	N	공급자 문서번호 → 파트너가 할당한 문서번호
11	invoiceeMgtKey	string	24	N	공급받는자 문서번호 → 파트너가 할당한 문서번호
12	trusteeMgtKey	string	24	N	수탁자 문서번호 → 파트너가 할당한 문서번호
13	eventDT	string	14	Y	이벤트 실행일시 → 형식 : yyyyMMddHHmmss
14	eventType	string	30	Y	이벤트 유형 Refuse
15	closeDownState	number	1	N	공급받는자 휴폐업상태 null 미확인 0 미등록 1 사업중 2 폐업 3 휴업 4 확인실패
16	closeDownStateDate	string	8	N	공급받는자 휴폐업일자 → 형식 : yyyyMMdd
17	interOPYN	boolean	-	Y	연동문서 여부 true API로 발행한 연동문서 false 팝빌 사이트에서 발행한 일반문서
18	stateMemo	string	200	N	상태메모

이벤트 예시

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

3. 문서 상태 - 대량발행

전자세금계산서 대량발행에서 발생하는 웹훅 이벤트입니다.
각 이벤트 발생시점은 [상태확인] 에서 확인 가능합니다.

이벤트 유형	설명
BULK.RESULT	전자세금계산서 대량발행 접수결과
CLOSEDOWN	전자세금계산서 대량발행 사업자등록상태조회 결과
NTS	전자세금계산서 대량발행 국세청 전송 처리결과
CancelIssue	전자세금계산서 발행취소

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

BULK.RESULT - 접수결과

공급자(또는 수탁자)가 전자세금계산서를 대량 접수 완료한 시점에 실행됩니다.

이벤트 본문

순번	변수명	타입	길이	필수	설명
1	corpNum	string	10	Y	전자세금계산서 발행 유형별 작성자 사업자번호 → 정발행 : 공급자 사업자번호 위수탁 : 수탁자 사업자번호
2	submitID	string	36	Y	접수 시점에 고객사에서 할당한 제출아이디
3	receiptID	string	36	Y	접수아이디 → 접수 시점에 팝빌에서 자동으로 할당
4	receiptDT	string	14	Y	접수일시 → 형식 : yyyyMMddHHmmss
5	eventType	string	-	Y	이벤트 유형 BULK.RESULT
6	eventDT	string	14	Y	이벤트 실행 일시 → 형식 : yyyyMMddHHmmss
7	submitCount	number	-	Y	세금계산서 접수 건수
8	successCount	number	-	Y	세금계산서 발행 성공 건수
9	failCount	number	-	Y	세금계산서 발행 실패 건수
10	txState	number	1	Y	접수상태 0 접수 1 처리중 2 처리완료
11	txResultCode	number	-	N	접수 결과코드 → 성공 : 1 실패 : 음의 정수 8자리 숫자값 [참고] 오류코드
12	txStartDT	string	14	N	발행처리 시작일시 → 형식 : yyyyMMddHHmmss
13	txEndDT	string	14	N	발행처리 완료일시 → 형식 : yyyyMMddHHmmss
14	issueResult	array	-	N	접수된 전자세금계산서 발행 결과
issueResult 순번 변수명 타입 길이 필수 설명 1 code number - Y API 처리에 대한 응답코드 → 성공 : 1 실패 : 음의 정수 8자리 숫자값 [참고] 오류코드 2 message string - N API 처리에 대한 응답 메시지 3 issueDT string 14 N 발행일시 → 형식 : yyyyMMddHHmmss 4 ntsconfirmNum string 24 N 국세청승인번호 → 전자세금계산서 발행 시점에 팝빌에서 자동으로 할당 5 invoicerMgtKey string 24 N 공급자 문서번호 → 파트너가 할당한 문서번호 6 trusteeMgtKey string 24 N 수탁자 문서번호 → 파트너가 할당한 문서번호

이벤트 예시

{
    "corpNum": "1234567890",
    "submitID": "20221013-TEST-2",
    "receiptID": "0221013-4e1a30b927ab4f88ad3d3f4a7ed9",
    "receiptDT": "20221013154838",
    "eventType": "BULK.RESULT",
    "eventDT": "20221013154839",
    "submitCount": 5,
    "successCount": 5,
    "failCount": 0,
    "txState": 2,
    "txResultCode": 1,
    "txStartDT": "20221013154839",
    "txEndDT": "20221013154839",
    "issueResult": [
        {
            "code": 1,
            "issueDT": "20221013154839",
            "ntsconfirmNum": "202210138888888800000068",
            "invoicerMgtKey": "20221013-TEST-2-0"
        },
        {
            "code": 1,
            "issueDT": "20221013154839",
            "ntsconfirmNum": "202210138888888800000069",
            "invoicerMgtKey": "20221013-TEST-2-1"
        }
    ]
}

CLOSEDOWN - 사업자등록상태조회 결과

대량 접수된 전자세금계산서의 사업자등록상태조회 완료 시점에 처리된 순서대로 최대 500건씩 리스트로 묶여 실행됩니다.

이벤트 본문

순번	변수명	타입	길이	필수	설명
1	header	object	-	Y	header
header 순번 변수명 타입 길이 필수 설명 1 QMNum string 24 Y 팝빌이 생성한 전자세금계산서 국세청 신고를 위한 고유번호 2 CORPNUM string 10 Y 전자세금계산서 발행 유형별 작성자 사업자번호 → 정발행 : 공급자 사업자번호 위수탁 : 수탁자 사업자번호 3 TYPE string - Y Webhook 유형 TAXINVOICE.STATE
2	body	object	-	Y	body
body 순번 변수명 타입 길이 필수 설명 1 corpNum string 10 Y 전자세금계산서 발행 유형별 작성자 사업자번호 → 정발행 : 공급자 사업자번호 위수탁 : 수탁자 사업자번호 2 itemKey string 18 Y 팝빌에서 할당한 식별번호 3 ntssendDT string 14 N 국세청 전송일시 → 형식 : yyyyMMddHHmmss 4 ntsconfirmNum string 24 Y 국세청승인번호 → 전자세금계산서 발행 시점에 팝빌에서 자동으로 할당 5 stateCode number 3 Y 상태코드 → [참고] 팝빌 상태코드 6 stateDT string 14 Y 상태 변경일시 → 형식 : yyyyMMddHHmmss 7 issueDT string 14 Y 발행일시 → 형식 : yyyyMMddHHmmss 8 invoicerMgtKey string 24 N 공급자 문서번호 → 파트너가 할당한 문서번호 9 trusteeMgtKey string 24 N 수탁자 문서번호 → 파트너가 할당한 문서번호 10 eventDT string 14 Y 이벤트 실행일시 → 형식 : yyyyMMddHHmmss 11 eventType string 30 Y 이벤트 유형 CLOSEDOWN 12 closeDownState number 1 N 공급받는자 휴폐업상태 null 미확인 0 미등록 1 사업중 2 폐업 3 휴업 4 확인실패 13 closeDownStateDate string 8 N 공급받는자 휴폐업일자 → 형식 : yyyyMMdd 14 interOPYN boolean - Y 연동문서 여부 true API로 발행한 연동문서 false 팝빌 사이트에서 발행한 일반문서

이벤트 예시

[
    {
        "header": {
            "QMNum": "202210138888888800000068",
            "CORPNUM": "1234567890",
            "TYPE": "TAXINVOICE.STATE"
        },
        "body": {
            "corpNum": "1234567890",
            "itemKey": "022101315483900001",
            "ntsconfirmNum": "202210138888888800000068",
            "ntssendDT": "20221013154839",
            "stateCode": 303,
            "stateDT": "20221013154839",
            "issueDT": "20221013154839",
            "invoicerMgtKey": "20221013-TEST-2-0",
            "eventDT": "20221013154839",
            "eventType": "CLOSEDOWN",
            "closeDownState": 0,
            "interOPYN": true
        }
    },
    {
        "header": {
            "QMNum": "202210138888888800000069",
            "CORPNUM": "1234567890",
            "TYPE": "TAXINVOICE.STATE"
        },
        "body": {
            "invoicerMgtKey": "20221013-TEST-2-1",
            "stateDT": "20221013154839",
            "eventType": "CLOSEDOWN",
            "closeDownState": 0,
            "itemKey": "022101315483900002",
            "ntsconfirmNum": "202210138888888800000069",
            "corpNum": "1234567890",
            "interOPYN": true,
            "ntssendDT": "20221013154839",
            "stateCode": 303,
            "eventDT": "20221013154839",
            "issueDT": "20221013154839"
        }
    }
]

NTS - 국세청 전송 처리결과

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

이벤트 본문

순번	변수명	타입	길이	필수	설명
1	header	object	-	Y	header
header 순번 변수명 타입 길이 필수 설명 1 QMNum string 24 Y 팝빌이 생성한 전자세금계산서 국세청 신고를 위한 고유번호 2 CORPNUM string 10 Y 전자세금계산서 발행 유형별 작성자 사업자번호 → 정발행 : 공급자 사업자번호 위수탁 : 수탁자 사업자번호 3 TYPE string - Y Webhook 유형 TAXINVOICE.STATE
2	body	object	-	Y	body
body 순번 변수명 타입 길이 필수 설명 1 corpNum string 10 Y 전자세금계산서 발행 유형별 작성자 사업자번호 → 정발행 : 공급자 사업자번호 위수탁 : 수탁자 사업자번호 2 itemKey string 18 Y 팝빌에서 할당한 식별번호 3 ntsconfirmNum string 24 Y 국세청승인번호 → 전자세금계산서 발행 시점에 팝빌에서 자동으로 할당 4 ntssendDT string 14 N 국세청 전송일시 → 형식 : yyyyMMddHHmmss 5 ntsresultDT string 14 N 국세청 결과 수신일시 → 형식 : yyyyMMddHHmmss 6 ntssendErrCode string 14 N 국세청 결과코드 → [참고] 국세청 결과코드 7 stateCode number 3 Y 상태코드 → [참고] 팝빌 상태코드 8 stateDT string 14 Y 상태 변경일시 → 형식 : yyyyMMddHHmmss 9 issueDT string 14 Y 발행일시 → 형식 : yyyyMMddHHmmss 10 invoicerMgtKey string 24 N 공급자 문서번호 → 파트너가 할당한 문서번호 11 trusteeMgtKey string 24 N 수탁자 문서번호 → 파트너가 할당한 문서번호 12 eventDT string 14 Y 이벤트 실행일시 → 형식 : yyyyMMddHHmmss 13 eventType string 30 Y 이벤트 유형 NTS 14 closeDownState number 1 N 공급받는자 휴폐업상태 null 미확인 0 미등록 1 사업중 2 폐업 3 휴업 4 확인실패 15 closeDownStateDate string 8 N 공급받는자 휴폐업일자 → 형식 : yyyyMMdd 16 interOPYN boolean - Y 연동문서 여부 true API로 발행한 연동문서 false 팝빌 사이트에서 발행한 일반문서

이벤트 예시

[
    {
        "header": {
            "QMNum": "20221013888888880000006b",
            "CORPNUM": "1234567890",
            "TYPE": "TAXINVOICE.STATE"
        },
        "body": {
            "corpNum": "1234567890",
            "itemKey": "022101315483900004",
            "ntsconfirmNum": "20221013888888880000006b",
            "ntssendDT": "20221013154839",
            "ntsresultDT": "20221013155339",
            "ntssendErrCode": "SUC001",
            "stateCode": 304,
            "stateDT": "20221013154839",
            "issueDT": "20221013154839",
            "invoicerMgtKey": "20221013-TEST-2-3",
            "eventDT": "20221013155339",
            "eventType": "NTS",
            "closeDownState": 0,
            "interOPYN": true
        }
    },
    {
        "header": {
            "QMNum": "20221013888888880000006c",
            "CORPNUM": "1234567890",
            "MEMBERCODE": "014070000004"
        },
        "body": {
            "invoicerMgtKey": "20221013-TEST-2-4",
            "stateDT": "20221013154840",
            "eventType": "NTS",
            "closeDownState": 0,
            "itemKey": "022101315483900005",
            "ntsconfirmNum": "20221013888888880000006c",
            "corpNum": "1234567890",
            "ntssendErrCode": "SUC001",
            "interOPYN": true,
            "ntssendDT": "20221013154840",
            "stateCode": 304,
            "ntsresultDT": "20221013155339",
            "eventDT": "20221013155339",
            "issueDT": "20221013154839"
        }
    }
]

CancelIssue - 발행취소

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

이벤트 본문

순번	변수명	타입	길이	필수	설명
1	corpNum	string	10	Y	전자세금계산서 발행 유형별 작성자 사업자번호 → 정발행 : 공급자 사업자번호 위수탁 : 수탁자 사업자번호
2	itemKey	string	18	Y	팝빌에서 할당한 식별번호
3	ntsconfirmNum	string	24	Y	국세청승인번호 → 전자세금계산서 발행 시점에 팝빌에서 자동으로 할당
4	ntssendDT	string	14	N	국세청 전송일시 → 형식 : yyyyMMddHHmmss
5	ntsresultDT	string	14	N	국세청 결과 수신일시 → 형식 : yyyyMMddHHmmss
6	ntssendErrCode	string	6	N	국세청 결과코드 → [참고] 국세청 결과코드
7	stateCode	number	3	Y	상태코드 → [참고] 팝빌 상태코드
8	stateDT	string	14	Y	상태 변경일시 → 형식 : yyyyMMddHHmmss
9	issueDT	string	14	Y	발행일시 → 형식 : yyyyMMddHHmmss
10	invoicerMgtKey	string	24	N	공급자 문서번호 → 파트너가 할당한 문서번호
11	invoiceeMgtKey	string	24	N	공급받는자 문서번호 → 파트너가 할당한 문서번호
12	trusteeMgtKey	string	24	N	수탁자 문서번호 → 파트너가 할당한 문서번호
13	eventDT	string	14	Y	이벤트 실행일시 → 형식 : yyyyMMddHHmmss
14	eventType	string	30	Y	이벤트 유형 CancelIssue
15	closeDownState	number	1	N	공급받는자 휴폐업상태 null 미확인 0 미등록 1 사업중 2 폐업 3 휴업 4 확인실패
16	closeDownStateDate	string	8	N	공급받는자 휴폐업일자 → 형식 : yyyyMMdd
17	interOPYN	boolean	-	Y	연동문서 여부 true API로 발행한 연동문서 false 팝빌 사이트에서 발행한 일반문서
18	stateMemo	string	200	N	상태메모

이벤트 예시

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

4. 인증서 상태

공동인증서 등록/재등록/삭제에서 발생하는 이벤트입니다.

이벤트 유형	설명
REGIST	공동인증서 등록/재등록
DELETE	공동인증서 삭제

REGIST - 등록/재등록

공동인증서를 등록/재등록 하는 시점에 실행됩니다.

이벤트 본문

순번	변수명	타입	길이	필수	설명
1	corpNum	string	10	Y	팝빌회원 사업자번호
2	expireDT	string	14	N	공동인증서 만료일시 → 형식 : yyyyMMddHHmmss
3	regContactID	string	50	N	공동인증서를 등록한 팝빌 담당자 아이디
4	issuerDN	string	200	N	발급자 DN
5	subjectDN	string	200	N	인증서 DN
6	eventDT	string	14	Y	이벤트 실행일시 → 형식 : yyyyMMddHHmmss
7	eventType	string	30	Y	이벤트 유형 REGIST
8	OID	string	30	N	OID

이벤트 예시

{
    "corpNum": "1234567890",
    "expireDT": "20250706145209",
    "regContactID": "linkhub",
    "issuerDN": "CN=Root CA, OU=Certification Authority, O=Organaization, C=KR",
    "eventType": "REGIST",
    "oid": "1.2.410.200004.5.1.1.5",
    "eventDT": "20250623135523",
    "subjectDN": "CN=홍길동, OU=Organaization Unit, O=Organaization, C=KR"
}

DELETE - 삭제

공동인증서를 삭제 하는 시점에 실행됩니다.

이벤트 본문

순번	변수명	타입	길이	필수	설명
1	corpNum	string	10	Y	팝빌회원 사업자번호
2	eventDT	string	14	Y	이벤트 실행일시 → 형식 : yyyyMMddHHmmss
3	eventType	string	30	Y	이벤트 유형 DELETE

이벤트 예시

{
    "corpNum": "1234567890",
    "eventType": "DELETE",
    "eventDT": "20250623135523"
}