연동매뉴얼

Index

Usage htTaxinvoiceService

var popbill = require('popbill');

popbill.config({

    // 링크허브에서 발급받은 링크아이디, 비밀키
    LinkID: 'TESTID',
    SecretKey: 'SwW2qU+1TEzYBx/6TVjIPGnI0VXUMMQQZtJf2Ed8q2I=',

    // 연동환경 설정값, (true-개발용, false-상업용)
    IsTest: true

    // 인증토큰 IP제한기능 사용여부, 권장(true)
    IPRestrictOnOff: true,

    defaultErrorHandler: function (Error) {
        console.log('Error Occur : [' + Error.code + '] ' + Error.message);
    }
});

var htTaxinvoiceService = popbill.HTTaxinvoiceService();

1. 홈택스 전자세금계산서 매입/매출 내역 수집

1.1. RequestJob - 수집 요청

ㆍ홈택스에 신고된 전자세금계산서 매입/매출 내역 수집을 팝빌에 요청합니다. (조회기간 단위 : 최대 3개월)

htTaxinvoiceService.requestJob(CorpNum, Type, DType, SDate, EDate, UserID, success, error)
유의사항

ㆍ주기적으로 자체 DB에 세금계산서 정보를 INSERT 하는 경우, {@no.3 DType} 값을 "S"로 하는 것을 권장합니다.

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 Type MgtKeyType - O 세금계산서 유형 : SELL / BUY / TRUSTEE 중 택 1
└ SELL = 매출, BUY = 매입, TRUSTEE = 위수탁
3 DType string - O 조회할 일자 유형 : "W" / "I" / "S" 중 택 1
└ W = 작성일자, I = 발행일자, S = 전송일자(권장)
4 SDate string - O 조회 기간의 시작일자 (형식 : yyyyMMdd)
5 EDate string - O 조회 기간의 종료일자 (형식 : yyyyMMdd)
6 UserID string 50 - 팝빌회원 아이디
7 success Function - O 성공에 대한 콜백 함수
8 error Function - O 실패에 대한 콜백 함수

Return

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

Throws

PopbillException

1.2. GetJobState - 수집 상태 확인

ㆍ함수 [1.1. RequestJob – 수집 요청]를 통해 반환 받은 작업 아이디의 상태를 확인합니다.

ㆍ[2.1 Search – 수집 결과 조회] 또는 [2.2 Summary – 수집결과 요약정보 조회]를 사용하기 전에 수집 작업의 진행 상태, 수집 작업의 성공 여부를 확인해야 합니다.

htTaxinvoiceService.getJobState(CorpNum, JobID, UserID, success, error)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 JobID string 18 O 작업 아이디(JobID)
└ [1.1 RequestJob - 수집 요청]의 반환값
3 UserID string 50 - 팝빌회원 아이디
4 success Function - O 성공에 대한 콜백 함수
5 error Function - O 실패에 대한 콜백 함수

Return

HTTaxinvoiceJobState

Throws

PopbillException

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

ㆍ전자세금계산서 매입/매출 내역 수집요청에 대한 상태 목록을 확인합니다.

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

htTaxinvoiceService.listActiveJob(CorpNum, UserID, success, error)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID string 50 - 팝빌회원 아이디
3 success Function - O 성공에 대한 콜백 함수
4 error Function - O 실패에 대한 콜백 함수

Return

HTTaxinvoiceJobState[ ]

Throws

PopbillException

2. 홈택스 전자세금계산서 매입/매출 내역 수집 결과 조회

2.1. Search - 수집 결과 조회

ㆍ함수 [1.2. GetJobState – 수집 상태 확인]를 통해 상태 정보가 확인된 작업아이디를 활용하여 수집된 전자세금계산서 매입/매출 내역을 조회합니다.

htTaxinvoiceService.search(CorpNum, JobID, Type, TaxType, PurposeType, TaxRegIDType, TaxRegIDYN, TaxRegID, Page, PerPage, Order, UserID, SearchString, success, error)

