# 수집 요청 ## 1. RequestJob - 수집 요청 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | ----------------------------------------------------------------- | ------------------------------------------------------------ | | POST | | | - 홈택스에 신고된 현금영수증 매입/매출 내역 수집을 팝빌에 요청합니다. - 최대 3개월 단위로 수집 요청이 가능하며, 수집기한의 제한은 없습니다. - API를 호출하고 반환 받은 작업아이디(JobID)는 수집을 요청한 시점으로부터 1시간 동안만 유효합니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/htcashbill/getting-started/authorization) - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **Path 파라미터** - QueryType `type: string` `length: -` `required: Y` `description: 현금영수증 유형 (택 1)` - `SELL`: 매출 - `BUY`: 매입 **Query 파라미터** - SDate `type: string` `length: 8` `required: Y` `description: 검색 시작일자` - 형식 : yyyyMMdd - EDate `type: string` `length: 8` `required: Y` `description: 검색 종료일자` - 형식 : yyyyMMdd **요청 예시** ```bash curl --request POST \ --url 'https://{domain}/HomeTax/Cashbill/{QueryType}?SDate={SDate}&EDate={EDate}' \ --header 'Authorization: Bearer {token}' ``` ### Response **응답 본문** - jobID `type: string` `length: 18` `description: 작업아이디` **응답 예시** ```json { "jobID": "025102210000000001" } ``` ## 2. GetJobState - 수집 상태 확인 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | ------------------------------------------------------------------- | -------------------------------------------------------------- | | GET | | | - [\[RequestJob – 수집 요청\]](https://developers.popbill.com/api-reference/htcashbill/api/job#RequestJob) API를 호출하고 반환 받은 작업아이디(JobID)를 이용하여 수집 상태를 확인합니다. - 수집상태(jobState) = 3(완료) 이면서, 수집 결과코드(errorCode) = 1(수집성공)인 경우 [\[Search - 수집 내역 확인\]](https://developers.popbill.com/api-reference/htcashbill/api/search#Search) 이 가능합니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/htcashbill/getting-started/authorization) - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **Path 파라미터** - jobID `type: string` `length: 18` `required: Y` `description: 팝빌에서 할당한 작업아이디` - [\[RequestJob - 수집 요청\]](#RequestJob) API의 반환값 **요청 예시** ```bash curl --request GET \ --url 'https://{domain}/HomeTax/Cashbill/{jobID}/State' \ --header 'Authorization: Bearer {token}' ``` ### Response **응답 본문** - jobID `type: string` `length: 18` `description: 팝빌에서 할당한 작업아이디` - jobState `type: number` `length: 1` `description: 수집상태` - `1`: 대기 - `2`: 진행 - `3`: 완료 - queryType `type: string` `length: 2` `description: 현금영수증 유형` - `매출` - `매입` - queryDateType `type: string` `length: 9` `description: 수집 일자 유형` - `TradeDT`: 거래일자 - queryStDate `type: string` `length: 8` `description: 시작일자` - 형식 : yyyyMMdd - queryEnDate `type: string` `length: 8` `description: 종료일자` - 형식 : yyyyMMdd - errorCode `type: number` `length: -` `description: 수집 결과코드` - 성공 : 1 - 실패 : 음의 정수 8자리 숫자값 [\[참고\] 오류코드](https://developers.popbill.com/error-code) - errorReason `type: string` `length: -` `description: 오류메시지` - 수집실패시 반환되는 사유 - jobStartDT `type: string` `length: 14` `description: 작업 시작일시` - 형식 : yyyyMMddHHmmss - jobEndDT `type: string` `length: 14` `description: 작업 종료일시` - 형식 : yyyyMMddHHmmss - collectCount `type: number` `length: -` `description: 수집건수` - regDT `type: string` `length: 14` `description: 수집 요청일시` - 형식 : yyyyMMddHHmmss **응답 예시** ```json { "jobID": "026091114000000002", "jobState": 3, "queryType": "매출", "queryDateType": "TradeDT", "queryStDate": "20260901", "queryEnDate": "20260911", "errorCode": 1, "errorReason": "수집 완료", "jobStartDT": "20260911143728", "jobEndDT": "20260911143735", "collectCount": 768, "regDT": "20260911143727" } ``` ## 3. ListActiveJob - 수집 상태 목록 확인 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | ------------------------------------------------------------- | -------------------------------------------------------- | | GET | | | - [\[RequestJob – 수집 요청\]](https://developers.popbill.com/api-reference/htcashbill/api/job#RequestJob) API를 호출하고 반환 받은 작업아이디(JobID) 목록의 수집 상태를 확인합니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/htcashbill/getting-started/authorization) - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **요청 예시** ```bash curl --request GET \ --url 'https://{domain}/HomeTax/Cashbill/JobList' \ --header 'Authorization: Bearer {token}' ``` ### Response **응답 본문** - jobID `type: string` `length: 18` `description: 팝빌에서 할당한 작업아이디` - jobState `type: number` `length: 1` `description: 수집상태` - `1`: 대기 - `2`: 진행 - `3`: 완료 - queryType `type: string` `length: 2` `description: 현금영수증 유형` - `매출` - `매입` - queryDateType `type: string` `length: 9` `description: 수집 일자 유형` - `TradeDT`: 거래일자 - queryStDate `type: string` `length: 8` `description: 시작일자` - 형식 : yyyyMMdd - queryEnDate `type: string` `length: 8` `description: 종료일자` - 형식 : yyyyMMdd - errorCode `type: number` `length: -` `description: 수집 결과코드` - 성공 : 1 - 실패 : 음의 정수 8자리 숫자값 [\[참고\] 오류코드](https://developers.popbill.com/error-code) - errorReason `type: string` `length: -` `description: 오류메시지` - 수집실패시 반환되는 사유 - jobStartDT `type: string` `length: 14` `description: 작업 시작일시` - 형식 : yyyyMMddHHmmss - jobEndDT `type: string` `length: 14` `description: 작업 종료일시` - 형식 : yyyyMMddHHmmss - collectCount `type: number` `length: -` `description: 수집건수` - regDT `type: string` `length: 14` `description: 수집 요청일시` - 형식 : yyyyMMddHHmmss **응답 예시** ```json [ { "jobID": "026091114000000002", "jobState": 3, "queryType": "매출", "queryDateType": "TradeDT", "queryStDate": "20260901", "queryEnDate": "20260911", "errorCode": 1, "errorReason": "수집 완료", "jobStartDT": "20260911143728", "jobEndDT": "20260911143735", "collectCount": 768, "regDT": "20260911143727" } ] ```