수집 내역 확인

1. Search - 수집 내역 확인

GET https://popbill-test.linkhub.co.kr/HomeTax/Taxinvoice/{jobID}

GET https://popbill.linkhub.co.kr/HomeTax/Taxinvoice/{jobID}

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

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

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

Request

요청 헤더

변수명	필수	설명
Authorization	Y	인증 토큰 [참고] 인증 및 헤더 설정
Accept-Language	N	응답 언어 설정 ko-KR: 기본값 en-US
Accept-Encoding	N	응답 압축 방식 gzip
X-PB-UserID	N	팝빌회원 아이디

Path 파라미터

순번	변수명	타입	길이	필수	설명
	jobID	string	18	Y	팝빌에서 할당한 작업아이디 [RequestJob - 수집 요청] API의 반환값

Query 파라미터

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

요청 예시

curl --request GET \
  --url 'https://{domain}/HomeTax/Taxinvoice/{jobID}?Type={Type}&TaxType={TaxType}&PurposeType={PurposeType}&TaxRegIDYN={TaxRegIDYN}&TaxRegIDType={TaxRegIDType}&TaxRegID={TaxRegID}&Page={Page}&PerPage={PerPage}&Order={Order}&SearchString={SearchString}' \
  --header 'Authorization: Bearer {token}'

Response

응답 본문

순번

변수명

타입

길이

설명

code

number

API 처리에 대한 응답코드

1성공

total

number

총 검색결과 건수

perPage

number

페이지당 목록 건수

pageNum

number

페이지 번호

pageCount

number

페이지 개수

list

array

세금계산서 요약정보

최대 : 1,000건

변수명	타입	길이	설명
ntsconfirmNum	string	24	전자세금계산서 국세청승인번호
writeDate	string	8	작성일자 형식 : yyyyMMdd
issueDate	string	8	발행일자 형식 : yyyyMMdd
sendDate	string	8	전송일자 형식 : yyyyMMdd
taxType	string	2	과세형태 과세 영세 면세
purposeType	string	2	영수/청구 영수 청구 없음
supplyCostTotal	string	18	공급가액 합계
taxTotal	string	18	세액 합계
totalAmount	string	18	합계금액
remark1	string	450	비고 전자세금계산서 비고1/2/3 값의 합
invoiceType	string	2	전자세금계산서 유형 매입 매출
modifyYN	boolean	-	수정 전자세금계산서 여부 true수정세금계산서 false일반세금계산서
orgNTSConfirmNum	string	24	당초 국세청승인번호
purchaseDate	string	8	품목1의 거래일자 형식 : yyyyMMdd
itemName	string	100	품목1의 품명
spec	string	60	품목1의 규격
qty	string	12	품목1의 수량 소수점 아래 2번째 자리까지 반환 가능 마이너스 금액 반환 가능
unitCost	string	18	품목1의 단가 소수점 아래 2번째 자리까지 반환 가능 마이너스 금액 반환 가능
supplyCost	string	18	품목1의 공급가액 마이너스 금액 반환 가능
tax	string	18	품목1의 세액 마이너스 금액 반환 가능
remark	string	100	품목1의 비고
invoicerCorpNum	string	10	공급자 사업자번호
invoicerTaxRegID	string	4	공급자 종사업장 식별번호 종사업장 식별번호는 4자리 숫자로만 구성
invoicerCorpName	string	200	공급자 상호
invoicerCEOName	string	100	공급자 대표자 성명
invoicerEmail	string	100	공급자 담당자 메일
invoiceeCorpNum	string	13	공급받는자 등록번호 ('-' 제외) - {invoiceeType}="사업자" 경우 사업자번호 - {invoiceeType}="개인" 경우 주민등록번호 - {invoiceeType}="외국인" 경우 "9999999999999"
invoiceeType	string	3	공급받는자 유형 사업자 개인 외국인
invoiceeTaxRegID	string	4	공급받는자 종사업장 식별번호 종사업장 식별번호는 4자리 숫자로만 구성
invoiceeCorpName	string	200	공급받는자 상호
invoiceeCEOName	string	100	공급받는자 대표자 성명
invoiceeEmail1	string	100	공급받는자 담당자 메일
invoiceeEmail2	string	70	공급받는자 ASP 연계사업자 메일
trusteeCorpNum	string	100	수탁자 사업자번호
trusteeTaxRegID	string	4	수탁자 종사업장 식별번호 종사업장 식별번호는 4자리 숫자로만 구성
trusteeCorpName	string	200	수탁자 상호
trusteeCEOName	string	100	수탁자 대표자 성명
trusteeEmail	string	100	수탁자 담당자 메일

