수집 내역 확인

1. Search - 수집 내역 확인

홈택스에서 수집된 전자세금계산서 매입/매출 내역을 확인합니다.

• 38개 항목으로 구성된 내역 확인이 가능합니다.

def search(CorpNum, JobID, Type, TaxType, PurposeType, TaxRegIDType, TaxRegIDYN, TaxRegID, Page, PerPage, Order, UserID=None, SearchString=None)

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

요청

Parameters

순번	변수명	타입	길이	필수	설명
1	CorpNum	str	10	Y	팝빌회원 사업자번호 ('-' 제외)
2	JobID	str	18	Y	팝빌에서 할당한 작업아이디 → [RequestJob - 수집 요청] API의 반환값
3	Type	list	-	N	세금계산서 문서형태 (다중 선택 가능) N 세금계산서 M 수정세금계산서 ※ 기본값 : 전체조회
4	TaxType	list	-	N	과세형태 (다중 선택 가능) T 과세 N 면세 Z 영세 ※ 기본값 : 전체조회
5	PurposeType	list	-	N	영수/청구 (다중 선택 가능) R 영수 C 청구 N 없음 ※ 기본값 : 전체조회
6	TaxRegIDType	str	1	N	종사업장번호의 주체 S 공급자 B 공급받는자 T 수탁자 ※ 기본값 : 전체조회
7	TaxRegIDYN	str	1	N	종사업장번호 유무 0 없음 1 있음 ※ 기본값 : 전체조회
8	TaxRegID	str	-	N	종사업장번호 → 다수건 검색시 콤마(',')로 구분. 예) 1234,1000 ※ 기본값 : 전체조회
9	Page	int	-	N	목록 페이지번호 ※ 기본값 : 1
10	PerPage	int	-	N	페이지당 표시할 목록 건수 → 최대 : 1,000건 ※ 기본값 : 500건
11	Order	str	1	N	목록 정렬 방향 D 내림차순 : 기본값 A 오름차순 → [RequestJob - 수집 요청] API의 매개변수 {DType} 기준
12	UserID	str	50	N	팝빌회원 아이디
13	SearchString	str	13	N	조회 검색어 ('-' 제외) → 상호명 조회시 거래처상호 입력 사업자 조회시 사업자번호 입력 개인 조회시 주민등록번호 입력 외국인 조회시 "9999999999999" 입력 ※ 기본값 : 전체조회

응답

HTTaxinvoiceSearchResult

순번	변수명	타입	길이	설명
1	code	int	-	API 처리에 대한 응답코드
2	message	str	-	API 처리에 대한 응답메시지
3	total	int	-	총 검색결과 건수
4	perPage	int	-	페이지당 목록 건수
5	pageNum	int	-	페이지 번호
6	pageCount	int	-	페이지 개수
7	list	HTTaxinvoiceAbbr[]	1,000	세금계산서 요약정보 → 최대 : 1,000건
HTTaxinvoiceAbbr[] 순번 변수명 타입 길이 설명 1 ntsconfirmNum str 24 전자세금계산서 국세청승인번호 2 writeDate str 8 작성일자 → 형식 : yyyyMMdd 3 issueDate str 8 발행일자 → 형식 : yyyyMMdd 4 sendDate str 8 전송일자 → 형식 : yyyyMMdd 5 taxType str 2 과세형태 과세 영세 면세 6 purposeType str 2 영수/청구 영수 청구 없음 7 supplyCostTotal str 18 공급가액 합계 8 taxTotal str 18 세액 합계 9 totalAmount str 18 합계금액 10 remark1 str 450 비고 → 전자세금계산서 비고1/2/3 값의 합 11 invoiceType str 2 전자세금계산서 유형 매입 매출 12 modifyYN bool - 수정 전자세금계산서 여부 True 수정세금계산서 False 일반세금계산서 13 orgNTSConfirmNum str 24 당초 국세청승인번호 14 purchaseDate str 8 품목1의 거래일자 → 형식 : yyyyMMdd 15 itemName str 100 품목1의 품명 16 spec str 60 품목1의 규격 17 qty str 12 품목1의 수량 → 소수점 아래 2번째 자리까지 반환 가능 마이너스 금액 반환 가능 18 unitCost str 18 품목1의 단가 → 소수점 아래 2번째 자리까지 반환 가능 마이너스 금액 반환 가능 19 supplyCost str 18 품목1의 공급가액 → 마이너스 금액 반환 가능 20 tax str 18 품목1의 세액 → 마이너스 금액 반환 가능 21 remark str 100 품목1의 비고 22 invoicerCorpNum str 10 공급자 사업자번호 23 invoicerTaxRegID str 4 공급자 종사업장 식별번호 24 invoicerCorpName str 200 공급자 상호 25 invoicerCEOName str 100 공급자 대표자 성명 26 invoicerEmail str 100 공급자 담당자 메일 27 invoiceeCorpNum str 13 공급받는자 등록번호 → {invoiceeType}="사업자" 경우 사업자번호 {invoiceeType}="개인" 경우 주민등록번호 {invoiceeType}="외국인" 경우 "9999999999999" 28 invoiceeType str 3 공급받는자 유형 사업자 개인 외국인 29 invoiceeTaxRegID str 4 공급받는자 종사업장 식별번호 30 invoiceeCorpName str 200 공급받는자 상호 31 invoiceeCEOName str 100 공급받는자 대표자 성명 32 invoiceeEmail1 str 100 공급받는자 담당자 메일 33 invoiceeEmail2 str 70 공급받는자 부) 담당자 메일 34 trusteeCorpNum str 10 수탁자 사업자번호 35 trusteeTaxRegID str 4 수탁자 종사업장 식별번호 36 trusteeCorpName str 200 수탁자 상호 37 trusteeCEOName str 100 수탁자 대표자 성명 38 trusteeEmail str 100 수탁자 담당자 메일

