POPBill Developers
가이드

서비스에 대한 정확한 이해로
최적의 구현방식을 적용합니다.

API Reference

서비스에 대한 정확한 이해로
최적의 구현방식을 적용합니다.

SDK

다수 개발자에게 검증받은
SDK Example을 제공합니다.

추가 개발언어는 신청주시면
검토 후 지원합니다.
Webhook(웹훅)

팝빌에서 발생한 이벤트 정보를
고객사 서버로 즉시 전송합니다.

API Reference
현금영수증
Node.js
API Reference 현금영수증 Node.js 객체정보

A. 객체정보

Response

순번변수명타입길이설명
code number - API 처리에 대한 응답코드
1성공
message string - API 처리에 대한 응답메시지

IssueResponse

순번변수명타입길이설명
code number - API 처리에 대한 응답코드
1성공
message string - API 처리에 대한 응답메시지
confirmNum string 9 국세청승인번호
현금영수증 발행 시점에 팝빌에서 자동으로 할당
tradeDate string 8 거래일자
현금영수증 발행 시점에 팝빌에서 자동으로 할당
형식 : yyyyMMdd

PopbillException

순번변수명타입길이설명
code number - API 처리 실패에 대한 오류코드
음의 정수 8자리 숫자값 [참고] 오류코드
message string - API 처리 실패에 대한 오류메시지

Cashbill - 입력부

