정보확인

1. GetInfo - 상태 확인

현금영수증 1건의 상태 및 요약정보를 확인합니다.

• 응답 객체 CashbillInfo 의 변수 ‘stateCode’를 통해 현금영수증의 상태코드를 확인합니다.

function cashbillinfo getinfo(string corpnum, string mgtkey) throws popbillexception

요청

Parameters

순번	변수명	타입	길이	필수	설명
1	corpnum	string	10	Y	팝빌회원 사업자번호 ('-' 제외)
2	mgtkey	string	24	Y	파트너가 할당한 문서번호

응답

CashbillInfo

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

예외

PopbillException

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

2. GetInfos - 다수건 상태 확인

다수건의 현금영수증 상태 및 요약 정보를 확인합니다. (1회 호출에 최대 1,000건 확인 가능)

• 리턴값 CashbillInfo 의 변수 ‘stateCode’를 통해 현금영수증의 상태코드를 확인합니다.

subroutine getinfos(string corpnum, ref string mgtkeylist[], ref cashbillinfo ref_returnlist[]) throws popbillexception

문서번호를 통해 현금영수증 목록을 구현하는 경우 활용합니다.

요청

Parameters

순번	변수명	타입	길이	필수	설명
1	corpnum	string	10	Y	팝빌회원 사업자번호 ('-' 제외)
2	mgtkeylist	string[ ]	1,000	Y	문서번호 목록 → 최대 : 1,000건
3	ref_returnlist	ref CashbillInfo[ ]	-	Y	서브루틴 반환 결과값
ref CashbillInfo[ ] 순번 변수명 타입 길이 필수 설명 1 itemKey string 18 N 팝빌에서 현금영수증 관리 목적으로 할당한 식별번호 2 mgtKey string 24 N 문서번호 → 파트너가 할당하는 식별번호 3 tradeDate string 8 N 거래일자 → 형식 : yyyyMMdd 4 tradeDT string 14 N 거래일시 → 형식 : yyyyMMddHHmmss 5 tradeType string 4 N 문서형태 승인거래 취소거래 6 tradeUsage string 5 N 거래구분 소득공제용 지출증빙용 7 tradeOpt string 4 N 거래유형 일반 도서공연 대중교통 8 taxationType string 3 N 과세형태 과세 비과세 9 totalAmount string 9 N 거래금액 (공급가액+부가세+봉사료) 10 issueDT string 14 N 발행일시 → 형식 : yyyyMMddHHmmss 11 regDT string 14 N 등록일시 → 형식 : yyyyMMddHHmmss 12 stateMemo string 200 N 상태메모 13 stateCode integer 3 N 상태코드 → [참고] 팝빌 상태코드 14 stateDT string 14 N 상태 변경일시 → 형식 : yyyyMMddHHmmss 15 identityNum string 19 N 식별번호 → {tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 반환 {tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 반환 16 itemName string 70 N 주문상품명 17 customerName string 70 N 구매자(고객) 성명 18 confirmNum string 9 N 국세청승인번호 → 현금영수증 발행 시점에 팝빌에서 자동으로 할당 19 orgConfirmNum string 9 N 당초 국세청승인번호 → {tradeType}="취소거래" 경우 반환 20 orgTradeDate string 8 N 당초 거래일자 → {tradeType}="취소거래" 경우 반환 21 ntssendDT string 14 N 국세청 전송일시 → 형식 : yyyyMMddHHmmss 22 ntsresultDT string 14 N 국세청 처리결과 수신일시 → 형식 : yyyyMMddHHmmss 23 ntsresultCode string 4 N 국세청 결과코드 → [참고] 국세청 결과코드 24 ntsresultMessage string 30 N 국세청 결과메시지 25 printYN boolean - N 인쇄여부 true 인쇄 false 미인쇄

응답

cashbillinfo - 요청 파라미터의 ref_returnlist 확인

예외

PopbillException

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

3. GetDetailInfo - 상세정보 확인

현금영수증 1건의 상세정보를 확인합니다.

function cashbill getdetailinfo(string corpnum, string mgtkey) throws popbillexception

요청

Parameters

순번	변수명	타입	길이	필수	설명
1	corpnum	string	10	Y	팝빌회원 사업자번호 ('-' 제외)
2	mgtkey	string	24	Y	파트너가 할당한 문서번호

응답

Cashbill

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

예외

PopbillException

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

4. CheckMgtKeyInUse - 문서번호 사용 여부 확인

파트너가 현금영수증 관리 목적으로 할당하는 문서번호 사용여부를 확인합니다.

• 이미 사용 중인 문서번호는 중복 사용이 불가하고, 현금영수증이 삭제된 경우에만 문서번호의 재사용이 가능합니다.

function boolean checkmgtkeyinuse(string corpnum, string mgtkey) throws popbillexception

요청

Parameters

순번	변수명	타입	길이	필수	설명
1	corpnum	string	10	Y	팝빌회원 사업자번호 ('-' 제외)
2	mgtkey	string	24	Y	확인할 문서번호

응답

boolean - true : (사용중) / false : (미사용중)

예외

PopbillException

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

5. Search - 목록 조회

검색조건에 해당하는 현금영수증을 조회합니다. (최대 조회기간 : 6개월)

function cbsearchresult search (string corpnum, string dtype, string sdate, string edate, string state[], string tradetype[], string tradeusage[], string taxationtype[], string qstring, string order, int page, int perpage, string tradeopt[], string franchisetaxregid) throws popbillexception

매개변수 Page, PerPage, Order를 이용하여 페이징 기능을 구현할 수 있습니다.

요청

Parameters

순번	변수명	타입	길이	필수	설명
1	corpnum	string	10	Y	팝빌회원 사업자번호 ('-' 제외)
2	dtype	string	1	Y	검색일자 유형 (택 1) R 등록일자 T 거래일자 I 발행일시
3	sdate	string	8	Y	검색 시작일자 → 형식 : yyyyMMdd
4	edate	string	8	Y	검색 종료일자 → 형식 : yyyyMMdd
5	state	string[ ]	-	N	현금영수증 상태코드 → 2, 3번째 자리에 와일드카드(*) 사용가능. 예) "3**" [참고] 팝빌 상태코드 ※ 기본값 : 전체조회
6	tradetype	string[ ]	-	N	현금영수증 문서형태 (다중 선택 가능) N 승인 현금영수증 C 취소 현금영수증 ※ 기본값 : 전체조회
7	tradeusage	string[ ]	-	N	거래구분 (다중 선택 가능) P 소득공제용 C 지출증빙용 ※ 기본값 : 전체조회
8	taxationtype	string[ ]	-	Y	과세형태 (다중 선택 가능) T 과세 N 비과세
9	qstring	string	-	N	조회 검색어(식별번호) ※ 기본값 : 전체조회
10	order	string	1	Y	조회 기준일자 유형을 기준으로 하는 목록 정렬 방향 D 내림차순 : 기본값 A 오름차순
11	page	int	-	N	목록 페이지번호 ※ 기본값 : 1
12	perpage	int	-	N	페이지당 표시할 목록 건수 → 최대 : 1,000건 ※ 기본값 : 500건
13	tradeopt	string[ ]	-	N	거래유형 (다중 선택 가능) N 일반 B 도서공연 T 대중교통 ※ 기본값 : 전체조회
14	franchisetaxregid	string	-	N	가맹점 종사업장번호 → 다수건 검색시 콤마(',')로 구분. 예) 1234,1000 ※ 기본값 : 전체조회