응답 예시

{
    "code": 1,
    "total": 1010,
    "perPage": 500,
    "pageNum": 1,
    "pageCount": 3,
    "list": [
        {
            "invoiceType": "매출",
            "ntsconfirmNum": "202510204100020300007559",
            "writeDate": "20251020",
            "issueDate": "20251020",
            "sendDate": "20251021",
            "taxType": "과세",
            "purposeType": "영수",
            "modifyYN": false,
            "invoicerCorpNum": "6798700433",
            "invoicerCorpName": "(주)링크허브",
            "invoicerCEOName": "이형국",
            "invoicerEmail": "tax@linkhubcorp.com",
            "invoiceeCorpNum": "6568702554",
            "invoiceeType": "사업자",
            "invoiceeCorpName": "(주)올림포스네트웍스",
            "invoiceeCEOName": "원종훈",
            "invoiceeEmail1": "olympos9983@olymposnetworks.com",
            "trusteeCorpName": "",
            "supplyCostTotal": "100000",
            "taxTotal": "10000",
            "totalAmount": "110000",
            "remark1": "입금자명 : 주식회사올림포스네",
            "purchaseDate": "20251020",
            "itemName": "팝빌 파트너 포인트 충전",
            "supplyCost": "100000",
            "tax": "10000"
        }
    ]
}

2. Summary - 수집 내역 합계

GET https://popbill-test.linkhub.co.kr/HomeTax/Taxinvoice/{jobID}/Summary

GET https://popbill.linkhub.co.kr/HomeTax/Taxinvoice/{jobID}/Summary

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

Request

요청 헤더

변수명	필수	설명
Authorization	Y	인증 토큰 [참고] 인증 및 헤더 설정
Accept-Language	N	응답 언어 설정 ko-KR: 기본값 en-US
Accept-Encoding	N	응답 압축 방식 gzip
X-PB-UserID	N	팝빌회원 아이디

Path 파라미터

순번	변수명	타입	길이	필수	설명
	jobID	string	18	Y	팝빌에서 할당한 작업아이디 [RequestJob - 수집 요청] API의 반환값

Query 파라미터

변수명	타입	길이	필수	설명
Type	string	-	N	세금계산서 문서형태 (다중 선택 가능) N세금계산서 M수정세금계산서 다중 선택시 콤마(',')로 구분. 예) N,M 기본값 : 전체조회
TaxType	string	-	N	과세형태 (다중 선택 가능) T과세 N면세 Z영세 다중 선택시 콤마(',')로 구분. 예) T,N 기본값 : 전체조회
PurposeType	string	-	N	영구/청구 (다중 선택 가능) R영수 C청구 N없음 다중 선택시 콤마(',')로 구분. 예) R,C 기본값 : 전체조회
TaxRegIDYN	string	1	N	종사업장번호 유무 0없음 1있음 기본값 : 전체조회
TaxRegIDType	string	1	N	종사업장번호의 주체 S공급자 B공급받는자 T수탁자 기본값 : 전체조회
TaxRegID	string	-	N	종사업장번호 다수건 검색시 콤마(',')로 구분. 예) 1234,1000 기본값 : 전체조회
SearchString	string	13	N	조회 검색어 ('-' 제외) - 상호명 조회시 거래처상호 입력 - 사업자 조회시 사업자번호 입력 - 개인 조회시 주민등록번호 입력 - 외국인 조회시 "9999999999999" 입력 기본값 : 전체조회

요청 예시

