작업 상태·결과 - 작업
제출한 작업의 진행 상태를 확인하고 결과 본문을 가져오며, 받은 파일을 지웁니다.
1. 작업 상태 조회GET / v1/ jobs/ {job_ id}
GEThttps:// api. xdata. kr/ v1/ jobs/ {job_ id}X-Env-Scope: real_test
데모입니다. 상태 조회와 결과 조회는 사용 토큰을 쓰지 않고, 데모 기간이 끝났는지도 보지 않습니다.
작업 제출로 받은 작업 아이디의 진행 상태를 확인합니다.
- status 가 SUCCEEDED 가 되면 결과 조회를 호출합니다. [작업 결과 조회]
- status 가 FAILED 또는 TIMEOUT 이면 error 에 원인 코드(code)와 재시도 여부(retryable)가 담깁니다.TIMEOUT 은 작업 전체 시간이 초과됐을 때(JOB_TIMEOUT)만 오고, 기관 응답 시간 초과(PROVIDER_TIMEOUT_CONNECT, PROVIDER_TIMEOUT_READ, PROVIDER_TIMEOUT_OVERALL)는 FAILED 로 끝납니다.
- 진행 중에는 retry_after_seconds 만큼 기다렸다 다시 조회하고, progress_message 를 화면에 보여 주세요. 종료되면 두 값이 null 이 됩니다.
- error.retryable 이 false 이면 같은 작업을 다시 제출하지 마세요. 발행·신청처럼 되돌릴 수 없는 작업은 요청이 이미 기관에 닿았을 수 있습니다. [재시도]
- 다른 조직·환경의 작업이거나 없는 작업이면 404 JOB_NOT_FOUND 입니다. 존재 여부를 알려 주지 않으려고 같은 응답으로 답합니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| job_ | string | 30 | Y | 작업 제출 응답으로 받은 작업 아이디입니다. |
curl --request GET \
--url 'https://api.xdata.kr/v1/jobs/{job_id}' \
--header 'Authorization: Basic {base64(client_id:client_secret)}' \
--header 'X-Env-Scope: real_test'Response
| 순번 | 변수명 | 타입 | 길이 | 설명 |
|---|---|---|---|---|
| job_ | string | 30 | 작업 아이디입니다. | |
| status | string | - | 작업 상태입니다.
| |
| env_ | string | - | 요청에 사용한 환경입니다. | |
| provider | string | - | 요청한 기관입니다. | |
| action | string | - | 요청한 작업입니다. | |
| submitted_ | string | - | 제출 일시입니다. | |
| started_ | string | - | 실행 시작 일시입니다. 시작 전에는 null 입니다. | |
| finished_ | string | - | 종료 일시입니다. 종료 전에는 null 입니다. | |
| retry_ | number | - | 재시도 횟수입니다. | |
| progress | number | - | 진행률(0~100)입니다. 10~25 는 대기 중(아직 시작 전), 30~90 은 처리 중, 100 은 종료입니다. 값이 뒤로 가지 않습니다. | |
| progress_ | string | - | 지금 단계를 알려 주는 문구입니다. 화면에 그대로 보여 주면 됩니다. 종료되면 null 입니다. | |
| retry_ | number | - | 다음 상태 조회까지 권장 대기 시간(초)입니다. 종료되면 null 이며, 더 조회하지 않아도 됩니다. | |
| error | object | - | 실패나 시간 초과일 때만 채워집니다. code, message, retryable, provider_error_ref 와 기관 쪽 HTTP 상태(upstream_status, 없으면 null), 다음 할 일(next)을 담습니다. next 는 두 경우에만 채워지고 그 밖에는 null 입니다. 블로그 로그인 연결이 끊겨 실패했고 다시 연결할 수 있으면 stage 가 link_credential 이고 사용자 문장(say_to_user)과 연결 창 주소(action_url)를 담습니다. 은행 거래내역에서 계좌 ID(bank_account_credential_id)를 보내지 않았는데 연동한 계좌가 여러 개라 실패했으면 stage 가 choose_bank_account 이고, 고를 계좌 목록(choices: bank_account_credential_id, 가린 계좌번호 masked_account_no, 기본 계좌 여부 is_default)을 담습니다. 그중 하나의 bank_account_credential_id 를 넣어 같은 요청을 다시 보냅니다. 요청 오류 응답과 달리 trace_id 는 없습니다. |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "RUNNING",
"env_scope": "real_test",
"provider": "hometax",
"action": "hometax.etax.invoice.search_list",
"submitted_at": "2026-05-27T12:34:56+09:00",
"started_at": "2026-05-27T12:34:57+09:00",
"finished_at": null,
"retry_count": 0,
"progress": 45,
"progress_message": "인증 처리 중...",
"retry_after_seconds": 2,
"error": null
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 작업 아이디가 job_ 로 시작하는 26자 형식이 아님 — HTTP 400 | |
| JOB_ | 없는 작업 아이디, 또는 다른 조직·환경의 작업 — HTTP 404 |
2. 작업 결과 조회GET / v1/ jobs/ {job_ id}/ result
GEThttps:// api. xdata. kr/ v1/ jobs/ {job_ id}/ resultX-Env-Scope: real_test
데모입니다. 상태 조회와 결과 조회는 사용 토큰을 쓰지 않고, 데모 기간이 끝났는지도 보지 않습니다.
성공한 작업의 결과 본문을 가져옵니다.
- status 가 SUCCEEDED 일 때만 결과 본문이 반환됩니다.
- 그 밖의 상태에서는 409 JOB_INVALID_TRANSITION 또는 404 JOB_NOT_FOUND 입니다.
- PDF · 엑셀 같은 파일을 만드는 작업은 result.artifacts 에 파일마다 download_url 이 내려옵니다. 이 주소는 15분 동안만 유효합니다.
- 받은 파일을 보관 기간(7일)보다 먼저 지우려면 결과 파일 삭제를 호출합니다. [결과 파일 삭제]
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| job_ | string | 30 | Y | 작업 제출 응답으로 받은 작업 아이디입니다. |
curl --request GET \
--url 'https://api.xdata.kr/v1/jobs/{job_id}/result' \
--header 'Authorization: Basic {base64(client_id:client_secret)}' \
--header 'X-Env-Scope: real_test'Response
| 순번 | 변수명 | 타입 | 길이 | 설명 |
|---|---|---|---|---|
| job_ | string | 30 | 작업 아이디입니다. | |
| status | string | - | 작업 상태입니다.
| |
| result. | string | - | 결과 스키마 이름입니다. | |
| result. | object | - | 결과 본문(요약)입니다. 파일만 내는 예전 작업이면 null 입니다. | |
| result. | array | - | PDF · 엑셀 같은 문서 파일 목록입니다. 파일을 내지 않는 작업이면 빈 배열입니다. | |
| result. | string | 30 | 파일 아이디입니다. 결과 파일 삭제로 지울 수 있는 파일에만 있고, 그 밖에는 null 입니다. | |
| result. | string | - | 받을 파일 이름입니다. 업무명_날짜(KST) 형식입니다. | |
| result. | string | - | 파일 형식입니다(예: application/pdf). | |
| result. | number | - | 파일 크기(바이트)입니다. | |
| result. | string | 64 | 받은 파일과 대조할 해시입니다. | |
| result. | string | - | 이 시각이 지나면 파일을 받을 수 없습니다. 파일은 7일 동안 보관됩니다. | |
| result. | boolean | - | 보관 기간이 지났는지입니다. true 이면 download_url 이 null 입니다. | |
| result. | string | - | 파일을 내려받는 서명된 주소입니다. 15분 동안만 유효하며, 만료되면 결과를 다시 조회해 새 주소를 받습니다. | |
| finished_ | string | - | 종료 일시입니다. |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "SUCCEEDED",
"result": {
"schema": "hometax.etax.invoice.search_list.v1",
"data": {
"...": "..."
},
"artifacts": []
},
"finished_at": "2026-05-27T12:35:42+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| JOB_ | SUCCEEDED 가 아닌 상태에서 결과를 조회 — HTTP 409 | |
| VALIDATION_ | 작업 아이디가 job_ 로 시작하는 26자 형식이 아님 — HTTP 400 | |
| JOB_ | 없는 작업 아이디 — HTTP 404 |
3. 결과 파일 삭제DELETE / v1/ jobs/ {job_ id}/ artifacts
DELETEhttps:// api. xdata. kr/ v1/ jobs/ {job_ id}/ artifactsX-Env-Scope: real_test
데모입니다. 결과 파일 삭제는 사용 토큰을 쓰지 않고, 데모 기간이 끝났는지도 보지 않습니다.
성공한 작업의 결과 파일을 보관 기간(7일)을 기다리지 않고 지금 지웁니다.
- 결과를 조회할 수 있는 키면 호출할 수 있습니다. 사용량을 차감하지 않습니다.
- 다시 호출해도 안전합니다. 이미 지운 뒤에는 deleted_count 가 0 입니다.
- 삭제 뒤 결과를 조회하면 지운 파일은 result.artifacts 에서 빠집니다. result.data 는 그대로입니다. [작업 결과 조회]
- artifact_id 가 null 인 파일은 이 호출로 지워지지 않고 보관 기간이 끝나면 지워집니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| job_ | string | 30 | Y | 작업 제출 응답으로 받은 작업 아이디입니다. |
curl --request DELETE \
--url 'https://api.xdata.kr/v1/jobs/{job_id}/artifacts' \
--header 'Authorization: Basic {base64(client_id:client_secret)}' \
--header 'X-Env-Scope: real_test'Response
| 순번 | 변수명 | 타입 | 길이 | 설명 |
|---|---|---|---|---|
| job_ | string | 30 | 작업 아이디입니다. | |
| deleted_ | number | - | 이번 요청이 지운 파일 수입니다. 이미 지웠으면 0 입니다. |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"deleted_count": 1
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| JOB_ | SUCCEEDED 로 끝나지 않은 작업 — HTTP 409 | |
| VALIDATION_ | 작업 아이디가 job_ 로 시작하는 26자 형식이 아님 — HTTP 400 | |
| JOB_ | 없는 작업 아이디, 또는 다른 조직·환경의 작업 — HTTP 404 |