# 발행 ## 1. RegistIssue - 승인 현금영수증 발행 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | --------------------------------------------- | ---------------------------------------- | | POST | | | - 작성된 현금영수증 데이터를 팝빌에 저장과 동시에 발행하여 “발행완료” 상태로 처리합니다. [\[참고\] 팝빌 국세청 전송 정책](https://developers.popbill.com/guide/cashbill/introduction/policy-of-send-to-nts) > 현금영수증 자진발급분은 소득공제 용도로만 발행 가능합니다. (자진발급 번호 : 010-000-1234)\ > 현금영수증 발행시 구매자 메일주소로 발행 안내 메일이 전송되니 유의하시기 바랍니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/cashbill/getting-started/authorization "_blank") - Content-Type `required: Y` `description: 요청 본문 형식` - `application/json` - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-HTTP-Method-Override `required: Y` `description: 요청 메서드 재정의` - `ISSUE` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **요청 본문** - mgtKey `type: string` `length: 24` `required: Y` `description: 문서번호` - 문서 관리를 위해 파트너가 할당하는 식별번호 - 영문 대소문자, 숫자, 특수문자('-','\_')만 이용 가능 - tradeDT `type: string` `length: 14` `required: N` `description: 거래일시` - 전일부터 당일까지 입력 가능 - 형식 : yyyyMMddHHmmss - 기본값 : 발행일시 사용 - tradeType `type: string` `length: 4` `required: Y` `description: 문서형태` - `승인거래` - tradeUsage `type: string` `length: -` `required: Y` `description: 거래구분 (택 1)` - `소득공제용` - `지출증빙용` - tradeOpt `type: string` `length: 4` `required: N` `description: 거래유형` - `일반`: 기본값 - `도서공연` - `대중교통` - 도서공연 : 도서, 공연, 박물관, 미술관, 수영장, 체력단련장, 신문구독료(종이신문), 영화관람료 - taxationType `type: string` `length: -` `required: Y` `description: 과세형태 (택 1)` - `과세` - `비과세` - totalAmount `type: string` `length: 9` `required: Y` `description: 거래금액 (공급가액+부가세+봉사료)` - 양수만 입력 - supplyCost `type: string` `length: 9` `required: Y` `description: 공급가액` - 양수만 입력 - tax `type: string` `length: 9` `required: Y` `description: 부가세` - 양수 또는 0 입력 - serviceFee `type: string` `length: 9` `required: Y` `description: 봉사료` - 양수 또는 0 입력 - franchiseCorpNum `type: string` `length: 10` `required: Y` `description: 가맹점 사업자번호` - 팝빌회원 사업자번호 ('-' 제외) - franchiseTaxRegID `type: string` `length: 4` `required: N` `description: 가맹점 종사업장 식별번호` - 종사업장 식별번호는 4자리 숫자로만 구성 - franchiseCorpName `type: string` `length: 200` `required: N` `description: 가맹점 상호` - franchiseCEOName `type: string` `length: 100` `required: N` `description: 가맹점 대표자 성명` - franchiseAddr `type: string` `length: 400` `required: N` `description: 가맹점 주소` - franchiseTEL `type: string` `length: 20` `required: N` `description: 가맹점 전화번호` - identityNum `type: string` `length: 19` `required: Y` `description: 식별번호` - {tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 입력 - {tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 입력 - 주민등록번호 13자리, 휴대폰번호 10\~11자리, 카드번호 13\~19자리, 사업자번호 10자리 입력 가능 - customerName `type: string` `length: 70` `required: N` `description: 구매자(고객) 성명` - itemName `type: string` `length: 70` `required: N` `description: 주문 상품명` - orderNumber `type: string` `length: 200` `required: N` `description: 주문번호` - email `type: string` `length: 100` `required: N` `description: 구매자(고객) 메일` - hp `type: string` `length: 20` `required: N` `description: 구매자(고객) 휴대폰` - smssendYN `type: boolean` `length: -` `required: N` `description: 구매자 알림문자 전송 여부` - `true`: 전송 - `false`: 미전송 : 기본값 - 수신자 : 구매자 휴대폰번호 {hp} - 문자 전송 포인트가 차감(단, 전송실패 건은 환불) - memo `type: string` `length: 200` `required: N` `description: 현금영수증 상태 이력을 관리하기 위한 메모` - emailSubject `type: string` `length: 300` `required: N` `description: 현금영수증 발행 안내메일 제목` - 기본값 : 팝빌에서 설정한 안내메일 제목 **요청 예시** ```bash curl --request POST \ --url 'https://{domain}/Cashbill' \ --header 'Authorization: Bearer {token}' \ --header 'Content-Type: application/json' \ --header 'X-HTTP-Method-Override: ISSUE' \ --data '{ "mgtKey": "TEST0001", "tradeType": "승인거래", "tradeUsage": "지출증빙용", "taxationType": "과세", "totalAmount": "11000", "supplyCost": "10000", "tax": "1000", "serviceFee": "0", "franchiseCorpNum": "1234567890", "identityNum": "1234567890" }' ``` ### Response **응답 본문** - code `type: number` `length: -` `description: API 처리에 대한 응답코드` - `1`: 성공 - message `type: string` `length: -` `description: API 처리에 대한 응답메시지` - confirmNum `type: string` `length: 9` `description: 국세청승인번호` - 현금영수증 발행 시점에 팝빌에서 자동으로 할당 - tradeDate `type: string` `length: 8` `description: 거래일자` - 현금영수증 발행 시점에 팝빌에서 자동으로 할당 - 형식 : yyyyMMdd **응답 예시** ```json { "code": 1, "message": "발행 완료", "confirmNum": "TB0000032", "tradeDate": "20251023" } ``` ## 2. RevokeRegistIssue - 취소 현금영수증 발행 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | --------------------------------------------- | ---------------------------------------- | | POST | | | - 당초 승인 현금영수증의 취소거래 발행 API 입니다. - 작성된 취소 현금영수증 데이터를 팝빌에 저장과 동시에 발행하여 “발행완료” 상태로 처리합니다. [\[참고\] 팝빌 국세청 전송 정책](https://developers.popbill.com/guide/cashbill/introduction/policy-of-send-to-nts) - 부분 취소 현금영수증을 발행하는 경우 `isPartCancel` 값을 true 로 설정하여 주시기 바랍니다. - 당초 국세청승인번호와 거래일자는 [\[GetInfo – 상태확인\]](https://developers.popbill.com/api-reference/cashbill/api/info#GetInfo)함수를 통해 확인 가능합니다. > 당초 승인 현금영수증의 거래일시보다 과거의 거래일시를 입력할 수 없습니다.\ > 취소 현금영수증의 거래금액의 합은 당초 승인 현금영수증의 거래금액을 넘을 수 없습니다.\ > 취소 현금영수증 발행시 구매자 메일주소로 발행 안내 메일이 전송되니 유의하시기 바랍니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/cashbill/getting-started/authorization) - Content-Type `required: Y` `description: 요청 본문 형식` - `application/json` - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-HTTP-Method-Override `required: Y` `description: 요청 메서드 재정의` - `REVOKEISSUE` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **요청 본문** - mgtKey `type: string` `length: 24` `required: Y` `description: 파트너가 할당한 문서번호` - 영문 대소문자, 숫자, 특수문자('-','\_')만 이용 가능 - orgConfirmNum `type: string` `length: 9` `required: Y` `description: 당초 국세청승인번호` - [\[GetInfo - 상태 확인\]](https://developers.popbill.com/api-reference/cashbill/api/info#GetInfo) API의 리턴값 confirmNum을 통해 내용 확인 가능 - orgTradeDate `type: string` `length: 8` `required: Y` `description: 당초 거래일자` - [\[GetInfo - 상태 확인\]](https://developers.popbill.com/api-reference/cashbill/api/info#GetInfo) API의 리턴값 tradeDate를 통해 내용 확인 가능 - smssendYN `type: boolean` `length: -` `required: N` `description: 현금영수증 발행시 알림문자 전송 여부` - `true`: 전송 - `false`: 미전송 : 기본값 - 당초 승인 현금영수증의 구매자(고객)의 휴대폰번호 문자 전송 - memo `type: string` `length: 200` `required: N` `description: 현금영수증 상태 이력을 관리하기 위한 메모` - isPartCancel `type: boolean` `length: -` `required: N` `description: 현금영수증 취소유형` - `true`: 부분 취소 - `false`: 전체 취소 : 기본값 - cancelType `type: number` `length: 1` `required: N` `description: 현금영수증 취소사유` - `1`: 거래취소 : 기본값 - `2`: 오류발급취소 - `3`: 기타 - supplyCost `type: string` `length: 9` `required: 조건부` `description: 부분 취소 공급가액` - 양수만 입력 - {isPartCancel}=true 경우 필수 - tax `type: string` `length: 9` `required: 조건부` `description: 부분 취소 부가세` - 양수 또는 0 입력 - {isPartCancel}=true 경우 필수 - serviceFee `type: string` `length: 9` `required: 조건부` `description: 부분 취소 봉사료` - 양수 또는 0 입력 - {isPartCancel}=true 경우 필수 - totalAmount `type: string` `length: 9` `required: 조건부` `description: 부분 취소 거래금액` - 양수만 입력 - 거래금액 = 공급가액 + 부가세 + 봉사료 - {isPartCancel}=true 경우 필수 - emailSubject `type: string` `length: 300` `required: N` `description: 현금영수증 발행 안내메일 제목` - 기본값 : 팝빌에서 설정한 안내메일 제목 - tradeDT `type: string` `length: 14` `required: N` `description: 거래일시` - 전일부터 당일까지 입력 가능 - 형식 : yyyyMMddHHmmss - 기본값 : 발행일시 사용 **요청 예시** ```bash curl --request POST \ --url 'https://{domain}/Cashbill' \ --header 'Authorization: Bearer {token}' \ --header 'Content-Type: application/json' \ --header 'X-HTTP-Method-Override: REVOKEISSUE' \ --data '{ "mgtKey": "TEST0002", "orgConfirmNum": "TB0000032", "orgTradeDate": "20251023" }' ``` ### Response **응답 본문** - code `type: number` `length: -` `description: API 처리에 대한 응답코드` - `1`: 성공 - message `type: string` `length: -` `description: API 처리에 대한 응답메시지` - confirmNum `type: string` `length: 9` `description: 국세청승인번호` - 현금영수증 발행 시점에 팝빌에서 자동으로 할당 - tradeDate `type: string` `length: 8` `description: 거래일자` - 현금영수증 발행 시점에 팝빌에서 자동으로 할당 - 형식 : yyyyMMdd **응답 예시** ```json { "code": 1, "message": "발행 완료", "confirmNum": "TB0000032", "tradeDate": "20251023" } ``` ## 3. BulkSubmit - 초대량 발행 접수 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | --------------------------------------------- | ---------------------------------------- | | POST | | | - 최대 100건의 현금영수증 발행을 한번의 요청으로 접수합니다. > 현금영수증 자진발급분은 소득공제 용도로만 발행 가능합니다. (자진발급 번호 : 010-000-1234)\ > 현금영수증 발행시 구매자 메일주소로 발행 안내 메일이 전송되니 유의하시기 바랍니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/cashbill/getting-started/authorization) - Content-Type `required: Y` `description: 요청 본문 형식` - `application/json` - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-Submit-ID `required: Y` `description: 제출아이디` - 영문, 숫자, '-' 조합으로 최대 36자 길이로 구성 - X-HTTP-Method-Override `required: Y` `description: 요청 메서드 재정의` - `BULKISSUE` - X-PB-Message-Digest `required: Y` `description: Message Digest` - 요청 본문의 무결성을 검증하는데 사용 - [\[참고\] X-PB-Message-Digest](https://developers.popbill.com/api-reference/cashbill/getting-started/etc-header#x-pb-message-digest) - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **요청 본문** - cashbills `type: array` `length: -` `required: Y` `description: 현금영수증 목록` - 최대 : 100건 - mgtKey `type: string` `length: 24` `required: Y` `description: 문서번호` - 문서 관리를 위해 파트너가 할당하는 식별번호 - 영문 대소문자, 숫자, 특수문자('-','\_')만 이용 가능 - tradeDT `type: string` `length: 14` `required: N` `description: 거래일시` - 전일부터 당일까지 입력 가능 - 형식 : yyyyMMddHHmmss - 기본값 : 발행일시 사용 - tradeType `type: string` `length: 4` `required: Y` `description: 문서형태` - `승인거래` - tradeUsage `type: string` `length: -` `required: Y` `description: 거래구분 (택 1)` - `소득공제용` - `지출증빙용` - tradeOpt `type: string` `length: 4` `required: N` `description: 거래유형` - `일반`: 기본값 - `도서공연` - `대중교통` - 도서공연 : 도서, 공연, 박물관, 미술관, 수영장, 체력단련장, 신문구독료(종이신문), 영화관람료 - taxationType `type: string` `length: -` `required: Y` `description: 과세형태 (택 1)` - `과세` - `비과세` - totalAmount `type: string` `length: 9` `required: Y` `description: 거래금액 (공급가액+부가세+봉사료)` - 양수만 입력 - supplyCost `type: string` `length: 9` `required: Y` `description: 공급가액` - 양수만 입력 - tax `type: string` `length: 9` `required: Y` `description: 부가세` - 양수 또는 0 입력 - serviceFee `type: string` `length: 9` `required: Y` `description: 봉사료` - 양수 또는 0 입력 - franchiseCorpNum `type: string` `length: 10` `required: Y` `description: 가맹점 사업자번호` - 팝빌회원 사업자번호 ('-' 제외) - franchiseTaxRegID `type: string` `length: 4` `required: N` `description: 가맹점 종사업장 식별번호` - 종사업장 식별번호는 4자리 숫자로만 구성 - franchiseCorpName `type: string` `length: 200` `required: N` `description: 가맹점 상호` - franchiseCEOName `type: string` `length: 100` `required: N` `description: 가맹점 대표자 성명` - franchiseAddr `type: string` `length: 400` `required: N` `description: 가맹점 주소` - franchiseTEL `type: string` `length: 20` `required: N` `description: 가맹점 전화번호` - identityNum `type: string` `length: 19` `required: Y` `description: 식별번호` - {tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 입력 - {tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 입력 - 주민등록번호 13자리, 휴대폰번호 10\~11자리, 카드번호 13\~19자리, 사업자번호 10자리 입력 가능 - customerName `type: string` `length: 70` `required: N` `description: 구매자(고객) 성명` - itemName `type: string` `length: 70` `required: N` `description: 주문 상품명` - orderNumber `type: string` `length: 200` `required: N` `description: 주문번호` - email `type: string` `length: 100` `required: N` `description: 구매자(고객) 메일` - hp `type: string` `length: 20` `required: N` `description: 구매자(고객) 휴대폰` - smssendYN `type: boolean` `length: -` `required: N` `description: 구매자 알림문자 전송 여부` - `true`: 전송 - `false`: 미전송 : 기본값 - 수신자 : 구매자 휴대폰번호 {hp} - 문자 전송 포인트가 차감(단, 전송실패 건은 환불) - memo `type: string` `length: 200` `required: N` `description: 현금영수증 상태 이력을 관리하기 위한 메모` - emailSubject `type: string` `length: 300` `required: N` `description: 현금영수증 발행 안내메일 제목` - 기본값 : 팝빌에서 설정한 안내메일 제목 **요청 예시** ```bash curl --request POST \ --url 'https://{domain}/Cashbill' \ --header 'Authorization: Bearer {token}' \ --header 'Content-Type: application/json' \ --header 'X-HTTP-Method-Override: BULKISSUE' \ --header 'X-PB-Submit-ID: {submitID}' \ --header 'X-PB-Message-Digest: {messageDigest}' \ --data '{ "cashbills": [ { "mgtKey": "TEST0004", "tradeType": "승인거래", "tradeUsage": "지출증빙용", "taxationType": "과세", "totalAmount": "11000", "supplyCost": "10000", "tax": "1000", "serviceFee": "0", "franchiseCorpNum": "1234567890", "identityNum": "1234567890" } ] }' ``` ### Response **응답 본문** - code `type: number` `length: -` `description: API 처리에 대한 응답코드` - `1`: 성공 - message `type: string` `length: -` `description: API 처리에 대한 응답메시지` - receiptID `type: string` `length: 36` `description: 접수아이디` **응답 예시** ```json { "code": 1, "message": "접수 완료", "receiptID": "0251024-f842ed73b6004518bf5bc73c1d9f" } ``` ## 4. GetBulkResult - 초대량 접수결과 확인 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | ------------------------------------------------------------------- | -------------------------------------------------------------- | | GET | | | - 접수시 기재한 SubmitID를 사용하여 현금영수증 접수결과를 확인합니다. - 개별 현금영수증 처리상태는 접수상태(txState)가 완료(2) 시 반환됩니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/cashbill/getting-started/authorization) - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **Path 파라미터** - submitID `type: string` `length: 36` `required: Y` `description: 파트너가 할당한 제출아이디` **요청 예시** ```bash curl --request GET \ --url 'https://{domain}/Cashbill/BULK/{submitID}/State' \ --header 'Authorization: Bearer {token}' ``` ### Response **응답 본문** - code `type: number` `length: -` `description: API 처리에 대한 응답코드` - `1`: 성공 - message `type: string` `length: -` `description: API 처리에 대한 응답메시지` - submitID `type: string` `length: 36` `description: 접수 시점에 고객사에서 할당한 제출아이디` - submitCount `type: number` `length: -` `description: 현금영수증 접수 건수` - successCount `type: number` `length: -` `description: 현금영수증 발행 성공 건수` - failCount `type: number` `length: -` `description: 현금영수증 발행 실패 건수` - txState `type: number` `length: 1` `description: 접수상태` - `0`: 접수 - `1`: 처리중 - `2`: 처리완료 - txResultCode `type: number` `length: -` `description: 접수 결과코드` - 성공 : 1 - 실패 : 음의 정수 8자리 숫자값 [\[참고\] 오류코드](https://developers.popbill.com/error-code "_blank") - txStartDT `type: string` `length: 14` `description: 발행처리 시작일시` - 형식 : yyyyMMddHHmmss - txEndDT `type: string` `length: 14` `description: 발행처리 완료일시` - 형식 : yyyyMMddHHmmss - receiptID `type: string` `length: 36` `description: 접수아이디` - 접수 시점에 팝빌에서 자동으로 할당 - issueResult `type: array` `length: -` `description: 발행결과` - code `type: number` `length: -` `description: API 처리에 대한 응답코드` - `1`: 성공 - message `type: string` `length: -` `description: API 처리에 대한 응답메시지` - mgtKey `type: string` `length: 24` `description: 문서번호` - confirmNum `type: string` `length: 9` `description: 국세청승인번호` - 현금영수증 발행 시점에 팝빌에서 자동으로 할당 - tradeDate `type: string` `length: 8` `description: 거래일자` - 현금영수증 발행 시점에 팝빌에서 자동으로 할당 - {tradeDT}의 yyyyMMdd - issueDT `type: string` `length: 14` `description: 발행일시` - 형식 : yyyyMMddHHmmss - receiptDT `type: string` `length: 14` `description: 접수일시` - 형식 : yyyyMMddHHmmss **응답 예시** ```json { "code": 1, "message": "확인 완료", "receiptID": "0251024-bf8026eae6d64e44854593e5fa82", "submitID": "20251024-JAVA3", "submitCount": 5, "successCount": 5, "failCount": 0, "txState": 2, "txStartDT": "20251024140659", "txEndDT": "20251024140700", "txResultCode": 1, "issueResult": [ { "mgtKey": "20251024-0", "code": 1, "confirmNum": "TB0000048", "tradeDate": "20251024", "issueDT": "20251024140659" } ], "receiptDT": "20251024140659" } ``` ## 5. Delete - 삭제 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | ------------------------------------------------------ | ------------------------------------------------- | | POST | | | - 삭제 가능한 상태의 현금영수증을 삭제합니다.\ ※ 삭제 가능한 상태: “전송실패” > 삭제 처리된 현금영수증의 문서번호는 재사용이 가능합니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/cashbill/getting-started/authorization) - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-HTTP-Method-Override `required: Y` `description: 요청 메서드 재정의` - `DELETE` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **Path 파라미터** - MgtKey `type: string` `length: 24` `required: Y` `description: 파트너가 할당한 문서번호` **요청 예시** ```bash curl --request POST \ --url 'https://{domain}/Cashbill/{MgtKey}' \ --header 'Authorization: Bearer {token}' \ --header 'X-HTTP-Method-Override: DELETE' ``` ### Response **응답 본문** - code `type: number` `length: -` `description: API 처리에 대한 응답코드` - `1`: 성공 - message `type: string` `length: -` `description: API 처리에 대한 응답메시지` **응답 예시** ```json { "code": 1, "message": "삭제 완료" } ```