curl --request GET \
  --url 'https://{domain}/HomeTax/Taxinvoice/{jobID}/Summary?Type={Type}&TaxType={TaxType}&PurposeType={PurposeType}&TaxRegIDYN={TaxRegIDYN}&TaxRegIDType={TaxRegIDType}&TaxRegID={TaxRegID}&SearchString={SearchString}' \
  --header 'Authorization: Bearer {token}'

Response

응답 본문

변수명	타입	길이	설명
count	number	-	수집 건수
supplyCostTotal	number	18	공급가액 합계
taxTotal	number	18	세액 합계
amountTotal	number	18	총계 (공급가액 합계+세액 합계)

응답 예시

{
    "count": 1010,
    "supplyCostTotal": 352516478,
    "taxTotal": 35251654,
    "amountTotal": 387768132
}

3. GetTaxinvoice - 수집 상세 확인

GET https://popbill-test.linkhub.co.kr/HomeTax/Taxinvoice/{ntsConfirmNum}

GET https://popbill.linkhub.co.kr/HomeTax/Taxinvoice/{ntsConfirmNum}

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

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

Request

요청 헤더

변수명	필수	설명
Authorization	Y	인증 토큰 [참고] 인증 및 헤더 설정
Accept-Language	N	응답 언어 설정 ko-KR: 기본값 en-US
Accept-Encoding	N	응답 압축 방식 gzip
X-PB-UserID	N	팝빌회원 아이디

Path 파라미터

순번	변수명	타입	길이	필수	설명
	ntsConfirmNum	string	24	Y	전자세금계산서 국세청승인번호

요청 예시

curl --request GET \
  --url 'https://{domain}/HomeTax/Taxinvoice/{ntsConfirmNum}' \
  --header 'Authorization: Bearer {token}'

Response

응답 본문

순번

변수명

타입

길이

설명

writeDate

string

작성일자

형식 : yyyyMMdd

issueDT

string

발행일시

형식 : yyyyMMddHHmmss

invoiceType

number

전자세금계산서 종류

101세금계산서
102영세율 세금계산서
103위수탁 세금계산서
104수입 세금계산서
105위수탁영세율 세금계산서
201수정세금계산서
202영세율 수정세금계산서
203위수탁 수정세금계산서
204수입 수정세금계산서
205위수탁영세율 수정세금계산서
301계산서
303위수탁 계산서
304수입 계산서
401수정계산서
403위수탁 수정계산서
404수입 수정계산서

taxType

string

과세형태

과세

영세

면세

taxTotal

string

세액 합계

supplyCostTotal

string

공급가액 합계

totalAmount

string

합계금액

purposeType

string

영수/청구

영수

청구

없음

serialNum

string

일련번호

cash

string

현금

chkBill

string

수표

credit

string

외상

note

string

어음

remark1

string

150

비고1

remark2

string

150

비고2

remark3

string

150

비고3

ntsconfirmNum

string

국세청승인번호

invoicerCorpNum

string

공급자 사업자번호

invoicerMgtKey

string

공급자 문서번호

invoicerTaxRegID

string

공급자 종사업장 식별번호

종사업장 식별번호는 4자리 숫자로만 구성

invoicerCorpName

string

200

공급자 상호

invoicerCEOName

string

100

공급자 대표자 성명

invoicerAddr

string

300

공급자 주소

invoicerBizType

string

100

공급자 업태

invoicerBizClass

string

100

공급자 종목

invoicerContactName

string

100

공급자 담당자 성명

invoicerDeptName

string

100

공급자 담당자 부서명

invoicerTEL

string

공급자 담당자 연락처

invoicerEmail

string

100

공급자 담당자 메일

invoiceeCorpNum

string

공급받는자 등록번호 ('-' 제외)
- {invoiceeType}="사업자" 경우 사업자번호
- {invoiceeType}="개인" 경우 주민등록번호
- {invoiceeType}="외국인" 경우 "9999999999999"

invoiceeType

string

공급받는자 유형

사업자

개인

외국인

invoiceeMgtKey

string

공급받는자 문서번호

invoiceeTaxRegID

string