ㆍ페이지 정보(Page, PerPage, Order) 항목을 사용하여 전자세금계산서 매입/매출 내역 조회 목록 페이징 기능을 구현할 수 있습니다.

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 JobID string 18 O 작업 아이디
└ [1.1 RequestJob - 수집 요청]의 반환값
3 Type object - O [배열] 세금계산서 문서형태 : "N" / "M" 중 선택 (다중 선택 가능)
└ N = 일반, M = 수정
※ 미입력시 전체조회
4 TaxType object - O [배열] 과세형태 : "T" / "N" / "Z" 중 선택 (다중 선택 가능)
└ T = 과세, N = 면세, Z = 영세
※ 미입력시 전체조회
5 PurposeType object - O [배열] 세금계산서 발행목적 : "R" / "C" / "N" 중 선택 (다중 선택 가능)
└ R = 영수, C = 청구, N = 없음
※ 미입력시 전체조회
6 TaxRegIDType string - O 종사업장번호의 주체 : "S" / "B" / "T" 중 택 1
└ S = 공급자, B = 공급받는자, T = 수탁자
※ 미입력시 전체조회
7 TaxRegIDYN string 1 O 종사업장번호 유무 : null / "0" / "1" 중 택 1
└ null = 전체, 0 = 없음, 1 = 있음
8 TaxRegID string - O 종사업장번호
└ 다수건 검색시 콤마(",")로 구분. 예) 1234,1000
※ 미입력시 전체조회
9 Page number - - 목록 페이지번호 (기본값 1)
10 PerPage string - - 페이지당 표시할 목록 개수 (기본값 500, 최대 1,000)
11 Order string 1 O [1.1 RequestJob - 수집 요청] 함수 사용시 사용한 DType 값을 기준으로 하는 목록 정렬 방향 : "D" / "A" 중 택 1
└ D = 내림차순(기본값), A = 오름차순
12 UserID string 50 - 팝빌회원 아이디
13 SearchString string - - 거래처 상호 / 사업자번호 (사업자) / 주민등록번호 (개인) / "9999999999999" (외국인) 중 검색하고자 하는 정보 입력
└ 사업자번호 / 주민등록번호는 하이픈('-')을 제외한 숫자만 입력
※ 미입력시 전체조회
14 success Function - O 성공에 대한 콜백 함수
15 error Function - O 실패에 대한 콜백 함수

Return

HTTaxinvoiceSearchResult

Throws

PopbillException

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

ㆍ함수 [1.2. GetJobState – 수집 상태 확인]를 통해 상태 정보가 확인된 작업아이디를 활용하여 수집된 전자세금계산서 매입/매출 내역의 요약 정보를 조회합니다.

※ 요약정보: 전자세금계산서 수집 건수, 공급가액 합계, 세액 합계, 합계 금액

htTaxinvoiceService.summary(CorpNum, JobID, Type, TaxType, PurposeType, TaxRegIDType, TaxRegIDYN, TaxRegID, UserID, SearchString, success, error)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 JobID string 18 O 수집 요청 시 팝빌에서 발급받은 작업아이디
3 Type object - O [배열] 세금계산서 문서형태 : "N" / "M" 중 선택 (다중 선택 가능)
└ N = 일반, M = 수정
※ 미입력시 전체조회
4 TaxType object - O [배열] 과세형태 : "T" / "N" / "Z" 중 선택 (다중 선택 가능)
└ T = 과세, N = 면세, Z = 영세
※ 미입력시 전체조회
5 PurposeType object - O [배열] 세금계산서 발행목적 : "R" / "C" / "N" 중 선택 (다중 선택 가능)
└ R = 영수, C = 청구, N = 없음
※ 미입력시 전체조회
6 TaxRegIDType string - O 종사업장번호의 주체 : "S" / "B" / "T" 중 택 1
└ S = 공급자, B = 공급받는자, T = 수탁자
※ 미입력시 전체조회
7 TaxRegIDYN string 1 O 종사업장번호 유무 : null / "0" / "1" 중 택 1
└ null = 전체, 0 = 없음, 1 = 있음
8 TaxRegID string - O 종사업장번호
└ 다수건 검색시 콤마(",")로 구분. 예) 1234,1000
※ 미입력시 전체조회
9 UserID string 50 - 팝빌회원 아이디
10 SearchString string - - 거래처 상호 / 사업자번호 (사업자) / 주민등록번호 (개인) / "9999999999999" (외국인) 중 검색하고자 하는 정보 입력
└ 사업자번호 / 주민등록번호는 하이픈('-')을 제외한 숫자만 입력
※ 미입력시 전체조회
11 success Function - O 성공에 대한 콜백 함수
12 error Function - O 실패에 대한 콜백 함수

Return

HTTaxinvoiceSummary

Throws

PopbillException

2.3. GetTaxinvoice - 상세정보 확인 (JSON)

ㆍ국세청 승인번호를 통해 수집한 전자세금계산서 1건의 상세정보를 반환합니다.

htTaxinvoiceService.getTaxinvoice(CorpNum, NTSConfirmNum, UserID, success, error)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 NTSConfirmNum string 24 O 전자세금계산서 국세청승인번호
3 UserID string 50 - 팝빌회원 아이디
4 success Function - O 성공에 대한 콜백 함수
5 error Function - O 실패에 대한 콜백 함수

Return

HTTaxinvoice

Throws

PopbillException

2.4. GetXML - 상세정보 확인 (XML)

