수집 요청

1. RequestJob - 수집 요청

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

홈택스에 신고된 전자세금계산서 매입/매출 내역 수집을 팝빌에 요청합니다.
최대 3개월 단위로 수집 요청이 가능하며, 수집 기한의 제한은 없습니다.
API를 호출하고 반환 받은 작업아이디(JobID)는 수집을 요청한 시점으로부터 1시간 동안만 유효합니다.

Request

요청 헤더

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

Path 파라미터

순번	변수명	타입	길이	필수	설명
1	`QueryType`	string	-	Y	전자세금계산서 유형 (택 1) `SELL` 매출 `BUY` 매입 `TRUSTEE` 위수탁

Query 파라미터

순번	변수명	타입	길이	필수	설명
1	`DType`	string	1	Y	검색일자 유형 (택 1) `W` 작성일자 `I` 발행일자 `S` 전송일자 (권장)
2	`SDate`	string	8	Y	검색 시작일자 형식 : yyyyMMdd
3	`EDate`	string	8	Y	검색 종료일자 형식 : yyyyMMdd

요청 예시

curl --request POST \
  --url 'https://{domain}/HomeTax/Taxinvoice/{QueryType}?DType={DType}&SDate={SDate}&EDate={EDate}' \
  --header 'Authorization: Bearer {token}'

Response

응답 본문

순번	변수명	타입	길이	설명
1	`jobID`	string	18	작업아이디

응답 예시

{
    "jobID": "025102210000000001"
}

2. GetJobState - 수집 상태 확인

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

[RequestJob - 수집 요청] API를 호출하고 반환 받은 작업아이디(JobID)를 이용하여 수집 상태를 확인합니다.
수집상태(jobState) = 3(완료) 이면서, 수집 결과코드(errorCode) = 1(수집성공)인 경우 [Search - 수집 내역 확인] 이 가능합니다.

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의 반환값

요청 예시

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

Response

응답 본문

순번	변수명	타입	길이	설명
1	`jobID`	string	18	팝빌에서 할당한 작업아이디
2	`jobState`	number	1	수집상태 `1` 대기 `2` 진행 `3` 완료
3	`queryType`	string	2	전자세금계산서 유형 `매출` `매입` `수탁`
4	`queryDateType`	string	9	일자유형 `WriteDate` 작성일자 `IssueDate` 발행일자 `SendDate` 전송일자
5	`queryStDate`	string	8	시작일자 형식 : yyyyMMdd
6	`queryEnDate`	string	8	종료일자 형식 : yyyyMMdd
7	`errorCode`	number	-	수집 결과코드 성공 : 1 실패 : 음의 정수 8자리 숫자값 [참고] 오류코드
8	`errorReason`	string	-	오류메시지 수집실패시 반환되는 사유
9	`jobStartDT`	string	14	작업 시작일시 형식 : yyyyMMddHHmmss
10	`jobEndDT`	string	14	작업 종료일시 형식 : yyyyMMddHHmmss
11	`collectCount`	number	-	수집건수
12	`regDT`	string	14	수집 요청일시 형식 : yyyyMMddHHmmss

응답 예시

{
    "jobID": "025102210000000004",
    "jobState": 3,
    "queryType": "매출",
    "queryDateType": "SendDate",
    "queryStDate": "20251001",
    "queryEnDate": "20251022",
    "errorCode": 1,
    "errorReason": "수집 완료",
    "jobStartDT": "20251022104325",
    "jobEndDT": "20251022104326",
    "collectCount": 1010,
    "regDT": "20251022104324"
}

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

GET https://popbill-test.linkhub.co.kr/HomeTax/Taxinvoice/JobList

[RequestJob – 수집 요청] API를 호출하고 반환 받은 작업아이디(JobID) 목록의 수집 상태를 확인합니다.

Request

요청 헤더

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

요청 예시

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

Response

응답 본문

순번	변수명	타입	길이	설명
1	`jobID`	string	18	팝빌에서 할당한 작업아이디
2	`jobState`	number	1	수집상태 `1` 대기 `2` 진행 `3` 완료
3	`queryType`	string	2	전자세금계산서 유형 `매출` `매입` `수탁`
4	`queryDateType`	string	9	일자유형 `WriteDate` 작성일자 `IssueDate` 발행일자 `SendDate` 전송일자
5	`queryStDate`	string	8	시작일자 형식 : yyyyMMdd
6	`queryEnDate`	string	8	종료일자 형식 : yyyyMMdd
7	`errorCode`	number	-	수집 결과코드 성공 : 1 실패 : 음의 정수 8자리 숫자값 [참고] 오류코드
8	`errorReason`	string	-	오류메시지 수집실패시 반환되는 사유
9	`jobStartDT`	string	14	작업 시작일시 형식 : yyyyMMddHHmmss
10	`jobEndDT`	string	14	작업 종료일시 형식 : yyyyMMddHHmmss
11	`collectCount`	number	-	수집건수
12	`regDT`	string	14	수집 요청일시 형식 : yyyyMMddHHmmss

응답 예시

[
    {
        "jobID": "025102210000000004",
        "jobState": 3,
        "queryType": "매출",
        "queryDateType": "SendDate",
        "queryStDate": "20251001",
        "queryEnDate": "20251022",
        "errorCode": 1,
        "errorReason": "수집 완료",
        "jobStartDT": "20251022104325",
        "jobEndDT": "20251022104326",
        "collectCount": 1010,
        "regDT": "20251022104324"
    }
]