공급받는자 종사업장 식별번호

종사업장 식별번호는 4자리 숫자로만 구성

invoiceeCorpName

string

200

공급받는자 상호

invoiceeCEOName

string

100

공급받는자 대표자 성명

invoiceeAddr

string

300

공급받는자 주소

invoiceeBizType

string

100

공급받는자 업태

invoiceeBizClass

string

100

공급받는자 종목

invoiceeContactName1

string

100

공급받는자 주) 담당자 성명

invoiceeDeptName1

string

100

공급받는자 주) 담당자 부서명

invoiceeTEL1

string

공급받는자 주) 담당자 연락처

invoiceeEmail1

string

100

공급받는자 주) 담당자 메일

invoiceeContactName2

string

100

공급받는자 부) 담당자 성명

invoiceeDeptName2

string

100

공급받는자 부) 담당자 부서명

invoiceeTEL2

string

공급받는자 부) 담당자 연락처

invoiceeEmail2

string

100

공급받는자 부) 담당자 메일

trusteeCorpNum

string

수탁자 사업자번호

trusteeMgtKey

string

수탁자 문서번호

trusteeTaxRegID

string

수탁자 종사업장 식별번호

종사업장 식별번호는 4자리 숫자로만 구성

trusteeCorpName

string

200

수탁자 상호

trusteeCEOName

string

100

수탁자 대표자 성명

trusteeAddr

string

300

수탁자 주소

trusteeBizType

string

100

수탁자 업태

trusteeBizClass

string

100

수탁자 종목

trusteeContactName

string

100

수탁자 담당자 성명

trusteeDeptName

string

100

수탁자 담당자 부서명

trusteeTEL

string

수탁자 담당자 연락처

trusteeEmail

string

100

수탁자 담당자 메일

modifyCode

number

수정 사유코드

1기재사항 착오정정
2공급가액 변동
3환입
4계약의 해지
5내국신용장 사후개설
6착오에 의한 이중발행

orgNTSConfirmNum

string

당초 국세청승인번호

detailList

array

상세항목

최대 : 99개

변수명	타입	길이	설명
serialNum	number	2	일련번호
purchaseDT	string	8	거래일자 형식 : yyyyMMdd
itemName	string	100	품명
spec	string	60	규격
qty	string	12	수량 -99999999.99 ~ 999999999.99 소수점 아래 2번째 자리까지 입력 가능
unitCost	string	18	단가 -99999999999999.99 ~ 999999999999999.99 소수점 아래 2번째 자리까지 입력 가능
supplyCost	string	18	공급가액 정수만 입력 가능 마이너스 금액 입력 가능, 소수점 자동 절사
tax	string	18	세액 정수만 입력 가능 마이너스 금액 입력 가능, 소수점 자동 절사
remark	string	100	비고

응답 예시

{
    "writeDate": "20251020",
    "issueDT": "20251020194612",
    "invoiceType": 101,
    "taxType": "과세",
    "invoicerCorpNum": "6798700433",
    "invoicerMgtKey": "202510200000000007",
    "invoicerCorpName": "(주)링크허브",
    "invoicerCEOName": "이형국",
    "invoicerAddr": "광주 북구 하남대로 705, LS빌딩 4층",
    "invoicerBizClass": "소프트웨어개발및공급",
    "invoicerBizType": "서비스",
    "invoicerContactName": "회계팀",
    "invoicerTEL": "16008536",
    "invoicerEmail": "test@test.com",
    "invoiceeCorpNum": "1234567890",
    "invoiceeType": "사업자",
    "invoiceeCorpName": "공급받는자 상호",
    "invoiceeCEOName": "공급받는자 대표자 성명",
    "invoiceeAddr": "공급받는자 주소",
    "invoiceeBizType": "공급받는자 업태",
    "invoiceeBizClass": "공급받는자 종목",
    "invoiceeContactName1": "공급받는자 주) 담당자 성명",
    "invoiceeTEL1": "01012345678",
    "invoiceeEmail1": "test@test.com",
    "taxTotal": "10000",
    "supplyCostTotal": "100000",
    "totalAmount": "110000",
    "purposeType": "영수",
    "remark1": "비고1",
    "ntsconfirmNum": "202510204100020300007559",
    "detailList": [
        {
            "serialNum": 1,
            "purchaseDT": "20251020",
            "itemName": "팝빌 파트너 포인트 충전",
            "supplyCost": "100000",
            "tax": "10000"
        }
    ]
}

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