ㆍ국세청 승인번호를 통해 수집한 전자세금계산서 1건의 상세정보를 XML 형태의 문자열로 반환합니다.

htTaxinvoiceService.getXML(CorpNum, NTSConfirmNum, UserID, success, error)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 NTSConfirmNum string 24 O 전자세금계산서 국세청승인번호
3 UserID string 50 - 팝빌회원 아이디
4 success Function - O 성공에 대한 콜백 함수
5 error Function - O 실패에 대한 콜백 함수

Return

HTTaxinvoiceXMLResponse

Throws

PopbillException

2.5 GetPopUpURL - 홈택스 전자세금계산서 보기 팝업 URL

ㆍ수집된 전자세금계산서 1건의 상세내역을 확인하는 페이지의 팝업 URL을 반환합니다.

ㆍ반환되는 URL은 보안 정책상 30초 동안 유효하며, 시간을 초과한 후에는 해당 URL을 통한 페이지 접근이 불가합니다.

htTaxinvoiceService.getPopUpURL(CorpNum, NTSConfirmNum, UserID, success, error)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 NTSConfirmNum string 24 O 전자세금계산서 국세청승인번호
3 UserID string 50 - 팝빌회원 아이디
4 success Function - O 성공에 대한 콜백 함수
5 error Function - O 실패에 대한 콜백 함수

Return

string - 요청에 대한 응답 URL

Throws

PopbillException

2.6 GetPrintURL - 홈택스 전자세금계산서 인쇄 팝업 URL

ㆍ수집된 전자세금계산서 1건의 상세내역을 인쇄하는 페이지의 URL을 반환합니다.

ㆍ반환되는 URL은 보안 정책상 30초 동안 유효하며, 시간을 초과한 후에는 해당 URL을 통한 페이지 접근이 불가합니다.

htTaxinvoiceService.getPrintURL(CorpNum, NTSConfirmNum, UserID, success, error)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 NTSConfirmNum string 24 O 전자세금계산서 국세청승인번호
3 UserID string 50 - 팝빌회원 아이디
4 success Function - O 성공에 대한 콜백 함수
5 error Function - O 실패에 대한 콜백 함수

Return

string - 요청에 대한 응답 URL

Throws

PopbillException

3. 홈택스연동 인증 관리

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

ㆍ홈택스연동 인증정보를 관리하는 페이지의 팝업 URL을 반환합니다.

ㆍ반환되는 URL은 보안 정책상 30초 동안 유효하며, 시간을 초과한 후에는 해당 URL을 통한 페이지 접근이 불가합니다.

htTaxinvoiceService.getCertificatePopUpURL(CorpNum, UserID, success, error)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID string 50 - 팝빌회원 아이디
3 success Function - O 성공에 대한 콜백 함수
4 error Function - O 실패에 대한 콜백 함수

Return

string - 요청에 대한 응답 URL

Throws

PopbillException

3.2. GetCertificateExpireDate - 인증서 만료일자 확인

ㆍ팝빌에 등록된 인증서 만료일자를 확인합니다.

htTaxinvoiceService.getCertificateExpireDate(CorpNum, UserID, success, error)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID string 50 - 팝빌회원 아이디
3 success Function - O 성공에 대한 콜백 함수
4 error Function - O 실패에 대한 콜백 함수

Return

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

Throws

PopbillException

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

ㆍ팝빌에 등록된 인증서로 홈택스 로그인 가능 여부를 확인합니다.

htTaxinvoiceService.checkCertValidation(CorpNum, UserID, success, error)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID string 50 - 팝빌회원 아이디
3 success Function - O 성공에 대한 콜백 함수
4 error Function - O 실패에 대한 콜백 함수

Return

Response

Throws

PopbillException

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

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

htTaxinvoiceService.registDeptUser(CorpNum, DeptUserID, DeptUserPWD, UserID, success, error)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 DeptUserID string 50 O 전자세금계산서 전용 부서사용자 계정 아이디
3 DeptUserPWD string 50 O 전자세금계산서 전용 부서사용자 계정 비밀번호
4 UserID string 50 - 팝빌회원 아이디
5 success Function - O 성공에 대한 콜백 함수
6 error Function - O 실패에 대한 콜백 함수

Return

Response

Throws

PopbillException

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

ㆍ홈택스연동 인증을 위해 팝빌에 등록된 전자세금계산서용 부서사용자 계정을 확인합니다.

htTaxinvoiceService.checkDeptUser(CorpNum, UserID, success, error)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID string 50 - 팝빌회원 아이디
3 success Function - O 성공에 대한 콜백 함수
4 error Function - O 실패에 대한 콜백 함수

Return

Response

Throws

PopbillException

3.6. CheckLoginDeptUser - 부서사용자 로그인 테스트

