POPBill Developers
가이드

Webhook Bulk 발행 이벤트

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 / NTS

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

이벤트 상세

  • 접수결과

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

    순번 필드명 타입 길이 필수 비고
    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 confirmNum String 24 N 현금영수증 발행 시점에 팝빌에서 자동으로 부여
    4 tradeDate String 8 N 거래일자(형식 : yyyyMMdd)
    5 issueDT String 14 N 발행일시 (형식 : yyyyMMddHHmmss)
    6 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 객체 정보
    순번 필드명 타입 길이 필수 비고
    1 QMNum String 24 Y 팝빌이 생성한 현금영수증 국세청 신고를 위한 고유번호
    2 CORPNUM String 10 Y 현금영수증 대량 접수 시 입력한 사업자번호
    3 TYPE String - Y Webhook 유형 : CASHBILL.STATE
    body 객체 정보
    순번 필드명 타입 길이 필수 비고
    1 corpNum String 10 Y 현금영수증 대량 접수 시 입력한 사업자번호
    2 itemKey String 18 Y 팝빌에서 현금영수증 관리 목적으로 할당한 식별번호
    3 confirmNum String 24 Y 팝빌이 생성한 현금영수증 국세청 신고를 위한 고유번호
    4 ntssendDT String 14 N 국세청 전송일시 (형식 : yyyyMMddHHmmss)
    5 ntsresultDT String 14 N 국세청 결과 수신일시 (형식 : yyyyMMddHHmmss)
    6 ntsresultCode String - N 결과코드
    [참고] 국세청 결과코드
    7 stateCode Number 3 Y 상태코드
    [참고] 팝빌 상태코드
    8 stateDT String 14 Y 상태 변경일시 (형식 : yyyyMMddHHmmss)
    9 issueDT String 14 Y 발행일시 (형식 : yyyyMMddHHmmss)
    10 mgtKey String 24 N 프로그램 공급사가 할당한 공급자 문서번호
    11 eventDT String 14 Y 이벤트 실행일시 (형식 : yyyyMMddHHmmss)
    12 eventType String 30 Y 이벤트 유형 : NTS
    13 interOPYN Boolean - Y 연동문서 여부 : true / false 중 반환
    └ true : API로 발행한 연동문서
    └ 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
            }
        }
    ]