POST https://popbill-test.linkhub.co.kr/HomeTax/Taxinvoice/{ntsConfirmNum}

POST https://popbill.linkhub.co.kr/HomeTax/Taxinvoice/{ntsConfirmNum}

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

Request

요청 헤더

변수명	필수	설명
Authorization	Y	인증 토큰 [참고] 인증 및 헤더 설정
Accept-Language	N	응답 언어 설정 ko-KR: 기본값 en-US
Accept-Encoding	N	응답 압축 방식 gzip
X-PB-UserID	N	팝빌회원 아이디

Path 파라미터

순번	변수명	타입	길이	필수	설명
	ntsConfirmNum	string	24	Y	전자세금계산서 국세청승인번호

Query 파라미터

순번	변수명	타입	길이	필수	설명
	T	string	-	Y	고정값 : xml

요청 예시

curl --request GET \
  --url 'https://{domain}/HomeTax/Taxinvoice/{ntsConfirmNum}?T=xml' \
  --header 'Authorization: Bearer {token}'

Response

응답 본문

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

응답 예시

{
    "ResultCode": 1,
    "Message": "202510204100020300007559",
    "retObject": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>\n<TaxInvoice..."
}

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

GET https://popbill-test.linkhub.co.kr/HomeTax/Taxinvoice/{ntsConfirmNum}/PopUp

GET https://popbill.linkhub.co.kr/HomeTax/Taxinvoice/{ntsConfirmNum}/PopUp

Request

요청 헤더

변수명	필수	설명
Authorization	Y	인증 토큰 [참고] 인증 및 헤더 설정
Accept-Language	N	응답 언어 설정 ko-KR: 기본값 en-US
Accept-Encoding	N	응답 압축 방식 gzip
X-PB-UserID	N	팝빌회원 아이디

Path 파라미터

순번	변수명	타입	길이	필수	설명
	ntsConfirmNum	string	24	Y	전자세금계산서 국세청승인번호

요청 예시

curl --request GET \
  --url 'https://{domain}/HomeTax/Taxinvoice/{ntsConfirmNum}/PopUp' \
  --header 'Authorization: Bearer {token}'

Response

응답 본문

순번	변수명	타입	길이	설명
	url	string	-	전자세금계산서 팝업 URL

응답 예시

{
    "url": "https://test.popbill.com/App/API?T=2ZU3PQGQII4UD3J7HW2EURIBS...AWPV2OWRUPGACA======"
}

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

GET https://popbill-test.linkhub.co.kr/HomeTax/Taxinvoice/{ntsConfirmNum}/Print

GET https://popbill.linkhub.co.kr/HomeTax/Taxinvoice/{ntsConfirmNum}/Print

Request

요청 헤더

변수명	필수	설명
Authorization	Y	인증 토큰 [참고] 인증 및 헤더 설정
Accept-Language	N	응답 언어 설정 ko-KR: 기본값 en-US
Accept-Encoding	N	응답 압축 방식 gzip
X-PB-UserID	N	팝빌회원 아이디

Path 파라미터

순번	변수명	타입	길이	필수	설명
	ntsConfirmNum	string	24	Y	전자세금계산서 국세청승인번호

요청 예시

curl --request GET \
  --url 'https://{domain}/HomeTax/Taxinvoice/{ntsConfirmNum}/Print' \
  --header 'Authorization: Bearer {token}'

Response

응답 본문

순번	변수명	타입	길이	설명
	url	string	-	전자세금계산서 인쇄 팝업 URL

응답 예시

{
    "url": "https://test.popbill.com/App/API?T=2ZU3PQGQII4UD3J7HW2EURIBS...AWPV2OWRUPGACA======"
}