Index

1. 홈택스 현금영수증 매입/매출 내역 수집

1.1. RequestJob - 수집 요청

ㆍ 현금영수증 매입/매출 내역 수집을 요청합니다.

ㆍ 시작일자, 종료일자는 현금영수증의 거래일자 기준 수집기간 범위입니다.

String RequestJob(String CorpNum, KeyType cbType, String SDate, String EDate, String UserID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 cbType KeyType - O 현금영수증 유형 [ SELL-매출 / BUY-매입 ]
3 SDate String - O 시작일자, 날짜형식(yyyyMMdd)
4 EDate String - O 종료일자, 날짜형식(yyyyMMdd)
5 UserID String 50 - 팝빌회원 아이디

Return

String - 요청에 대한 작업아이디(JobID)

Throws

PopbillException

1.2. GetJobState - 수집 상태 확인

ㆍ 현금영수증 매입/매출 내역 수집요청에 대한 처리상태를 확인합니다.

ㆍ 반환되는 항목 중 수집상태(jobState) 확인 후 결과 조회(Search, Summary) 함수를 호출하시기 바랍니다.

HTCashbillJobState GetJobState(String CorpNum, String JobID, String UserID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 JobID String 18 O 작업 아이디
3 UserID String 50 - 팝빌회원 아이디

Return

HTCashbillJobState

Throws

PopbillException

1.3. ListActiveJob - 수집 상태 목록 확인

ㆍ 현금영수증 매입/매출 내역 수집요청에 대한 상태 목록을 확인합니다.

ㆍ 수집 요청 후 1시간이 경과한 수집 요청건은 상태정보가 반환되지 않습니다.

List<HTCashbillJobState> ListActiveJob(String CorpNum, String UserID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID String 50 - 팝빌회원 아이디

Return

List<HTCashbillJobState>

Throws

PopbillException

2. 홈택스 현금영수증 매입/매출 내역 수집 결과 조회

2.1. Search - 목록 조회

ㆍ 수집처리가 완료된 작업아이디(jobID)를 사용하여 현금영수증 수집결과를 조회합니다.

ㆍ 페이지 정보(Page, PerPage) 항목을 사용하여 현금영수증 매입/매출 목록 페이징 기능을 구현할 수 있습니다.

HTCashbillSearch Search(String CorpNum, String JobID, String[] TradeType, String[] TradeUsage, int Page, int PerPage, String Order, String UserID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 JobID String 18 O 작업 아이디
3 TradeType String[] - O [배열] 문서형태 [ N-일반 현금영수증 / C-취소 현금영수증 ]
4 TradeUsage String[] - O [배열] 거래구분 [ P-소득공제용 / C-지출증빙용 ]
5 Page int - O 페이지번호, 기본값 '1'
6 PerPage int - O 페이지당 검색개수, 기본값 500, 최대 1000
7 Order String 1 - 정렬 방향, 기본값 'D' [ D-내림차순, A-오름차순 중 택1 ]
8 UserID String 50 - 팝빌회원 아이디

Return

HTCashbillSearch

Throws

PopbillException

2.2. Summary - 수집 결과 요약정보 조회

ㆍ 수집처리가 완료된 작업아이디(jobID)를 사용하여 현금영수증 수집결과 요약정보를 조회합니다.

ㆍ 현금영수증 수집 건수, 공급가액 합계, 세액 합계, 봉사료 합계, 합계 금액을 반환합니다.

HTCashbillSummary Summary(String CorpNum, String JobID, String[] TradeType, String[] TradeUsage, String UserID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 JobID String 18 O 수집 요청 시 팝빌에서 발급받은 작업아이디
3 TradeType String[] - O [배열] 문서형태 [ N-일반 현금영수증 / C-취소 현금영수증 ]
4 TradeUsage String[] - O [배열] 거래구분 [ P-소득공제용 / C-지출증빙용 ]
5 UserID String 50 - 팝빌회원 아이디

Return

HTCashbillSummary

Throws

PopbillException

3. 홈택스연동 인증 관리

3.1. GetCertificatePopUpURL - 홈택스연동 인증 관리 팝업 URL

ㆍ 홈택스연동 인증관리 팝업 URL을 반환합니다.

ㆍ 반환되는 URL은 보안정책상 30초의 유효시간을 갖으며, 유효시간 이후 호출시 정상적으로 페이지가 호출되지 않습니다.

String GetCertificatePopUpURL(String CorpNum, String UserID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID String 50 - 팝빌회원 아이디

Return

String - 요청에 대한 응답 URL

Throws

PopbillException

3.2. GetCertificateExpireDate - 홈택스연동 공인인증서 만료일자 확인

ㆍ 홈택스연동 인증을 위해 팝빌에 등록된 공인인증서 만료일자를 반환합니다.

DateTime GetCertificateExpireDate(String CorpNum, String UserID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID String 50 - 팝빌회원 아이디

Return

DateTime - 팝빌에 등록된 공인인증서 만료일자

Throws

PopbillException

3.3. CheckCertValidation - 홈택스 공인인증서 로그인 테스트

ㆍ 팝빌에 홈택스연동 인증을 위해 등록된 공인인증서를 사용하여 홈택스 로그인을 테스트합니다.

Response CheckCertValidation(String corpNum, String userID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 userID String 50 - 팝빌회원 아이디

Return

Response

Throws

PopbillException

3.4. RegistDeptUser - 부서사용자 계정등록

ㆍ 팝빌에 홈택스연동 인증을 위해 현금영수증 부서사용자 계정을 등록합니다.

Response RegistDeptUser(String corpNum, String deptUserID, String deptUserPWD, String userID)

Parameters

순번 변수명 타입 길이 필수 설명
1 corpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 deptUserID String 50 O 현금영수증 전용 부서사용자 계정 아이디
3 deptUserPWD String 50 O 현금영수증 전용 부서사용자 계정 비밀번호
4 userID String 50 - 팝빌회원 아이디

Return

Response

Throws

PopbillException

3.5. CheckDeptUser - 부서사용자 등록정보 확인

ㆍ 팝빌에 등록된 홈택스 현금영수증 부서사용자 아이디를 확인합니다.

Response CheckDeptUser(String corpNum, String userID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 userID String 50 - 팝빌회원 아이디

Return

Response

Throws

PopbillException

3.6. CheckLoginDeptUser - 부서사용자 등록정보 확인

ㆍ 팝빌에 등록된 홈택스 현금영수증 부서사용자 계정으로 홈택스 로그인을 테스트합니다.

Response CheckLoginDeptUser(String corpNum, String userID)

Parameters

순번 변수명 타입 길이 필수 설명
1 corpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
1 CorpNum String 10 - 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 userID String 50 - 팝빌회원 아이디

Return

Response

Throws

PopbillException

3.7. DeleteDeptUser - 부서사용자 등록정보 삭제

ㆍ 팝빌에 등록된 홈택스 현금영수증 부서사용자 계정을 삭제합니다.

Response DeleteDeptUser(String corpNum, String userID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 userID String 50 - 팝빌회원 아이디

Return

Response

Throws

PopbillException

4. 포인트관리 / 정액제 신청

4.1. GetBalance - 연동회원 잔여포인트 확인

ㆍ 연동회원 잔여포인트를 확인합니다.

Double GetBalance(String CorpNum)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)

Return

Double - 연동회원 잔여포인트

Throws

PopbillException

4.2. GetChargeURL - 연동회원 포인트충전 URL

ㆍ 팝빌 연동회원 사업자의 포인트 충전 팝업 URL을 반환합니다.

ㆍ 반환되는 URL은 보안정책상 30초의 유효시간을 갖으며, 유효시간 이후 호출시 정상적으로 페이지가 호출되지 않습니다.

String GetChargeURL(String CorpNum, String UserID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID String 50 - 팝빌회원 아이디

Return

String - 요청에 대한 응답 URL

Throws

PopbillException

4.3. GetPartnerBalance - 파트너 잔여포인트 확인

ㆍ 파트너 잔여포인트를 확인합니다.

Double GetPartnerBalance(String CorpNum)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)

Return

Double - 파트너 잔여포인트

Throws

PopbillException

4.4. GetPartnerURL - 파트너 포인트충전 URL

ㆍ 파트너 포인트충전 팝업 URL 을 반환합니다.

ㆍ 반환되는 URL은 보안정책상 30초의 유효시간을 갖으며, 유효시간 이후 호출시 정상적으로 페이지가 호출되지 않습니다.

String GetPartnerURL(String CorpNum, String TOGO)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 TOGO String - O CHRG : 파트너 포인트 충전

Return

String - 요청에 대한 응답 URL

Throws

PopbillException

4.5. GetChargeInfo - 과금정보 확인

ㆍ 홈택스연동 매입/매출 조회 서비스 과금정보를 확인합니다.

ChargeInfo GetChargeInfo(String CorpNum, String UserID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID String 50 - 팝빌회원 아이디

Return

ChargeInfo

Throws

PopbillException

4.6. GetFlatRatePopUpURL - 정액제 서비스 신청 URL

ㆍ 홈택스연동 정액제 서비스 신청 팝업 URL을 반환합니다.

ㆍ 반환되는 URL은 보안정책상 30초의 유효시간을 갖으며, 유효시간 이후 호출시 정상적으로 페이지가 호출되지 않습니다.

String GetFlatRatePopUpURL(String CorpNum, String UserID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID String 50 - 팝빌회원 아이디

Return

String - 요청에 대한 응답 URL

Throws

PopbillException

4.7. GetFlatRateState - 정액제 서비스 상태 확인

ㆍ 홈택스연동 정액제 서비스 상태를 확인합니다.

HTFlatRate GetFlatRateState(String CorpNum, String UserID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID String 50 - 팝빌회원 아이디

Return

HTFlatRate

Throws

PopbillException

5. 회원정보

5.1. CheckIsMember - 연동회원 가입여부 확인

ㆍ 사업자번호를 조회하여 연동회원 가입여부를 확인합니다.

Response CheckIsMember(String CorpNum, String LinkID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 LinkID String - O 링크아이디

Return

Response

Throws

PopbillException

5.2. CheckID - 아이디 중복 확인

ㆍ 팝빌회원 아이디 중복여부를 확인합니다.

Response CheckID(String ID)

Parameters

순번 변수명 타입 길이 필수 설명
1 ID String 10 O 중복여부 확인 할 아이디

Return

Response

Throws

PopbillException

5.3. JoinMember - 연동회원 신규가입

ㆍ 사업자의 연동회원 가입처리를 요청합니다.

Response JoinMember(JoinForm joinInfo)

Parameters

순번 변수명 타입 길이 필수 설명
1 joinInfo JoinForm - O 연동 회원 정보 객체

Return

Response

Throws

PopbillException

5.4. GetAccessURL - 팝빌 로그인 URL

ㆍ 팝빌 사이트에 로그인 상태로 접근할 수 있는 팝업 URL을 반환합니다.

ㆍ 반환되는 URL은 보안정책상 30초의 유효시간을 갖으며, 유효시간 이후 호출시 정상적으로 페이지가 호출되지 않습니다.

String GetAccessURL(String CorpNum, String UserID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID String 50 - 팝빌회원 아이디

Return

String - 요청에 대한 응답 URL

Throws

PopbillException

5.5. GetCorpInfo - 회사정보 확인

ㆍ 팝빌 연동회원의 회사정보를 확인합니다.

CorpInfo GetCorpInfo(String CorpNum, String UserID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID String 50 - 팝빌회원 아이디

Return

CorpInfo

Throws

PopbillException

5.6. UpdateCorpInfo - 회사정보 수정

ㆍ 팝빌 연동회원의 회사정보를 수정합니다.

Response UpdateCorpInfo(String CorpNum, CorpInfo corpInfo, String UserID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 corpInfo CorpInfo - O 회사정보 객체
3 UserID String 50 - 팝빌회원 아이디

Return

Response

Throws

PopbillException

5.7. RegistContact - 담당자 등록

ㆍ 팝빌 연동회원 사업자의 담당자 정보(팝빌 로그인 계정)를 추가합니다.

ㆍ 하나의 사업자번호에 다수의 담당자 정보(팝빌 로그인 계정)를 추가할 수 있습니다.

Response RegistContact(String CorpNum, Contact contactInfo, String UserID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 contactInfo Contact - O 담당자 정보 객체
3 UserID String 50 - 팝빌회원 아이디

Return

Response

Throws

PopbillException

5.8. ListContact - 담당자 목록 확인

ㆍ 팝빌 연동회원 사업자의 담당자 목록을 확인합니다.

List<Contact> ListContact(String CorpNum, String UserID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID String 50 - 팝빌회원 아이디

Return

List<Contact>

Throws

PopbillException

5.9. UpdateContact - 담당자 정보 수정

ㆍ 팝빌 연동회원 사업자의 담당자 정보를 수정합니다.

Response UpdateContact(String CorpNum, Contact contactInfo, String UserID)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 contactInfo Contact - O 담당자 정보 객체
3 UserID String 50 - 팝빌회원 아이디

Return

Response

Throws

PopbillException

A. 객체정보

A.1. Response

순번 변수명 항목명 타입 길이 비고
1 code 코드 long - API 처리에 대한 응답 상태코드
2 message 메시지 String - API 처리에 대한 응답 메시지

A.2. PopbillException

순번 변수명 항목명 타입 길이 비고
1 code 코드 long - API 처리 실패에 대한 오류코드(-로 시작하는 8자리 숫자값)
2 message 메시지 String - API 처리 실패에 대한 오류메시지

A.3. KeyType (enum)

순번 변수명 항목명 타입 길이 비고
1 SELL 매출 enum -
2 BUY 매입 enum -

A.4. HTCashbillJobState

순번 변수명 항목명 타입 길이 비고
1 jobID 작업아이디 String 18
2 jobState 수집상태 int? - 1-대기 / 2-진행 / 3-완료
3 queryType 수집유형 String - 매출, 매입 중 반환
4 queryDateType 수집 일자 유형 String - TradeDate-거래일자
5 queryStDate 시작일자 String - 날짜형식(yyyyMMdd)
6 queryEnDate 종료일자 String - 날짜형식(yyyyMMdd)
7 errorCode 오류코드 long? - 1-수집성공 / 기타-수집실패
8 errorReason 오류메시지 String -
9 jobStartDT 작업 시작일시 String - 날짜형식(yyyyMMddHHmmss)
10 jobEndDT 작업 종료일시 String - 날짜형식(yyyyMMddHHmmss)
11 collectCount 수집개수 long -
12 regDT 수집 요청일시 String - 날짜형식(yyyyMMddHHmmss)

A.5. HTCashbill

순번 변수명 항목명 타입 길이 비고
1 ntsconfirmNum 국세청승인번호 String 24 현금영수증의 국세청승인번호
2 tradeDate 거래일자 String 8 날짜형식(yyyyMMdd)
3 tradeDT 거래일시 String 8 날짜형식(yyyyMMddHHmmss)
4 tradeType 문서형태 String 4 승인거래, 취소거래 중 반환
5 tradeUsage 거래구분 String 5 소득공제용, 지출증빙용 중 반환
6 totalAmount 거래금액 String 9
7 supplyCost 공급가액 String 9
8 tax 부가세 String 9
9 serviceFee 봉사료 String 9
10 invoiceType 매입/매출 String 2 매입, 매출 중 반환
11 franchiseCorpNum 발행자 사업자번호 String 10
12 franchiseCorpName 발행자 상호 String 200
13 franchiseCorpType 발행자 사업자유형 String 1 1-일반과세자
2-간이과세자
5-법인과세자
14 identityNum 식별번호 String 4 식별번호 마지막 4 자리 반환
15 identityNumType 식별번호유형 String 1 1-주민등록번호
2-사업자번호
3-휴대전화번호
4-카드번호
16 customerName 고객명 String 70
17 cardOwnerName 카드소유자명 String 70
18 deductionType 공제유형 String 1 1,2– 공제 /3,4- 불공제

A.6. HTCashbillSearch

순번 변수명 항목명 타입 길이 비고
1 code 요청에 대한 응답코드 int? -
2 message 요청에 대한 응답메시지 String -
3 total 총 검색결과 건수 int? -
4 perPage 페이지당 검색개수 int? -
5 pageNum 페이지 번호 int? -
6 pageCount 페이지 개수 int -
7 list 현금영수증 정보 List<HTCashbill> [리스트] 최대 1,000개

A.7. HTCashbillSummary

순번 변수명 항목명 타입 길이 비고
1 count 수집 결과 건수 long? -
2 supplyCostTotal 공급가액 합계 long? -
3 taxTotal 세액 합계 long? -
4 serviceFeeTotal 봉사료 합계 long? -
5 amountTotal 합계 금액 long? -

A.8. HTFlatRate

순번 변수명 항목명 타입 길이 비고
1 referenceID 사업자번호 String -
2 contractDT 정액제 서비스 시작일시 String - 날짜형식(yyyyMMddHHmmss)
3 useEndDate 정액제 서비스 종료일자 String - 날짜형식(yyyyMMdd)
4 baseDate 자동연장 결제일 int? - 5,15,25 중 반환
5 state 정액제 서비스 상태 int? - 1-사용 / 2–해지
6 closeRequestYN 정액제 서비스 해지신청 여부 bool? -
7 useRestrictYN 정액제 서비스 사용제한 여부 bool? -
8 closeOnExpired 정액제 서비스 만료시 해지 여부 bool? -
9 unPaidYN 미수금 보유 여부 bool? -

A.9. ChargeInfo

순번 변수명 항목명 타입 길이 비고
1 unitCost 월정액요금 String - 월정액요금 반환
2 chargeMethod 과금유형 String - 일반, 연동, 파트너 중 반환
3 rateSystem 과금제도 String - 정액제 반환

A.10. JoinForm

순번 변수명 항목명 타입 길이 필수 비고
1 ID 아이디 String 50 O 6자 이상 50자 미만
2 PWD 비밀번호 String 20 O 6자 이상 20자 미만
3 LinkID 파트너 링크아이디 String 20 O 파트너 신청시 메일로 발급받은 링크아이디
4 CorpNum 사업자번호 String 10 O 사업자번호 (하이픈 '-' 제외 10 자리)
5 CEOName 대표자 성명 String 100 O
6 CorpName 상호 String 200 O
7 Addr 사업장 주소 String 300 O
8 BizType 업태 String 100 O
9 BizClass 종목 String 100 O
10 ContactName 담당자 성명 String 100 O
11 ContactEmail 담당자 이메일 String 100 O
12 ContactTEL 담당자 연락처 String 20 O
13 ContactHP 담당자 휴대폰번호 String 20 -
14 ContactFAX 담당자 팩스번호 String 20 -

A.11. CorpInfo

순번 변수명 항목명 타입 길이 필수 비고
1 ceoname 대표자 성명 String 100 O
2 corpName 상호 String 200 O
3 addr 주소 String 300 O
4 bizType 업태 String 100 O
5 bizClass 종목 String 100 O

A.12. Contact

순번 변수명 항목명 타입 길이 필수 비고
1 id 아이디 String 50 O 6자 이상 50자 미만
2 pwd 비밀번호 String 20 O 6자 이상 20자 미만
3 personName 담당자 성명 String 100 O
4 tel 담당자 연락처 String 20 -
5 hp 담당자 휴대폰번호 String 20 -
6 fax 담당자 팩스번호 String 20 -
7 email 담당자 이메일 String 100 O
8 regDT 등록일시 String 14 -
9 searchAllAllowYN 담당자 조회권한 설정 bool? - O
10 mgrYN 관리자 여부 bool? - O True-관리자 / False-사용자
11 state 상태 String 1 - 0–승인대기 / 1–사용중