작업 상태·결과

제출한 작업의 진행 상태를 확인하고 결과 본문을 가져옵니다.

1. 작업 상태 조회GET /v1/jobs/{job_id}

GEThttps://api.xdata.kr/v1/jobs/{job_id}X-Env-Scope: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

작업 제출로 받은 작업 아이디의 진행 상태를 확인합니다.

status 가 SUCCEEDED 가 되면 결과 조회를 호출합니다. [작업 결과 조회]
status 가 FAILED 또는 TIMEOUT 이면 error 에 원인 코드(code)와 재시도 여부(retryable)가 담깁니다.
진행 중에는 retry_after_seconds 만큼 기다렸다 다시 조회하고, progress_message 를 화면에 보여 주세요. 종료되면 두 값이 null 이 됩니다.
error.retryable 이 false 이면 같은 작업을 다시 제출하지 마세요. 발행·신청처럼 되돌릴 수 없는 작업은 요청이 이미 기관에 닿았을 수 있습니다. [재시도]
다른 조직·환경의 작업이거나 없는 작업이면 404 JOB_NOT_FOUND 입니다. 존재 여부를 알려 주지 않으려고 같은 응답으로 답합니다.

Request

순번 변수명 필수 설명

Authorization

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-Scope

호출 환경입니다.

sandbox샌드박스 — 모의 응답
real_test데모 — 하루 100 사용 토큰
production정식 — 유료 플랜 전용

[참고] 환경

X-Trace-Id N 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

순번	변수명	타입	길이	필수	설명
	job_id	string	30	Y	작업 제출 응답으로 받은 작업 아이디입니다. 형식 : job_ + 26자 ULID

추가 파라미터가 없습니다. params 는 {} 로 보냅니다.

bash

curl --request GET \
  --url 'https://api.xdata.kr/v1/jobs/{job_id}' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox'

Response

변수명	타입	길이	설명
job_id	string	30	작업 아이디입니다.
status	string	-	작업 상태입니다. `QUEUED`대기 `RUNNING`진행 `SUCCEEDED`성공 `FAILED`실패 `CANCELED`취소 `TIMEOUT`시간 초과
env_scope	string	-	요청에 사용한 환경입니다.
provider	string	-	요청한 기관입니다.
action	string	-	요청한 작업입니다.
submitted_at	string	-	제출 일시입니다. 형식 : ISO 8601 (KST, +09:00)
started_at	string	-	실행 시작 일시입니다. 시작 전에는 null 입니다.
finished_at	string	-	종료 일시입니다. 종료 전에는 null 입니다.
retry_count	number	-	재시도 횟수입니다.
progress	number	-	진행률(0~100)입니다. 10~25 는 대기 중(아직 시작 전), 30~90 은 처리 중, 100 은 종료입니다. 값이 뒤로 가지 않습니다.
progress_message	string	-	지금 단계를 알려 주는 문구입니다. 화면에 그대로 보여 주면 됩니다. 종료되면 null 입니다.
retry_after_seconds	number	-	다음 상태 조회까지 권장 대기 시간(초)입니다. 종료되면 null 이며, 더 조회하지 않아도 됩니다.
error	object	-	실패·시간 초과일 때만 채워집니다. code · message · retryable · provider_error_ref 와 기관 쪽 HTTP 상태(upstream_status, 없으면 null)를 담습니다. 요청 오류 응답과 달리 trace_id 는 없습니다. [참고] 오류 응답

json

{
    "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
}

순번	오류 코드	발생 조건
	JOB_NOT_FOUND	없는 작업 아이디, 또는 다른 조직·환경의 작업 — HTTP 404

2. 작업 결과 조회GET /v1/jobs/{job_id}/result

GEThttps://api.xdata.kr/v1/jobs/{job_id}/resultX-Env-Scope: sandbox