POPBill Developers
가이드

Webhook 단건 발행 이벤트

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 / CancelIssue / CLOSEDOWN / NTS / OPEN / Request / CancelRequest / Refuse

팝빌은 기본으로 제공되는 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 공급받는자 휴폐업상태 : 0 / 1 / 2 / 3 / 4 중 반환
└ 0 : 미등록
└ 1 : 사업중
└ 2 : 폐업 (폐업일자 확인 가능)
└ 3 : 휴업 (휴업일자 확인 가능)
└ 4 : 확인실패
closeDownStateDate String 8 N 공급받는자 휴페업일자 closeDownState "2(폐업)" 또는 "3(휴업)" 인 경우 확인 (형식 : yyyyMMdd)
interOPYN Boolean - Y 연동문서 여부 : true / false 중 반환
└ true : API로 발행한 연동문서
└ false : 팝빌 사이트에서 발행한 일반문서
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"
    }
  • 발행취소

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

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