수집 내역 확인

1. Search - 수집 내역 확인

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

홈택스에서 수집된 전자세금계산서 매입/매출 내역을 확인합니다.
38개 항목으로 구성된 내역 확인이 가능합니다.

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

Request

요청 헤더

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

Path 파라미터

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

Query 파라미터

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

페이지 개수

array

세금계산서 요약정보

최대 : 1,000건

list

순번	변수명	타입	길이	설명
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	450	비고 전자세금계산서 비고1/2/3 값의 합
11	`invoiceType`	string	2	전자세금계산서 유형 `매입` `매출`
12	`modifyYN`	boolean	-	수정 전자세금계산서 여부 `true` 수정세금계산서 `false` 일반세금계산서
13	`orgNTSConfirmNum`	string	24	당초 국세청승인번호
14	`purchaseDate`	string	8	품목1의 거래일자 형식 : yyyyMMdd
15	`itemName`	string	100	품목1의 품명
16	`spec`	string	60	품목1의 규격
17	`qty`	string	12	품목1의 수량 소수점 아래 2번째 자리까지 반환 가능 마이너스 금액 반환 가능
18	`unitCost`	string	18	품목1의 단가 소수점 아래 2번째 자리까지 반환 가능 마이너스 금액 반환 가능
19	`supplyCost`	string	18	품목1의 공급가액 마이너스 금액 반환 가능
20	`tax`	string	18	품목1의 세액 마이너스 금액 반환 가능
21	`remark`	string	100	품목1의 비고
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	공급받는자 등록번호 ('-' 제외) {invoiceeType}="사업자" 경우 사업자번호 {invoiceeType}="개인" 경우 주민등록번호 {invoiceeType}="외국인" 경우 "9999999999999"
28	`invoiceeType`	string	3	공급받는자 유형 `사업자` `개인` `외국인`
29	`invoiceeTaxRegID`	string	4	공급받는자 종사업장 식별번호 종사업장 식별번호는 4자리 숫자로만 구성
30	`invoiceeCorpName`	string	200	공급받는자 상호
31	`invoiceeCEOName`	string	100	공급받는자 대표자 성명
32	`invoiceeEmail1`	string	100	공급받는자 담당자 메일
33	`invoiceeEmail2`	string	70	공급받는자 부) 담당자 메일
34	`trusteeCorpNum`	string	10	수탁자 사업자번호
35	`trusteeTaxRegID`	string	4	수탁자 종사업장 식별번호 종사업장 식별번호는 4자리 숫자로만 구성
36	`trusteeCorpName`	string	200	수탁자 상호
37	`trusteeCEOName`	string	100	수탁자 대표자 성명
38	`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

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

Request

요청 헤더

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

Path 파라미터

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

Query 파라미터

순번	변수명	타입	길이	필수	설명
1	`Type`	string	-	N	세금계산서 문서형태 (다중 선택 가능) `N` 세금계산서 `M` 수정세금계산서 다중 선택시 콤마(',')로 구분. 예) N,M 기본값 : 전체조회
2	`TaxType`	string	-	N	과세형태 (다중 선택 가능) `T` 과세 `N` 면세 `Z` 영세 다중 선택시 콤마(',')로 구분. 예) T,N 기본값 : 전체조회
3	`PurposeType`	string	-	N	영수/청구 (다중 선택 가능) `R` 영수 `C` 청구 `N` 없음 다중 선택시 콤마(',')로 구분. 예) R,C 기본값 : 전체조회
4	`TaxRegIDYN`	string	1	N	종사업장번호 유무 `0` 없음 `1` 있음 기본값 : 전체조회
5	`TaxRegIDType`	string	1	N	종사업장번호의 주체 `S` 공급자 `B` 공급받는자 `T` 수탁자 기본값 : 전체조회
6	`TaxRegID`	string	-	N	종사업장번호 다수건 검색시 콤마(',')로 구분. 예) 1234,1000 기본값 : 전체조회
7	`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

응답 본문

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

응답 예시

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

3. GetTaxinvoice - 수집 상세 확인

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

홈택스에서 수집된 전자세금계산서 1건의 상세정보를 제공합니다.
60개 항목과 99개 품목으로 구성된 정보 확인이 가능합니다.

Request

요청 헤더

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

Path 파라미터

순번	변수명	타입	길이	필수	설명
1	`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

당초 국세청승인번호

array

상세항목

최대 : 99개

detailList

순번	변수명	타입	길이	설명
1	`serialNum`	number	2	일련번호
2	`purchaseDT`	string	8	거래일자 형식 : yyyyMMdd
3	`itemName`	string	100	품명
4	`spec`	string	60	규격
5	`qty`	string	12	수량 -99999999.99 ~ 999999999.99 소수점 아래 2번째 자리까지 입력 가능
6	`unitCost`	string	18	단가 -99999999999999.99 ~ 999999999999999.99 소수점 아래 2번째 자리까지 입력 가능
7	`supplyCost`	string	18	공급가액 정수만 입력 가능 마이너스 금액 입력 가능, 소수점 자동 절사
8	`tax`	string	18	세액 정수만 입력 가능 마이너스 금액 입력 가능, 소수점 자동 절사
9	`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)

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

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

Request

요청 헤더

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

Path 파라미터

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

Query 파라미터

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

요청 예시

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

Response

응답 본문

순번	변수명	타입	길이	설명
1	`ResultCode`	number	-	API 처리에 대한 응답코드 `1` 성공
2	`Message`	string	-	API 처리에 대한 응답메시지
3	`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

전자세금계산서 팝업 URL 미리보기

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

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

Request

요청 헤더

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

Path 파라미터

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

요청 예시

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

Response

응답 본문

순번	변수명	타입	길이	설명
1	`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

전자세금계산서 인쇄 팝업 URL 미리보기

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

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

Request

요청 헤더

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

Path 파라미터

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

요청 예시

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

Response

응답 본문

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

응답 예시

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