수집 요청

1. RequestJob - 수집 요청

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

POST https://popbill.linkhub.co.kr/HomeTax/Cashbill/{QueryType}

홈택스에 신고된 현금영수증 매입/매출 내역 수집을 팝빌에 요청합니다.

최대 3개월 단위로 수집 요청이 가능하며, 수집기한의 제한은 없습니다.
API를 호출하고 반환 받은 작업아이디(JobID)는 수집을 요청한 시점으로부터 1시간 동안만 유효합니다.

Request

요청 헤더

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

Path 파라미터

순번	변수명	타입	길이	필수	설명
	QueryType	string	-	Y	현금영수증 유형 (택 1) SELL매출 BUY매입

Query 파라미터

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

요청 예시

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

Response

응답 본문

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

응답 예시

{
    "jobID": "025102210000000001"
}

2. GetJobState - 수집 상태 확인

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

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

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

수집상태(jobState) = 3(완료) 이면서, 수집 결과코드(errorCode) = 1(수집성공)인 경우 [Search - 수집 내역 확인] 이 가능합니다.

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

요청 예시

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

Response

응답 본문

변수명	타입	길이	설명
jobID	string	18	팝빌에서 할당한 작업아이디
jobState	string	1	수집상태 1대기 2진행 3완료
queryType	string	2	현금영수증 유형 매출 매입
queryDateType	string	9	수집 일자 유형 TradeDate거래일자
queryStDate	string	8	시작일자 형식 : yyyyMMdd
queryEnDate	string	8	시작일자 형식 : yyyyMMdd
errorCode	number	-	수집 결과코드 - 성공 : 1 - 실패 : 음의 정수 8자리 숫자값 [참고] 오류코드
errorReason	string	-	오류메시지 수집실패시 반환되는 사유
jobStartDT	string	14	작업 시작일시 형식 : yyyyMMddHHmmss
jobEndDT	string	14	작업 종료일시 형식 : yyyyMMddHHmmss
collectCount	number	-	수집건수
regDT	string	14	수집 요청일시 형식 : yyyyMMddHHmmss

응답 예시

{
    "jobID": "025102213000000001",
    "jobState": 3,
    "queryType": "매출",
    "queryDateType": "TradeDT",
    "queryStDate": "20251001",
    "queryEnDate": "20251022",
    "errorCode": -11100001,
    "errorReason": "홈택스 로그인에 실패하였습니다.",
    "jobStartDT": "20251022134003",
    "jobEndDT": "20251022134003",
    "regDT": "20251022134000"
}

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

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

GET https://popbill.linkhub.co.kr/HomeTax/Cashbill/JobList

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

Request

요청 헤더

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

요청 예시

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

Response

응답 본문

변수명	타입	길이	설명
jobID	string	18	팝빌에서 할당한 작업아이디
jobState	string	1	수집상태 1대기 2진행 3완료
queryType	string	2	현금영수증 유형 매출 매입
queryDateType	string	9	수집 일자 유형 TradeDate거래일자
queryStDate	string	8	시작일자 형식 : yyyyMMdd
queryEnDate	string	8	시작일자 형식 : yyyyMMdd
errorCode	number	-	수집 결과코드 - 성공 : 1 - 실패 : 음의 정수 8자리 숫자값 [참고] 오류코드
errorReason	string	-	오류메시지 수집실패시 반환되는 사유
jobStartDT	string	14	작업 시작일시 형식 : yyyyMMddHHmmss
jobEndDT	string	14	작업 종료일시 형식 : yyyyMMddHHmmss
collectCount	number	-	수집건수
regDT	string	14	수집 요청일시 형식 : yyyyMMddHHmmss

응답 예시

[
    {
        "jobID": "025102213000000001",
        "jobState": 3,
        "queryType": "매출",
        "queryDateType": "TradeDT",
        "queryStDate": "20251001",
        "queryEnDate": "20251022",
        "errorCode": -11100001,
        "errorReason": "홈택스 로그인에 실패하였습니다.",
        "jobStartDT": "20251022134003",
        "jobEndDT": "20251022134003",
        "regDT": "20251022134000"
    }
]