ㆍ팝빌에 등록된 전자세금계산서용 부서사용자 계정 정보로 홈택스 로그인 가능 여부를 확인합니다.

htTaxinvoiceService.checkLoginDeptUser(CorpNum, UserID, success, error)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID string 50 - 팝빌회원 아이디
3 success Function - O 성공에 대한 콜백 함수
4 error Function - O 실패에 대한 콜백 함수

Return

Response

Throws

PopbillException

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

ㆍ팝빌에 등록된 홈택스 전자세금계산서용 부서사용자 계정을 삭제합니다.

htTaxinvoiceService.deleteDeptUser(CorpNum, UserID, success, error)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID string 50 - 팝빌회원 아이디
3 success Function - O 성공에 대한 콜백 함수
4 error Function - O 실패에 대한 콜백 함수

Return

Response

Throws

PopbillException

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

4.1. GetFlatRatePopUpURL - 정액제 서비스 신청 팝업 URL

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

ㆍ반환되는 URL은 보안 정책상 30초 동안 유효하며, 시간을 초과한 후에는 해당 URL을 통한 페이지 접근이 불가합니다.

htTaxinvoiceService.getFlatRatePopUpURL(CorpNum, UserID, success, error)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID string 50 - 팝빌회원 아이디
3 success Function - O 성공에 대한 콜백 함수
4 error Function - O 실패에 대한 콜백 함수

Return

string - 요청에 대한 응답 URL

Throws

PopbillException

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

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

htTaxinvoiceService.getFlatRateState(CorpNum, UserID, success, error)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID string 50 - 팝빌회원 아이디
3 success Function - O 성공에 대한 콜백 함수
4 error Function - O 실패에 대한 콜백 함수

Return

FlatRateState

Throws

PopbillException

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

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

htTaxinvoiceService.getBalance(CorpNum, callback, err)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 callback Function - O 성공에 대한 콜백 함수
3 err Function - O 실패에 대한 콜백 함수

Return

string - 연동회원 잔여포인트

Throws

PopbillException

4.4. GetChargeURL - 연동회원 포인트 충전 팝업 URL

ㆍ연동회원 포인트 충전을 위한 페이지의 팝업 URL을 반환합니다.

ㆍ반환되는 URL은 보안 정책상 30초 동안 유효하며, 시간을 초과한 후에는 해당 URL을 통한 페이지 접근이 불가합니다.

htTaxinvoiceService.getChargeURL(CorpNum, UserID, callback, err)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID string 50 - 팝빌회원 아이디
3 callback Function - O 성공에 대한 콜백 함수
4 err Function - O 실패에 대한 콜백 함수

Return

string - 요청에 대한 응답 URL

Throws

PopbillException

4.3. GetPaymentURL - 연동회원 포인트 결제내역 팝업 URL

ㆍ연동회원 포인트 결제내역 확인을 위한 페이지의 팝업 URL을 반환합니다.

ㆍ반환되는 URL은 보안 정책상 30초 동안 유효하며, 시간을 초과한 후에는 해당 URL을 통한 페이지 접근이 불가합니다.

htTaxinvoiceService.getPaymentURL(CorpNum, UserID, callback, err)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID string 50 - 팝빌회원 아이디
3 callback Function - O 성공에 대한 콜백 함수
4 err Function - O 실패에 대한 콜백 함수

Return

string - 요청에 대한 응답 URL

Throws

PopbillException

4.4. GetUseHistoryURL - 연동회원 포인트 사용내역 팝업 URL

ㆍ연동회원 포인트 사용내역 확인을 위한 페이지의 팝업 URL을 반환합니다.

ㆍ반환되는 URL은 보안 정책상 30초 동안 유효하며, 시간을 초과한 후에는 해당 URL을 통한 페이지 접근이 불가합니다.

htTaxinvoiceService.getUseHistoryURL(CorpNum, UserID, callback, err)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID string 50 - 팝빌회원 아이디
3 callback Function - O 성공에 대한 콜백 함수
4 err Function - O 실패에 대한 콜백 함수

Return

string - 요청에 대한 응답 URL

Throws

PopbillException

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

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

htTaxinvoiceService.getPartnerBalance(CorpNum, callback, err)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 callback Function - O 성공에 대한 콜백 함수
3 err Function - O 실패에 대한 콜백 함수

Return

string - 파트너 잔여포인트

Throws

PopbillException

4.8. GetPartnerURL - 파트너 포인트충전 팝업 URL

ㆍ파트너 포인트 충전을 위한 페이지의 팝업 URL을 반환합니다.

ㆍ반환되는 URL은 보안 정책상 30초 동안 유효하며, 시간을 초과한 후에는 해당 URL을 통한 페이지 접근이 불가합니다.