예외

PopbillException

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

2. Summary - 수집 내역 합계

홈택스에서 수집된 전자세금계산서 매입/매출 내역의 합계정보를 제공합니다.
※ 합계정보 - 수집 건수, 공급가액 합계, 세액 합계, 총계 (공급가액 합계+세액 합계)

def summary(CorpNum, JobID, Type, TaxType, PurposeType, TaxRegIDType, TaxRegIDYN, TaxRegID, UserID=None, SearchString=None)

요청

Parameters

순번	변수명	타입	길이	필수	설명
1	CorpNum	str	10	Y	팝빌회원 사업자번호 ('-' 제외)
2	JobID	str	18	Y	팝빌에서 할당한 작업아이디 → [RequestJob - 수집 요청] API의 반환값
3	Type	list	-	N	세금계산서 문서형태 (다중 선택 가능) N 세금계산서 M 수정세금계산서 ※ 기본값 : 전체조회
4	TaxType	list	-	N	과세형태 (다중 선택 가능) T 과세 N 면세 Z 영세 ※ 기본값 : 전체조회
5	PurposeType	list	-	N	영수/청구 (다중 선택 가능) R 영수 C 청구 N 없음 ※ 기본값 : 전체조회
6	TaxRegIDType	str	1	N	종사업장번호의 주체 S 공급자 B 공급받는자 T 수탁자 ※ 기본값 : 전체조회
7	TaxRegIDYN	str	1	N	종사업장번호 유무 0 없음 1 있음 ※ 기본값 : 전체조회
8	TaxRegID	str	-	N	종사업장번호 → 다수건 검색시 콤마(',')로 구분. 예) 1234,1000 ※ 기본값 : 전체조회
9	UserID	str	50	N	팝빌회원 아이디
10	SearchString	str	13	N	조회 검색어 ('-' 제외) → 상호명 조회시 거래처상호 입력 사업자 조회시 사업자번호 입력 개인 조회시 주민등록번호 입력 외국인 조회시 "9999999999999" 입력 ※ 기본값 : 전체조회

응답

HTTaxinvoiceSummary

순번	변수명	타입	길이	설명
1	count	int	-	수집 건수
2	supplyCostTotal	int	18	공급가액 합계
3	taxTotal	int	18	세액 합계
4	amountTotal	int	18	총계 (공급가액 합계+세액 합계)

예외

PopbillException

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

3. GetTaxinvoice - 수집 상세 확인

홈택스에서 수집된 전자세금계산서 1건의 상세정보를 제공합니다.

• 60개 항목과 99개 품목으로 구성된 정보 확인이 가능합니다.

def getTaxinvoice(CorpNum, NTSConfirmNum, UserID=None)

요청

Parameters

순번	변수명	타입	길이	필수	설명
1	CorpNum	str	10	Y	팝빌회원 사업자번호 ('-' 제외)
2	NTSConfirmNum	str	24	Y	전자세금계산서 국세청승인번호
3	UserID	str	50	N	팝빌회원 아이디

응답

HTTaxinvoice

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

예외

PopbillException

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

4. GetXML - 수집 상세 확인 (XML)

홈택스에서 수집된 전자세금계산서 1건의 상세정보를 XML 데이터 포맷으로 제공합니다.

def getXML(CorpNum, NTSConfirmNum, UserID=None)

요청

Parameters

순번	변수명	타입	길이	필수	설명
1	CorpNum	str	10	Y	팝빌회원 사업자번호 ('-' 제외)
2	NTSConfirmNum	str	24	Y	전자세금계산서 국세청승인번호
3	UserID	str	50	N	팝빌회원 아이디

응답

HTTaxinvoiceXMLResponse

순번	변수명	타입	길이	설명
1	ResultCode	int	-	API 처리에 대한 응답코드 1 성공
2	Message	str	-	API 처리에 대한 응답메시지
3	retObject	str	-	전자세금계산서 XML 문서

예외

PopbillException

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

5. GetPopUpURL - 전자세금계산서 팝업 URL

미리보기

홈택스에서 수집된 전자세금계산서 1건의 팝업 URL을 반환합니다.

• 권장 사이즈 : width = 1,000px (최소 725px) / height = 730px
• 반환되는 URL은 30초 동안만 사용이 가능합니다.
• 반환되는 URL에서만 유효한 세션을 포함하고 있습니다.

def getPopUpURL(CorpNum, NTSConfirmNum, UserID=None)

요청

Parameters

순번	변수명	타입	길이	필수	설명
1	CorpNum	str	10	Y	팝빌회원 사업자번호 ('-' 제외)
2	NTSConfirmNum	str	24	Y	전자세금계산서 국세청승인번호
3	UserID	str	50	N	팝빌회원 아이디

응답

str - 요청에 대한 응답 URL

예외

PopbillException

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

6. GetPrintURL - 전자세금계산서 인쇄 팝업 URL

미리보기

홈택스에서 수집된 전자세금계산서 1건의 인쇄 팝업 URL을 반환합니다.

• 권장 사이즈 : width = 930px / height = 765px
• 반환되는 URL은 30초 동안만 사용이 가능합니다.
• 반환되는 URL에서만 유효한 세션을 포함하고 있습니다.

def getPrintURL(CorpNum, NTSConfirmNum, UserID=None)

요청

Parameters

순번	변수명	타입	길이	필수	설명
1	CorpNum	str	10	Y	팝빌회원 사업자번호 ('-' 제외)
2	NTSConfirmNum	str	24	Y	전자세금계산서 국세청승인번호
3	UserID	str	50	N	팝빌회원 아이디

응답

str - 요청에 대한 응답 URL

예외

PopbillException

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