수집 요청

1. RequestJob - 수집 요청

POST https://popbill-test.linkhub.co.kr/HomeTax/Cashbill/{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` 매입

Query 파라미터

순번	변수명	타입	길이	필수	설명
1	`SDate`	string	8	Y	검색 시작일자 형식 : yyyyMMdd
2	`EDate`	string	8	Y	검색 종료일자 형식 : yyyyMMdd

요청 예시

curl --request POST \
  --url 'https://{domain}/HomeTax/Cashbill/{QueryType}?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/Cashbill/{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/Cashbill/{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	수집 일자 유형 `TradeDT` 거래일자
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": "026091114000000002",
    "jobState": 3,
    "queryType": "매출",
    "queryDateType": "TradeDT",
    "queryStDate": "20260901",
    "queryEnDate": "20260911",
    "errorCode": 1,
    "errorReason": "수집 완료",
    "jobStartDT": "20260911143728",
    "jobEndDT": "20260911143735",
    "collectCount": 768,
    "regDT": "20260911143727"
}

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

GET https://popbill-test.linkhub.co.kr/HomeTax/Cashbill/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/Cashbill/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	수집 일자 유형 `TradeDT` 거래일자
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": "026091114000000002",
        "jobState": 3,
        "queryType": "매출",
        "queryDateType": "TradeDT",
        "queryStDate": "20260901",
        "queryEnDate": "20260911",
        "errorCode": 1,
        "errorReason": "수집 완료",
        "jobStartDT": "20260911143728",
        "jobEndDT": "20260911143735",
        "collectCount": 768,
        "regDT": "20260911143727"
    }
]