순번변수명타입길이필수설명
mgtKey string 24 Y 문서번호
문서 관리를 위해 파트너가 할당하는 식별번호
영문 대소문자, 숫자, 특수문자('-','_')만 이용 가능
orgConfirmNum string 9 조건부 당초 승인 현금영수증 국세청승인번호
취소 현금영수증 작성시 필수
orgTradeDate string 9 조건부 당초 승인 현금영수증 거래일자
취소 현금영수증 작성시 필수
tradeDT string 14 N 거래일시
전날부터 당일까지 입력 가능
형식 : yyyyMMddHHmmss
기본값 : 발행일시 사용
tradeType string 4 Y 문서형태 (택 1)
승인거래
취소거래
tradeUsage string - Y 거래구분 (택 1)
소득공제용
지출증빙용
tradeOpt string 4 N 거래유형
일반 : 기본값
도서공연
대중교통
taxationType string - Y 과세형태 (택 1)
과세
비과세
totalAmount string 9 Y 거래금액
양수만 입력
supplyCost string 9 Y 공급가액
양수만 입력
tax string 9 Y 부가세
양수만 입력
serviceFee string 9 Y 봉사료
양수만 입력
franchiseCorpNum string 10 Y 가맹점 사업자번호
팝빌회원 사업자번호 ('-' 제외)
franchiseTaxRegID string 4 N 가맹점 종사업장 식별번호
종사업장 식별번호는 4자리 숫자로만 구성
franchiseCorpName string 200 N 가맹점 상호
franchiseCEOName string 100 N 가맹점 대표자 성명
franchiseAddr string 400 N 가맹점 주소
franchiseTEL string 20 N 가맹점 전화번호
identityNum string 19 Y 식별번호
- {tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 입력
- {tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 입력
주민등록번호 13자리, 휴대폰번호 10~11자리, 카드번호 13~19자리, 사업자번호 10자리 입력 가능
customerName string 70 N 구매자(고객) 성명
itemName string 70 N 주문 상품명
orderNumber string 200 N 주문번호
email string 100 N 구매자(고객) 이메일
hp string 20 N 구매자(고객) 휴대폰
smssendYN boolean - N 구매자 알림문자 전송 여부
true전송
false미전송 : 기본값
수신자 : 구매자 휴대폰번호 {hp}
문자 전송 포인트가 차감(단, 전송실패 건은 환불)
cancelType number 1 N 취소사유
1거래취소 : 기본값
2오류발급취소
3기타
{tradeType}="취소거래" 경우 입력
memo string 200 N 현금영수증 상태 이력을 관리하기 위한 메모
대량(Bulk)발행 경우 사용
emailSubject string 300 N 현금영수증 발행 안내메일 제목
기본값 : 팝빌에서 설정한 안내메일 제목

Cashbill - 출력부

순번변수명타입길이설명
mgtKey string 24 문서번호
문서 관리를 위해 파트너가 할당하는 식별번호
confirmNum string 9 국세청승인번호
현금영수증 발행 시점에 팝빌에서 자동으로 할당
orgConfirmNum string 9 당초 승인 현금영수증 국세청승인번호
{tradeType}="취소거래" 경우 반환
orgTradeDate string 9 당초 승인 현금영수증 거래일자
{tradeType}="취소거래" 경우 반환
tradeDate string 8 거래일자
현금영수증 발행 시점에 팝빌에서 자동으로 할당
{tradeDT}의 yyyyMMdd
tradeDT string 14 거래일시
형식 : yyyyMMddHHmmss
tradeType string 4 문서형태
승인거래
취소거래
tradeUsage string 5 거래구분
소득공제용
지출증빙용
tradeOpt string 4 거래유형
일반
도서공연
대중교통
taxationType string 3 과세형태
과세
비과세
totalAmount string 9 거래금액
supplyCost string 9 공급가액
tax string 9 부가세
serviceFee string 9 봉사료
franchiseCorpNum string 10 가맹점 사업자번호
팝빌회원 사업자번호 ('-' 제외)
franchiseTaxRegID string 4 가맹점 종사업장 식별번호
종사업장 식별번호는 4자리 숫자로만 구성
franchiseCorpName string 200 가맹점 상호
franchiseCEOName string 100 가맹점 대표자 성명
franchiseAddr string 400 가맹점 주소
franchiseTEL string 20 가맹점 전화번호
identityNum string 19 식별번호
- {tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 반환
- {tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 반환
customerName string 70 구매자(고객) 성명
itemName string 70 주문 상품명
orderNumber string 200 주문번호
email string 100 구매자(고객) 이메일
hp string 20 구매자(고객) 휴대폰
smssendYN boolean - 구매자 알림문자 전송 여부
true전송
false미전송
수신자 : 구매자 휴대폰번호 {hp}
cancelType number 1 취소사유
1거래취소
2오류발급취소
3기타
{tradeType}="취소거래" 경우 반환

BulkResponse

순번변수명타입길이설명
code number - API 처리에 대한 응답코드
1성공
message string - API 처리에 대한 응답메시지
receiptID string 24 접수아이디
접수 시점에 팝빌에서 자동으로 할당

BulkCashbillResult

순번변수명타입길이설명
code number - API 처리에 대한 응답코드
1성공
message string - API 처리에 대한 응답메시지
submitID string 36 접수 시점에 고객사에서 할당한 제출아이디
submitCount number - 현금영수증 접수 건수
successCount number - 현금영수증 발행 성공 건수
failCount number - 현금영수증 발행 실패 건수
txState number 1 접수상태
0접수
1처리중
2처리완료
txResultCode number - 접수 결과코드
- 성공 : 1
- 실패 : 음의 정수 8자리 숫자값 [참고] 오류코드
txStartDT string 14 발행처리 시작일시
형식 : yyyyMMddHHmmss
txEndDT string 14 발행처리 완료일시
형식 : yyyyMMddHHmmss
receiptDT string 14 접수일시
형식 : yyyyMMddHHmmss
issueResult BulkCashbillIssueResult[] 발행결과
receiptID string 36 접수아이디
접수 시점에 팝빌에서 자동으로 할당

BulkCashbillIssueResult

순번변수명타입길이설명
code number - API 처리에 대한 응답코드
1성공
message string - API 처리에 대한 응답메시지
mgtKey string 24 문서번호
confirmNum string 9 국세청승인번호
현금영수증 발행 시점에 팝빌에서 자동으로 할당
tradeDate string 8 거래일자
현금영수증 발행 시점에 팝빌에서 자동으로 할당
형식 : yyyyMMdd
issueDT string 14 발행일시
형식 : yyyyMMddHHmmss

CBSearchResult

순번변수명타입길이설명
code string - API 처리에 대한 응답코드
1성공
message string - API 처리에 대한 응답메시지
total string - 총 검색결과 건수
perPage string - 페이지당 목록 건수
pageNum string - 페이지 번호
pageCount string - 페이지 개수
list CashbillInfo[] 현금영수증 상태/요약정보
함수 [GetInfo - 상태 확인]의 리턴값 구성과 동일
최대 1,000건

CashbillInfo

순번변수명타입길이설명
itemKey string 18 팝빌에서 현금영수증 관리 목적으로 할당한 식별번호
mgtKey string 24 문서번호
파트너가 할당하는 식별번호
tradeDate string 8 거래일자
형식 : yyyyMMdd
tradeDT string 14 거래일시
형식 : yyyyMMddHHmmss
tradeType string 4 문서형태
승인거래
취소거래
tradeUsage string 5 거래구분
소득공제용
지출증빙용
tradeOpt string 4 거래유형
일반
도서공연
대중교통
taxationType string 3 과세형태
과세
비과세
totalAmount string 9 거래금액
supplyCost string 9 공급가액
양수만 입력
tax string 9 부가세
양수만 입력
serviceFee string 9 봉사료
양수만 입력
issueDT string 14 발행일시
형식 : yyyyMMddHHmmss
regDT string 14 등록일시
형식 : yyyyMMddHHmmss
stateCode number 3 상태코드
[참고] 팝빌 상태코드
stateDT string 14 상태 변경일시
형식 : yyyyMMddHHmmss
identityNum string 19 식별번호
- {tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 반환
- {tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 반환
itemName string 70 주문상품명
orderNumber string 200 주문번호
email string 100 구매자(고객) 이메일
hp string 20 구매자(고객) 휴대폰
customerName string 70 구매자(고객) 성명
confirmNum string 9 국세청승인번호
현금영수증 발행 시점에 팝빌에서 자동으로 할당
orgConfirmNum string 9 당초 승인 현금영수증 국세청승인번호
{tradeType}="취소거래" 경우 반환
orgTradeDate string 8 당초 승인 현금영수증 거래일자
{tradeType}="취소거래" 경우 반환
ntssendDT string 14 국세청 전송일시
형식 : yyyyMMddHHmmss
ntsresultDT string 14 국세청 처리결과 수신일시
형식 : yyyyMMddHHmmss
ntsresultCode string 4 결과코드
[참고] 국세청 결과코드
ntsresultMessage string 30 결과메시지
printYN boolean - 인쇄여부
true인쇄
false미인쇄
interOPYN boolean - 연동문서 여부
trueAPI를 통해 발행한 연동문서
false팝빌 사이트를 통해 발행한 문서

EmailSendConfig

순번변수명타입길이설명
emailType string 9 메일전송유형
CSH_ISSUE
고객에게 현금영수증이 발행 되었음을 알려주는 메일
sendYN boolean - 전송여부
true전송
false미전송

UseHistoryResult

순번변수명타입길이설명
code number - API 처리에 대한 응답코드
1성공
total number - 총 검색결과 건수
perPage number - 페이지당 목록 건수
pageNum number - 페이지 번호
pageCount number - 페이지 개수
list UseHistory[] 사용내역

UseHistory

순번변수명타입길이설명
itemCode string 3 서비스 코드
  • 110세금계산서
  • 111홈택스수집(세금)
  • 121거래명세서
  • 122청구서
  • 123견적서
  • 124발주서
  • 125입금표
  • 126영수증
  • 140현금영수증
  • 141홈택스수집(현금)
  • 150문자(SMS)
  • 151문자(LMS)
  • 152문자(MMS)
  • 153알림톡
  • 154친구톡(텍스트)
  • 155친구톡(이미지)
  • 160팩스(일반망)
  • 161팩스(지능망)
  • 170사업자등록상태조회
  • 171기업정보조회
  • 180계좌조회
  • 182계좌성명조회
  • 183계좌실명조회
txType string 2 포인트 증감 유형
포인트 증가
  • 11포인트 충전
  • 12조정
  • 13조정
  • 19분배
  • 31환불
  • 32정액제 해지
포인트 감소
  • 21서비스 사용
  • 22조정
  • 23조정
  • 24포인트 결제
  • 25미수금 결제
  • 26포인트 환불
  • 29회수
  • 41후불누적조정
txPoint string 18 증감 포인트
balance string 18 잔여포인트
txDT string 14 포인트 증감 일시
형식 : yyyyMMddHHmmss
userID string 50 담당자 아이디
userName string 100 담당자명

PaymentHistoryResult

순번변수명타입길이설명
code number - API 처리에 대한 응답코드
1성공
total number - 총 검색결과 건수
perPage number - 페이지당 목록 건수
pageNum number - 페이지 번호
pageCount number - 페이지 개수
list PaymentHistory[] 결제내역

PaymentHistory

순번변수명타입길이설명
productType string 3 결제 내용
포인트
정액제
미수금
productName string 30 결제 상품명
settleType string 7 결제유형
무통장
신용카드
실시간계좌이체
settlerName string 100 담당자명
settlerEmail string 100 담당자메일
settleCost string 18 결제금액
settlePoint string 18 충전포인트
settleState number 1 결제상태
  • 1대기
  • 2승인
  • 3실패
  • 45취소
regDT string 14 등록일시
형식 : yyyyMMddHHmmss
stateDT string 14 상태일시
형식 : yyyyMMddHHmmss

RefundHistoryResult

순번변수명타입길이설명
code number - API 처리에 대한 응답코드
1성공
total number - 총 검색결과 건수
perPage number - 페이지당 목록 건수
pageNum number - 페이지 번호
pageCount number - 페이지 개수
list RefundHistory[] 환불내역

RefundHistory

순번변수명타입길이설명
reqDT string 14 신청일시
형식 : yyyyMMddHHmmss
requestPoint string 18 환불 신청포인트
accountBank string 10 환불계좌 은행명
accountNum string 50 환불계좌번호
accountName string 70 환불계좌 예금주명
state number 1 상태
  • 1 접수대기
  • 2 심사중
  • 3 입금대기
  • 4 환불완료
  • 5 취소
reason string 200 환불사유

RefundForm

순번변수명타입길이필수설명
ContactName string 100 Y 담당자명
tel string 20 Y 담당자 연락처
RequestPoint string 18 Y 환불 신청 포인트
AccountBank string 10 Y 은행명
AccountNum string 50 Y 계좌번호
AccountName string 70 Y 예금주명
Reason string 200 N 환불사유

PaymentForm

순번변수명타입길이필수설명
settlerName string 100 N 담당자명
settlerEmail string 100 N 담당자 이메일
notifyHP string 20 N 담당자 휴대폰
무통장 입금 승인 알림톡이 전송될 번호
paymentName string 70 Y 입금자명
settleCost string 18 Y 결제금액

PaymentResponse

순번변수명타입길이설명
code number - 응답코드
message string - 응답메시지
settleCode string 18 정산코드

ChargeInfo

순번변수명타입길이설명
unitCost string 12 발행단가
chargeMethod string 3 과금유형
연동
파트너
rateSystem string 3 과금제도
종량제

JoinForm

순번변수명타입길이필수설명
ID string 50 Y 아이디
6자 이상 50자 이하
Password string 20 Y 비밀번호
8자 이상 20자 이하
영문, 숫자, 특수문자(~!@#$%^&*()_+) 포함
LinkID string 20 Y 파트너 링크아이디
팝빌에서 발급한 링크아이디
CorpNum string 10 Y 사업자번호 ('-' 제외)
CEOName string 100 Y 대표자 성명
CorpName string 200 Y 회사명
Addr string 300 Y 사업장 주소
BizType string 100 Y 업태
BizClass string 100 Y 종목
ContactName string 100 Y 담당자 성명
ContactEmail string 100 Y 담당자 이메일
ContactTEL string 20 Y 담당자 휴대폰

CorpInfo

순번변수명타입길이필수설명
ceoname string 100 Y 대표자 성명
corpName string 200 Y 회사명
addr string 300 Y 주소
bizType string 100 Y 업태
bizClass string 100 Y 종목

ContactInfo - 입력부

순번변수명타입길이필수설명
id string 50 Y 아이디
6자 이상 50자 이하
password string 20 조건부 비밀번호
8자 이상 20자 이하
영문, 숫자, 특수문자(~!@#$%^&*()_+) 포함
함수 [RegistContact - 담당자 추가]호출을 위한 필수값
personName string 100 Y 담당자 성명
tel string 20 Y 담당자 휴대폰
email string 100 Y 담당자 이메일
searchRole number 1 N 담당자 권한
1개인권한
2읽기권한
3회사권한 : 기본값

ContactInfo - 출력부

순번변수명타입길이설명
id string 50 아이디
personName string 100 담당자 성명
tel string 20 담당자 휴대폰
email string 100 담당자 이메일
regDT string 14 등록일시
형식 : yyyyMMddHHmmss
searchRole number 1 담당자 권한
1개인권한
2읽기권한
3회사권한
mgrYN boolean - 관리자 여부
true관리자
false담당자
팝빌 사이트 [마이페이지] > [회사정보] > [담당자 관리]에서 수정 가능
state number 1 계정상태
1사용중

RefundResponse

순번변수명타입길이설명
code number - API 처리에 대한 응답코드
1성공
message string - API 처리에 대한 응답메시지
refundCode string 18 환불코드