htTaxinvoiceService.getPartnerURL(CorpNum, TOGO, callback, err)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 TOGO string - O "CHRG" 입력
3 callback Function - O 성공에 대한 콜백 함수
4 err Function - O 실패에 대한 콜백 함수

Return

string - 요청에 대한 응답 URL

Throws

PopbillException

4.9. GetChargeInfo - 과금정보 확인

ㆍ팝빌 홈택스연동(세금) API 서비스 과금정보를 확인합니다.

htTaxinvoiceService.getChargeInfo(CorpNum, UserID, success, error)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID string 50 - 팝빌회원 아이디
3 success Function - O 성공에 대한 콜백 함수
4 error Function - O 실패에 대한 콜백 함수

Return

ChargeInfo

Throws

PopbillException

5. 회원정보

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

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

htTaxinvoiceService.checkIsMember(CorpNum, callback, err)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 callback Function - O 성공에 대한 콜백 함수
3 err Function - O 실패에 대한 콜백 함수

Return

Response - code : 0 (미가입) / code : 1 (가입)

Throws

PopbillException

5.2. CheckID - 아이디 중복 확인

ㆍ사용하고자 하는 아이디의 중복여부를 확인합니다.

htTaxinvoiceService.checkID(targetID, callback, err)

연동회원 신규가입(JoinMember API) 호출 전에 아이디 중복 여부 확인을 권장합니다.

Parameters

순번 변수명 타입 길이 필수 설명
1 targetID string 50 O 중복여부를 확인할 아이디
2 callback Function - O 성공에 대한 콜백 함수
3 err Function - O 실패에 대한 콜백 함수

Return

Response - code : 0 (미사용중) / code : 1 (사용중)

Throws

PopbillException

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

ㆍ사용자를 연동회원으로 가입처리합니다.

htTaxinvoiceService.joinMember(JoinForm, callback, err)

Parameters

순번 변수명 타입 길이 필수 설명
1 JoinInfo JoinForm - O 연동회원 객체정보
2 callback Function - O 성공에 대한 콜백 함수
3 err Function - O 실패에 대한 콜백 함수

Return

Response

Throws

PopbillException

5.4. GetAccessURL - 팝빌 로그인 팝업 URL

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

ㆍ반환되는 URL은 보안 정책상 30초 동안 유효하며, 시간을 초과한 후에는 해당 URL을 통한 페이지 접근이 불가합니다.

htTaxinvoiceService.getAccessURL(CorpNum, UserID, callback, err)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID string 50 - 팝빌회원 아이디
3 callback Function - O 성공에 대한 콜백 함수
4 err Function - O 실패에 대한 콜백 함수

Return

string - 요청에 대한 응답 URL

Throws

PopbillException

5.5. GetCorpInfo - 회사정보 확인

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

htTaxinvoiceService.getCorpInfo(CorpNum, callback, err)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 callback Function - O 성공에 대한 콜백 함수
3 err Function - O 실패에 대한 콜백 함수

Return

CorpInfo

Throws

PopbillException

5.6. UpdateCorpInfo - 회사정보 수정

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

htTaxinvoiceService.updateCorpInfo(CorpNum, UserID, CorpInfo, callback, err)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID string 50 - 팝빌회원 아이디
3 CorpInfo CorpInfo - O 회사 객체정보
4 callback Function - O 성공에 대한 콜백 함수
5 err Function - O 실패에 대한 콜백 함수

Return

Response

Throws

PopbillException

5.7. RegistContact - 담당자 추가

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

htTaxinvoiceService.registContact(CorpNum, UserID, ContactInfo, callback, err)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID string 50 - 팝빌회원 아이디
3 ContactInfo ContactInfo - O 담당자 객체정보
4 callback Function - O 성공에 대한 콜백 함수
5 err Function - O 실패에 대한 콜백 함수

Return

Response

Throws

PopbillException

5.8. GetContactInfo - 담당자 정보 확인

ㆍ연동회원 사업자번호에 등록된 담당자(팝빌 로그인 계정) 정보를 확인합니다.

htTaxinvoiceService.getContactInfo(CorpNum, ContactID, UserID, callback, err)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 ContactID string 50 O 담당자 아이디
3 UserID string 50 - 팝빌회원 아이디
4 callback Function - O 성공에 대한 콜백 함수
5 err Function - O 실패에 대한 콜백 함수

Return

ContactInfo

Throws

PopbillException

5.9. ListContact - 담당자 목록 확인

ㆍ연동회원 사업자번호에 등록된 담당자(팝빌 로그인 계정) 목록을 확인합니다.

htTaxinvoiceService.listContact(CorpNum, callback, err)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 callback Function - O 성공에 대한 콜백 함수
3 err Function - O 실패에 대한 콜백 함수

