작업(Job) 처리 흐름

모든 기관 호출은 작업으로 제출되어 비동기로 처리됩니다. 상태 확인부터 결과 수신까지의 흐름입니다.

POST /v1/jobs 는 곧바로 job_id 를 돌려주고, 기관 호출은 서버가 이어서 처리합니다. 그래서 제출한 쪽은 상태를 확인하다가 끝나면 결과를 가져오는 순서로 씁니다.

STEP 01
제출
POST /v1/jobs 로 보내고 job_id 를 받습니다.
STEP 02
상태 확인
GET /v1/jobs/{job_id} 로 지금 상태를 봅니다.
STEP 03
다시 확인
retry_after_seconds 만큼 기다렸다 반복합니다.
STEP 04
결과 받기
SUCCEEDED 가 되면 /result 를 호출합니다.

작업 상태

QUEUED대기
접수되어 처리 순서를 기다립니다.
RUNNING실행
기관에 접속해 요청을 처리하고 있습니다.

SUCCEEDED성공
결과를 가져올 수 있습니다.
FAILED실패
error 에 원인 코드가 담깁니다.
TIMEOUT시간 초과
정해진 시간 안에 끝나지 않았습니다.
CANCELED취소
대기·실행 중에 취소되어 끝났습니다.

상태 응답에서 볼 값

필드	뜻
status	위 여섯 가지 중 하나입니다.
progress	진행률(%)입니다. 대기 10~25, 실행 30~90, 끝나면 100 입니다.
progress_message	지금 어느 단계인지 알려 주는 문구입니다(예: 인증 처리 중...). 끝나면 null 입니다.
retry_after_seconds	다음 확인까지 권하는 대기 시간(초)입니다. 끝나면 null 입니다.
error	실패·시간 초과일 때만 채워집니다. code·message·retryable 이 들어 있습니다. 되돌릴 수 없는 작업(발행·신고·신청)이면 retryable 은 코드와 상관없이 false 로 옵니다 — 오류 코드.

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'

필드별 계약(길이·형식·오류)은 작업 상태 조회 레퍼런스에 있습니다.

결과가 나올 때까지 기다리기

상태가 QUEUED 나 RUNNING 인 동안에는 retry_after_seconds 만큼 기다렸다 다시 확인하고, SUCCEEDED 가 되면 결과를 가져옵니다. 그대로 실행할 수 있는 코드는 전체 예제에 있습니다.

재시도와 중복 방지

Idempotency-Key 는 "같은 요청"을 가리키는 키입니다. 네트워크 오류로 응답을 받지 못했다면 같은 키와 같은 본문으로 다시 보냅니다 — 이미 접수된 작업이면 새로 실행하지 않고 그 작업을 그대로 돌려줍니다(HTTP 200).

작업이 실패로 끝난 뒤에는 판단이 갈립니다. 오류의 retryable 이 false 면 같은 요청을 그대로 다시 제출하지 않습니다. 입력값이 잘못된 경우(VALIDATION_*)에는 값을 고친 뒤 새 키로 다시 냅니다. true 여서 다시 실행하려면 새 키를 씁니다 — 같은 키로 보내면 그때 실패한 작업이 그대로 돌아옵니다.

자세한 규칙은 재시도(멱등성)에 있습니다.

발행·신고·신청처럼 되돌릴 수 없는 작업이 PROVIDER_OUTCOME_UNCONFIRMED 로 끝났다면 다시 제출하지 마세요. 기관에서 이미 처리됐을 수 있어 두 번 처리될 위험이 있습니다. 오류 메시지에 확인할 기관 화면이 적혀 있으면 그 화면에서, 없으면 해당 기관 사이트에서 처리 여부를 먼저 확인합니다.

결과 가져오기

GET /v1/jobs/{job_id}/result 는 상태가 SUCCEEDED 일 때만 결과를 돌려줍니다. 그 밖의 상태에서는 409, 없는 작업이면 404 입니다.

결과는 대부분 result.data 로 바로 옵니다. 엑셀 같은 파일을 만드는 작업만 result.data 대신 result.download_url 을 돌려주고, 이 주소는 15분 동안만 유효합니다. 만료되면 결과를 다시 조회해 새 주소를 받습니다.