# 수집 요청 ## 1. RequestJob - 수집 요청 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | ------------------------------------------------------------------- | -------------------------------------------------------------- | | POST | | | - 홈택스에 신고된 전자세금계산서 매입/매출 내역 수집을 팝빌에 요청합니다. - 최대 3개월 단위로 수집 요청이 가능하며, 수집 기한의 제한은 없습니다. - API를 호출하고 반환 받은 작업아이디(JobID)는 수집을 요청한 시점으로부터 1시간 동안만 유효합니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/httaxinvoice/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`: 매입 - `TRUSTEE`: 위수탁 **Query 파라미터** - DType `type: string` `length: 1` `required: Y` `description: 검색일자 유형 (택 1)` - `W`: 작성일자 - `I`: 발행일자 - `S`: 전송일자 (권장) - 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/Taxinvoice/{QueryType}?DType={DType}&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/httaxinvoice/api/job#RequestJob) API를 호출하고 반환 받은 작업아이디(JobID)를 이용하여 수집 상태를 확인합니다. - 수집상태(jobState) = 3(완료) 이면서, 수집 결과코드(errorCode) = 1(수집성공)인 경우 [\[Search - 수집 내역 확인\]](https://developers.popbill.com/api-reference/httaxinvoice/api/search#Search) 이 가능합니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/httaxinvoice/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/Taxinvoice/{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: 일자유형` - `WriteDate`: 작성일자 - `IssueDate`: 발행일자 - `SendDate`: 전송일자 - 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 "_blank") - 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": "025102210000000004", "jobState": 3, "queryType": "매출", "queryDateType": "SendDate", "queryStDate": "20251001", "queryEnDate": "20251022", "errorCode": 1, "errorReason": "수집 완료", "jobStartDT": "20251022104325", "jobEndDT": "20251022104326", "collectCount": 1010, "regDT": "20251022104324" } ``` ## 3. ListActiveJob - 수집 상태 목록 확인 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | --------------------------------------------------------------- | ---------------------------------------------------------- | | GET | | | - [\[RequestJob – 수집 요청\]](https://developers.popbill.com/api-reference/httaxinvoice/api/job#RequestJob) API를 호출하고 반환 받은 작업아이디(JobID) 목록의 수집 상태를 확인합니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/httaxinvoice/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/Taxinvoice/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: 일자유형` - `WriteDate`: 작성일자 - `IssueDate`: 발행일자 - `SendDate`: 전송일자 - 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 "_blank") - 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": "025102210000000004", "jobState": 3, "queryType": "매출", "queryDateType": "SendDate", "queryStDate": "20251001", "queryEnDate": "20251022", "errorCode": 1, "errorReason": "수집 완료", "jobStartDT": "20251022104325", "jobEndDT": "20251022104326", "collectCount": 1010, "regDT": "20251022104324" } ] ```