Return

ContactInfo[ ]

Throws

PopbillException

5.10. UpdateContact - 담당자 정보 수정

ㆍ연동회원 사업자번호에 등록된 담당자(팝빌 로그인 계정) 정보를 수정합니다.

htTaxinvoiceService.updateContact(CorpNum, UserID, ContactInfo, callback, err)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum string 10 O 팝빌회원 사업자번호 (하이픈 '-' 제외 10 자리)
2 UserID string 50 - 팝빌회원 아이디
3 ContactInfo ContactInfo - O 담당자 객체정보
4 callback Function - O 성공에 대한 콜백 함수
5 err Function - O 실패에 대한 콜백 함수

Return

Response

Throws

PopbillException

A. 객체정보

A.1. Response

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

A.2. PopbillException

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

A.3. MgtKeyType

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

A.4. HTTaxinvoiceJobState

순번 변수명 항목명 타입 길이 비고
1 jobID 작업아이디 string 18
2 jobState 수집상태 number - "1" : (대기) / "2" : (진행) / "3" : (완료) 중 반환
3 queryType 수집유형 string - "매출" / "매입" / "수탁" 중 반환
4 queryDateType 일자유형 string - "WriteDate" : (작성일자) / "IssueDate" : (발행일자) / "SendDate" : (전송일자) 중 반환
5 queryStDate 시작일자 string 8 형식 : yyyyMMdd
6 queryEnDate 종료일자 string 8 형식 : yyyyMMdd
7 errorCode 오류코드 number - 수집 결과 코드 : 1 / -8자리 숫자 값
└ 1 = 수집성공, -8자리 숫자 값 = 수집실패
※ -8자리 숫자의 예) -99999999
8 errorReason 오류메시지 string - 수집실패시 반환되는 사유
9 jobStartDT 작업 시작일시 string 14 형식 : yyyyMMddHHmmss
10 jobEndDT 작업 종료일시 string 14 형식 : yyyyMMddHHmmss
11 collectCount 수집개수 number -
12 regDT 수집 요청일시 string 14 형식 : yyyyMMddHHmmss

A.5. HTTaxinvoice

