POPBill Developers
가이드

Webhook Bulk 발행 이벤트

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 이벤트 유형
└ BULK.RESULT / BULK.CLOSEDOWN / BULK.NTS / CancelIssue

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

Bulk 발행 이벤트 상세

  • 접수결과

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

    순번 필드명 타입 길이 필수 설명
    1 corpNum String 10 Y 전자세금계산서 발행 유형별 작성자 사업자번호
    └ 정발행 : 공급자 사업자번호
    └ 위수탁발행 : 수탁자 사업자번호
    2 submitID String 36 Y 프로그램 공급사가 할당한 Bulk 발행 접수 식별을 위한 고유번호
    3 receiptID String 36 Y 접수 아이디
    └ 팝빌이 생성한 Bulk 발행 접수 식별을 위한 고유번호
    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 중 반환
    └ 0 : 접수
    └ 1 : 처리중
    └ 2 : 처리완료
    11 txResultCode Number - N 접수결과코드 : 1
    12 txStartDT String 14 N 발행처리 시작일시
    형식 : yyyyMMddHHmmss
    13 txEndDT String 14 N 발행처리 완료일시
    형식 : yyyyMMddHHmmss
    14 issueResult Object 100 N 접수된 전자세금계산서 발행 결과
    └ 하단의 테이블 참고
    issueResult 객체 정보
    순번 필드명 타입 길이 필수 설명
    1 code Number - Y 발행 처리에 대한 결과코드 반환
    └ 처리결과가 성공일 경우 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 위수탁발행시 공급자의 문서 관리를 위해 파트너가 할당하는 식별번호
    Request Body 예시
    {  
      "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",
          },
          ...
        ]
    }
  • 휴폐업조회 결과

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

    header 객체 정보
    순번 필드명 타입 길이 필수 설명
    1 QMNum String 24 Y 팝빌이 생성한 전자세금계산서 국세청 신고를 위한 고유번호
    2 CORPNUM String 10 Y 전자세금계산서 발행 유형별 작성자 사업자번호
    └ 정발행 : 공급자 사업자번호
    └ 위수탁발행 : 수탁자 사업자번호
    3 TYPE String - Y Webhook 유형 : TAXINVOICE.STATE
    body 객체 정보
    순번 필드명 타입 길이 필수 설명
    1 corpNum String 10 Y 전자세금계산서 발행 유형별 작성자 사업자번호
    └ 정발행 : 공급자 사업자번호
    └ 위수탁발행 : 수탁자 사업자번호
    2 itemKey String 18 Y 팝빌에서 세금계산서 관리 목적으로 할당한 식별번호
    3 ntsConfirmNum String 24 Y 팝빌이 생성한 전자세금계산서 국세청 신고를 위한 고유번호
    4 stateCode Number 3 Y 상태코드
    [참고] 팝빌 상태코드
    5 stateDT String 14 Y 상태 변경일시
    형식 : yyyyMMddHHmmss
    6 issueDT String 14 Y 발행일시
    형식 : yyyyMMddHHmmss
    7 invoicerMgtKey String 24 N 프로그램 공급사가 할당한 공급자 문서번호
    8 trusteeMgtKey String 24 N 프로그램 공급사가 할당한 수탁자 문서번호
    9 eventDT String 14 Y 이벤트 실행일시 (형식 : yyyyMMddHHmmss)
    10 eventType String 30 Y 이벤트 유형 : CLOSEDOWN
    11 closeDownState Number 1 Y 공급받는자 휴폐업상태 : 0 / 1 / 2 / 3 / 4 중 반환
    └ 0 : 미등록
    └ 1 : 사업중
    └ 2 : 폐업 (폐업일자 확인 가능)
    └ 3 : 휴업 (휴업일자 확인 가능)
    └ 4 : 확인실패
    12 closeDownStateDate String 8 N 공급받는자 휴페업일자 closeDownState "2(폐업)" 또는 "3(휴업)" 인 경우 확인 (형식 : yyyyMMdd)
    12 interOPYN Boolean - Y 연동문서 여부 : true / false
    └ true : API로 발행한 연동문서
    └ false : 팝빌 사이트에서 발행한 일반문서
    Request Body 예시
    [
    	{
    		"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"
    		}
    	},
    	...
    ]
    
  • 국세청 전송 처리결과

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

    header 객체 정보
    순번 필드명 타입 길이 필수 설명
    1 QMNum String 24 Y 팝빌이 생성한 전자세금계산서 국세청 신고를 위한 고유번호
    2 CORPNUM String 10 Y 전자세금계산서 발행 유형별 작성자 사업자번호
    └ 정발행 : 공급자 사업자번호
    └ 위수탁발행 : 수탁자 사업자번호
    3 TYPE String - Y Webhook 유형 : TAXINVOICE.STATE
    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 - 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 Y 공급받는자 휴폐업상태 : 0 / 1 / 2 / 3 / 4 중 반환
    └ 0 : 미등록
    └ 1 : 사업중
    └ 2 : 폐업 (폐업일자 확인 가능)
    └ 3 : 휴업 (휴업일자 확인 가능)
    └ 4 : 확인실패
    15 closeDownStateDate String 8 N 공급받는자 휴페업일자 closeDownState "2(폐업)" 또는 "3(휴업)" 인 경우 확인 (형식 : yyyyMMdd)
    16 interOPYN Boolean - Y 연동문서 여부 : true / false
    └ true : API로 발행한 연동문서
    └ false : 팝빌 사이트에서 발행한 일반문서
    Request Body 예시
    [
    	{
    		"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"
    		}
    	},
    	...
    ]
  • 발행취소

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

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