1. Request for crawling

1.1. RequestJob - Request for data crawling

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

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

This API request data crawling for issued sales/purchase cash receipts from the NTS. (Maximum search scope : 3 months)

Request

Request Headers

Field	Mandatory	Description
Authorization	Y	Auth Token [Reference] Authentication
Accept-Language	N	Response language ko-KR: default en-US
Accept-Encoding	N	Response compression method gzip
X-PB-UserID	N	User’s POPBiLL ID

Path Parameters

No.	Field	Type	Length	Mandatory	Description
	QueryType	string	-	Y	Type of the cash receipt SELLsales BUYpurchase

Query Parameters

No.	Field	Type	Length	Mandatory	Description
	SDate	string	8	Y	Start date of search scope format : yyyyMMdd
	SDate	string	8	Y	End date of search scope format : yyyyMMdd

Request Example

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

Response

Response Body

No.	Field	Type	Length	Description
	jobID	string	18	JobID

Response Example

{
    "jobID": "025102210000000001"
}

1.2. GetJobState - Check the data crawling status

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

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

This API checks the status of a JobID that is returned via [RequestJob – Request for data crawling] API.
When calling [Search – Check the result of the data crawling] or [Summary – Check the summarized information of the data crawling result] APIs, you must check the crawling status.

Request

Request Headers

Field	Mandatory	Description
Authorization	Y	Auth Token [Reference] Authentication
Accept-Language	N	Response language ko-KR: default en-US
Accept-Encoding	N	Response compression method gzip
X-PB-UserID	N	User’s POPBiLL ID

Path Parameters

No.	Field	Type	Length	Mandatory	Description
	jobID	string	18	Y	Request ID(JobID) returned value of [RequestJob – Request for data crawling] API

Request Example

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

Response

Response Body

Field	Type	Length	Description
jobID	string	18	Request ID(JobID)
jobState	string	1	Crawling job status 1pending 2processing 3completed
queryType	string	2	Type of the cash receipt 매출sales 매입purchase
queryDateType	string	9	Types of dates from crawled data TradeDatedate of trade
queryStDate	string	8	Start date of search scope format : yyyyMMdd
queryEnDate	string	8	End date of search scope format : yyyyMMdd
errorCode	number	-	Crawling result code - succeeded : 1 - failed: 8 digits starting with (‘-’) [Error Code]
errorReason	string	-	Error message reason for crawling failure
jobStartDT	string	14	Start date and time of the crawling job format : yyyyMMddHHmmss
jobEndDT	string	14	End date and time of the crawling job format : yyyyMMddHHmmss
collectCount	number	-	Number of crawled data
regDT	string	14	Date and time of crawling request format : yyyyMMddHHmmss

Response Example

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

1.3. ListActiveJob - Check the list of active data crawling jobs

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

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

This API checks the list of active data crawling jobs.
JobID of each request is only valid for 1 hour.

Request

Request Headers

Field	Mandatory	Description
Authorization	Y	Auth Token [Reference] Authentication
Accept-Language	N	Response language ko-KR: default en-US
Accept-Encoding	N	Response compression method gzip
X-PB-UserID	N	User’s POPBiLL ID

Request Example

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

Response

Response Body

Field	Type	Length	Description
jobID	string	18	Request ID(JobID)
jobState	string	1	Crawling job status 1pending 2processing 3completed
queryType	string	2	Type of the cash receipt 매출sales 매입purchase
queryDateType	string	9	Types of dates from crawled data TradeDatedate of trade
queryStDate	string	8	Start date of search scope format : yyyyMMdd
queryEnDate	string	8	End date of search scope format : yyyyMMdd
errorCode	number	-	Crawling result code - succeeded : 1 - failed: 8 digits starting with (‘-’) [Error Code]
errorReason	string	-	Error message reason for crawling failure
jobStartDT	string	14	Start date and time of the crawling job format : yyyyMMddHHmmss
jobEndDT	string	14	End date and time of the crawling job format : yyyyMMddHHmmss
collectCount	number	-	Number of crawled data
regDT	string	14	Date and time of crawling request format : yyyyMMddHHmmss

Response Example

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