POPBill Developers
Webhook

이벤트 데이터 - Bulk

현금영수증 대량발행(Bulk) 웹훅에서 발생하는 이벤트입니다.

이벤트 타입 설명
BULK.RESULT 현금영수증 대량발행 접수결과
NTS 현금영수증 국세청 전송 처리결과

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

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

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

이벤트 예시

현금영수증 대량발행(Bulk) 웹훅에서 발생하는 이벤트 예시입니다.
각 이벤트 발생시점은 [발행유형]의 상태확인 내용에서 확인 가능합니다.

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

  • 접수결과

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

    필드명 타입 길이 필수 설명
    corpNum String 10 Y 팝빌회원 사업자번호 ('-' 제외)
    franchiseCorpNum String 10 Y 현금영수증 대량 접수 시 입력한 사업자번호
    submitID String 36 Y 접수 시점에 고객사에서 할당한 제출아이디
    receiptID String 36 Y 접수 아이디
    접수 시점에 팝빌에서 자동으로 할당
    receiptDT String 14 Y 접수일시
    형식 : yyyyMMddHHmmss
    eventType String - Y 이벤트 유형
    BULK.RESULT
    eventDT String 14 Y 이벤트 실행 일시
    형식 : yyyyMMddHHmmss
    submitCount Number - Y 현금영수증 접수 건수
    successCount Number - Y 현금영수증 발행 성공 건수
    failCount Number - Y 현금영수증 발행 실패 건수
    txState Number 1 Y 접수상태
    0접수
    1처리중
    2처리완료
    txResultCode Number - N 접수 결과코드
    - 성공 : 1
    - 실패 : 음의 정수 8자리 숫자값 [참고] 오류코드
    txStartDT String 14 N 발행처리 시작일시
    형식 : yyyyMMddHHmmss
    txEndDT String 14 N 발행처리 완료일시
    형식 : yyyyMMddHHmmss
    issueResult Object 100 N 접수된 현금영수증 발행 결과
    하단의 테이블 참고
    issueResult 객체 정보
    필드명 타입 길이 필수 설명
    code Number - Y API 처리에 대한 응답코드
    - 성공 : 1
    - 실패 : 음의 정수 8자리 숫자값 [참고] 오류코드
    message String - N API처리에 대한 응답 메시지
    confirmNum String 24 N 국세청승인번호
    현금영수증 발행 시점에 팝빌에서 자동으로 할당
    tradeDate String 8 N 거래일자
    형식 : yyyyMMdd
    issueDT String 14 N 발행일시
    형식 : yyyyMMddHHmmss
    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 객체 정보
    필드명 타입 길이 필수 설명
    QMNum String 24 Y 팝빌이 생성한 현금영수증 국세청 신고를 위한 고유번호
    CORPNUM String 10 Y 현금영수증 대량 접수 시 입력한 사업자번호
    TYPE String - Y Webhook 유형
    CASHBILL.STATE
    body 객체 정보
    필드명 타입 길이 필수 설명
    corpNum String 10 Y 현금영수증 대량 접수 시 입력한 사업자번호
    itemKey String 18 Y 팝빌에서 현금영수증 관리 목적으로 할당한 식별번호
    confirmNum String 24 Y 국세청승인번호
    현금영수증 발행 시점에 팝빌에서 자동으로 할당
    ntssendDT String 14 N 국세청 전송일시
    형식 : yyyyMMddHHmmss
    ntsresultDT String 14 N 국세청 결과 수신일시
    형식 : yyyyMMddHHmmss
    ntsresultCode String - N 결과코드
    stateCode Number 3 Y 상태코드
    stateDT String 14 Y 상태 변경일시
    형식 : yyyyMMddHHmmss
    issueDT String 14 Y 발행일시
    형식 : yyyyMMddHHmmss
    mgtKey String 24 N 문서번호
    파트너가 할당한 문서번호
    eventDT String 14 Y 이벤트 실행일시
    형식 : yyyyMMddHHmmss
    eventType String 30 Y 이벤트 유형
    NTS
    interOPYN Boolean - Y 연동문서 여부
    trueAPI로 발행한 연동문서
    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
            }
        }
    ]