응답

CBSearchResult

순번	변수명	타입	길이	설명
1	code	string	-	API 처리에 대한 응답코드 1 성공
2	message	string	-	API 처리에 대한 응답메시지
3	total	string	-	총 검색결과 건수
4	perPage	string	-	페이지당 목록 건수
5	pageNum	string	-	페이지 번호
6	pageCount	string	-	페이지 개수
7	list	CashbillInfo[ ]	-	현금영수증 상태/요약정보 → 함수 [GetInfo - 상태 확인]의 리턴값 구성과 동일 최대 1,000건
CashbillInfo[ ] 순번 변수명 타입 길이 설명 1 itemKey string 18 팝빌에서 현금영수증 관리 목적으로 할당한 식별번호 2 mgtKey string 24 문서번호 → 파트너가 할당하는 식별번호 3 tradeDate string 8 거래일자 → 형식 : yyyyMMdd 4 tradeDT string 14 거래일시 → 형식 : yyyyMMddHHmmss 5 tradeType string 4 문서형태 승인거래 취소거래 6 tradeUsage string 5 거래구분 소득공제용 지출증빙용 7 tradeOpt string 4 거래유형 일반 도서공연 대중교통 8 taxationType string 3 과세형태 과세 비과세 9 totalAmount string 9 거래금액 (공급가액+부가세+봉사료) 10 issueDT string 14 발행일시 → 형식 : yyyyMMddHHmmss 11 regDT string 14 등록일시 → 형식 : yyyyMMddHHmmss 12 stateMemo string 200 상태메모 13 stateCode integer 3 상태코드 → [참고] 팝빌 상태코드 14 stateDT string 14 상태 변경일시 → 형식 : yyyyMMddHHmmss 15 identityNum string 19 식별번호 → {tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 반환 {tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 반환 16 itemName string 70 주문상품명 17 customerName string 70 구매자(고객) 성명 18 confirmNum string 9 국세청승인번호 → 현금영수증 발행 시점에 팝빌에서 자동으로 할당 19 orgConfirmNum string 9 당초 국세청승인번호 → {tradeType}="취소거래" 경우 반환 20 orgTradeDate string 8 당초 거래일자 → {tradeType}="취소거래" 경우 반환 21 ntssendDT string 14 국세청 전송일시 → 형식 : yyyyMMddHHmmss 22 ntsresultDT string 14 국세청 처리결과 수신일시 → 형식 : yyyyMMddHHmmss 23 ntsresultCode string 4 국세청 결과코드 → [참고] 국세청 결과코드 24 ntsresultMessage string 30 국세청 결과메시지 25 printYN boolean - 인쇄여부 true 인쇄 false 미인쇄

예외

PopbillException

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

6. GetURL - 문서함 팝업 URL

미리보기

현금영수증 문서함의 팝업 URL을 반환합니다.

• 권장 사이즈 : width = 1,280px (최소 1,000px) / height = 800px
• 반환되는 URL은 30초 동안만 사용이 가능합니다.
• 반환되는 URL은 팝빌회원의 로그인 세션을 포함하고 있으니 사용에 유의하여 주시기 바랍니다.

function string geturl(string corpnum, string userid, string togo) throws popbillexception

요청

Parameters

순번	변수명	타입	길이	필수	설명
1	corpnum	string	10	Y	팝빌회원 사업자번호 ('-' 제외)
2	userid	string	50	N	팝빌회원 아이디
3	togo	string	-	Y	접근 메뉴 (택 1) TBOX 임시 문서함 PBOX 발행 문서함 WRITE 현금영수증 작성

응답

string - 요청에 대한 응답 URL

예외

PopbillException

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