순번 변수명 항목명 타입 길이 비고
1 writeDate 작성일자 string 8 형식 : yyyyMMdd
2 issueDT 발행일시 string 14 형식 : yyyyMMddHHmmss
3 invoiceType 전자세금계산서 종류 number 3 101 : (일반 세금계산서) / 102 : (영세율 세금계산서)
103 : (위수탁 세금계산서) / 104 : (수입 세금계산서)
105 : (위수탁 영세율 세금계산서) / 201 : (수정 일반 세금계산서)
202 : (수정 영세율 세금계산서) / 203 : (수정 위수탁 세금계산서)
204 : (수정 수입 세금계산서) / 205 : (수정 영세율 위수탁 세금계산서)
301 : (일반 계산서) / 303 : (위수탁 계산서)
304 : (수입 계산서) / 401 : (수정 일반 계산서)
403 : (수정 위수탁 계산서) / 404 : (수정 수입 계산서) 중 반환
4 taxType 과세형태 string 2 "과세" / "영세" / "면세" 중 반환
5 taxTotal 세액 합계 string 18
6 supplyCostTotal 공급가액 합계 string 18
7 totalAmount 합계금액 string 18
8 purposeType 영수/청구 string 2 "영수" / "청구" / "없음" 중 반환
9 serialNum 일련번호 string 30
10 cash 현금 string 18
11 chkBill 수표 string 18
12 credit 외상 string 18
13 note 어음 string 18
14 remark1 비고1 string 150
15 remark2 비고2 string 150
16 remark3 비고3 string 150
17 ntsconfirmNum 국세청 승인번호 string 24
18 invoicerCorpNum 사업자번호 string 10
19 invoicerMgtKey 공급자 문서번호 string 24
20 invoicerTaxRegID 공급자 종사업장 식별번호 string 4 4자리 숫자값
21 invoicerCorpName 공급자 상호 string 200
22 invoicerCEOName 공급자 대표자 성명 string 100
23 invoicerAddr 공급자 주소 string 300
24 invoicerBizType 공급자 업태 string 100
25 invoicerBizClass 공급자 종목 string 100
26 invoicerContactName 공급자 담당자 성명 string 100
27 invoicerDeptName 공급자 담당자 부서명 string 100
28 invoicerTEL 공급자 담당자 연락처 string 20
29 invoicerEmail 공급자 담당자 이메일 string 100
30 invoiceeCorpNum 공급받는자 사업자번호 string 13 {@no 31. invoiceeType} = "사업자" 인 경우, 사업자번호 10자리
{@no 31. invoiceeType} = "개인" 인 경우, 주민등록번호 13자리
{@no 31. invoiceeType} = "외국인" 인 경우, "9999999999999"
31 invoiceeType 공급받는자 구분 string - "사업자" / "개인" / "외국인" 중 반환
32 invoiceeMgtKey 공급받는자 문서번호 string 24
33 invoiceeTaxRegID 공급받는자 종사업장 식별번호 string 4 4자리 숫자값
34 invoiceeCorpName 공급받는자 상호 string 200
35 invoicerCEOName 공급받는자 대표자 성명 string 100
36 invoiceeAddr 공급받는자 주소 string 300
37 invoiceeBizType 공급받는자 업태 string 100
38 invoiceeBizClass 공급받는자 종목 string 100
39 invoiceeContactName1 공급받는자 주) 담당자 성명 string 100
40 invoiceeDeptName1 공급받는자 주) 담당자 부서명 string 100
41 invoiceeTEL1 공급받는자 주) 담당자 연락처 string 20
42 invoiceeEmail1 공급받는자 주) 담당자 이메일 string 100
43 invoiceeContactName2 공급받는자 부) 담당자 성명 string 30
44 invoiceeDeptName2 공급받는자 부) 담당자 부서명 string 40
45 invoiceeTEL2 공급받는자 부) 담당자 연락처 string 20
46 invoiceeEmail2 공급받는자 부) 담당자 이메일 string 70
47 trusteeCorpNum 수탁자 사업자번호 string 10
48 trusteeMgtKey 수탁자 문서번호 string 24
49 trusteeTaxRegID 수탁자 종사업장 식별번호 string 4 4자리 숫자값
50 trusteeCorpName 수탁자 상호 string 200
51 trusteeCEOName 수탁자 대표자 성명 string 100
52 trusteeAddr 수탁자 주소 string 300
53 trusteeBizType 수탁자 업태 string 100
54 trusteeBizClass 수탁자 종목 string 100
55 trusteeContactName 수탁자 담당자 성명 string 100
56 trusteeDeptName 수탁자 담당자 부서명 string 100
57 trusteeTEL 수탁자 담당자 연락처 string 20
58 trusteeEmail 수탁자 담당자 이메일 string 100
59 modifyCode 수정 사유코드 number 1 1 : (입력사항 착오정정) / 2 : (공급가액 변동) / 3 : (환입)
4 : (계약의 해지) / 5 : (내국신용장 사후개설) / 6 : (착오에 의한 이중발행) 중 반환
60 orgNTSConfirmNum 원본 세금계산서
국세청 승인번호		 string 24
61 detailList 상세항목 HTTaxinvoiceDetail[ ] [배열] 최대 99개

A.6. HTTaxinvoiceDetail

순번 변수명 항목명 타입 길이 비고
1 serialNum 일련번호 number 1
2 purchaseDT 거래일자 string 8 형식 : yyyyMMdd
3 itemName 품명 string 100
4 spec 규격 string 60
5 qty 수량 string 12
6 unitCost 단가 string 18 소수점 아래 2번째 자리까지 반환 가능
※ 마이너스 금액 반환 가능
7 supplyCost 공급가액 string 18 ※ 마이너스 금액 반환 가능
8 tax 세액 string 18 ※ 마이너스 금액 반환 가능
9 remark 비고 string 100

A.7. HTTaxinvoiceSearchResult

순번 변수명 항목명 타입 길이 비고
1 code 요청에 대한 응답코드 number -
2 message 요청에 대한 응답메시지 string -
3 total 총 검색결과 건수 number -
4 perPage 페이지당 검색개수 number -
5 pageNum 페이지 번호 number -
6 pageCount 페이지 개수 number -
7 object 세금계산서 요약정보 HTTaxinvoiceAbbr[ ] [배열] 최대 1,000건

A.8. HTTaxinvoiceAbbr

순번 변수명 항목명 타입 길이 비고
1 ntsconfirmNum 국세청 승인번호 string 24
2 writeDate 작성일자 string 8 형식 : yyyyMMdd
3 issueDate 발행일자 string 8 형식 : yyyyMMdd
4 sendDate 전송일자 string 8 형식 : yyyyMMdd
5 taxType 과세형태 string 2 "과세" / "영세" / "면세" 중 반환
6 purposeType 영수/청구 string 2 "영수" / "청구" / "없음" 중 반환
7 supplyCostTotal 공급가액 합계 string 18
8 taxTotal 세액 합계 string 18
9 totalAmount 합계금액 string 18
10 remark1 비고 string 150
11 invoiceType 매입/매출 string 2 "매입" / "매출" 중 반환
12 modifyYN 수정 전자세금계산서 여부 boolean - true : (수정) / false : (일반) 중 반환
13 orgNTSConfirmNum 원본 전자세금계산서 국세청 승인번호 string 24
14 purchaseDate 거래일자 string 8 형식 : yyyyMMdd
15 itemName 품명 string 100
16 spec 규격 string 60
17 qty 수량 string 12
18 unitCost 단가 string 18 소수점 아래 2번째 자리까지 반환 가능
※ 마이너스 금액 반환 가능
19 supplyCost 공급가액 string 18 ※ 마이너스 금액 반환 가능
20 tax 세액 string 18 ※ 마이너스 금액 반환 가능
21 remark 비고 string 100
22 invoicerCorpNum 공급자 사업자번호 string 10
23 invoicerTaxRegID 공급자 종사업장번호 string 4 4자리 숫자값
24 invoicerCorpName 공급자 상호 string 200
25 invoicerCEOName 공급자 대표자 성명 string 100
26 invoicerEmail 공급자 담당자 이메일 string 100
27 invoiceeCorpNum 공급받는자 사업자번호 string 13 {@no 28. invoiceeType} = "사업자" 인 경우, 사업자번호 10자리
{@no 28. invoiceeType} = "개인" 인 경우, 주민등록번호 13자리
{@no 28. invoiceeType} = "외국인" 인 경우, "9999999999999"
28 invoiceeType 공급받는자 구분 string - "사업자" / "개인" / "외국인" 중 반환
29 invoiceeTaxRegID 공급받는자 종사업장번호 string 4 4자리 숫자값
30 invoiceeCorpName 공급받는자 상호 string 200
31 invoiceeCEOName 공급받는자 대표자 성명 string 100
32 invoiceeEmail1 공급받는자 담당자 이메일 string 100
33 invoiceeEmail2 공급받는자 ASP 연계사업자 메일 string 70
34 trusteeCorpNum 수탁자 사업자번호 string 10
35 trusteeTaxRegID 수탁자 종사업장번호 string 4
36 trusteeCorpName 수탁자 상호 string 200
37 trusteeCEOName 수탁자 대표자 성명 string 100
38 trusteeEmail 수탁자 담당자 이메일 string 100

A.9. HTTaxinvoiceSummary

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

A.10. HTTaxinvoiceXMLResponse

순번 변수명 항목명 타입 길이 비고
1 ResultCode 코드 number - API 처리에 대한 응답코드
2 Message 국세청 승인번호 string 24
3 retObject 전자세금계산서 XML 문서 string -

A.11. FlatRateState

순번 변수명 항목명 타입 길이 비고
1 referenceID 사업자번호 string 10 하이픈 '-' 제외 10자리 숫자값
2 contractDT 정액제 서비스 시작일시 string 14 형식 : yyyyMMddHHmmss
3 useEndDate 정액제 서비스 종료일자 string 8 형식 : yyyyMMdd
4 baseDate 자동연장 결제일 number - 5 / 15 / 25 중 반환
5 state 정액제 서비스 상태 number - 1 : (사용) / 2 : (해지) 중 반환
6 closeRequestYN 정액제 서비스 해지신청 여부 boolean - true : (신청) / false : (미신청) 중 반환
7 useRestrictYN 정액제 서비스 사용제한 여부 boolean - true : (제한) / false : (미제한) 중 반환
8 closeOnExpired 정액제 서비스 만료시 해지 여부 boolean - true : (해지) / false : (미해지) 중 반환
9 unPaidYN 미수금 보유 여부 boolean - true : (보유) / false : (미보유) 중 반환

A.12. ChargeInfo

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

A.13. JoinForm

순번 변수명 항목명 타입 길이 필수 비고
1 ID 아이디 string 50 O 6자 이상 50자 이하
2 Password 비밀번호 string 20 O 8자 이상 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

A.14. 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.15. ContactInfo

순번 변수명 항목명 타입 길이 필수 비고
1 id 아이디 string 50 O 6자 이상 50자 이하
2 Password 비밀번호 string 20 △ 8자 이상 20자 이하
└ 영문, 숫자, 특수문자 조합
3 personName 담당자 성명 string 100 O
4 tel 담당자 연락처(전화번호) string 20 O
5 email 담당자 이메일 string 100 O
6 regDT 등록일시 string 14 X 형식 : yyyyMMddHHmmss
7 searchRole 담당자 권한 number 1 - 1 : (개인권한) / 2 : (읽기권한) / 3 : (회사권한)
8 mgrYN 관리자 여부 Boolean - X true : (관리자) / false : (담당자) 중 반환
※ 팝빌 사이트 [마이페이지] > [회사정보] > [담당자 관리]에서 수정 가능
9 state 계정상태 number 1 X 0 : (승인대기 - 관리자의 승인 후 이용가능) / 1 : (사용중) 중 반환