작업 처리 흐름
모든 기관 호출은 작업으로 제출되어 비동기로 처리됩니다. 상태 확인부터 결과 수신까지의 흐름입니다.
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 로 옵니다 — 오류 코드. |
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'필드별 계약(길이·형식·오류)은 작업 상태 조회 레퍼런스에 있습니다.
결과가 나올 때까지 기다리기
상태가 QUEUED 나 RUNNING 이면 retry_after_seconds 만큼 기다렸다 다시 확인합니다. SUCCEEDED 가 되면 결과를 가져옵니다.
같은 연동(account_link_id)으로 낸 작업은 한 번에 하나씩 실행됩니다.앞선 작업이 RUNNING 인 동안 뒤 작업은 QUEUED 로 기다립니다.요청에서 account_link_id 를 빼도 서버가 하나뿐인 연동을 골라 채우면 그 연동의 순서에 들고, 연동 없이 실행되는 작업(예: 로그인)만 이 순서에 들지 않습니다.다른 연동의 작업이 먼저 접수돼 있으면 그 뒤에서도 QUEUED 로 기다릴 수 있습니다. 한 연동으로 여러 작업을 한꺼번에 내면 뒤 작업일수록 QUEUED 가 길어집니다.
그대로 실행할 수 있는 코드는 전체 예제에 있습니다.
재시도와 중복 방지
Idempotency-Key 는 "같은 요청"을 가리키는 키입니다.
네트워크 오류로 응답을 받지 못했다면 같은 키와 같은 본문으로 다시 보냅니다.이미 접수된 작업이면 새로 실행하지 않고 그 작업을 그대로 돌려줍니다(HTTP 200). 확인값(confirmation_token)을 받는 쓰기 작업도 같습니다. 확인값을 이미 썼거나 넣지 않았어도 접수된 작업이 먼저 돌아옵니다.처음 접수할 때의 확인값 규칙은 재시도(멱등성)의 「확인값을 받는 쓰기 작업의 재시도」 를 봅니다.
작업이 실패로 끝난 뒤에는 판단이 갈립니다. 다시 낼 때는 새 키를 씁니다.
- 오류의 retryable 이 false 면 같은 요청을 그대로 다시 제출하지 않습니다. 입력값이 잘못된 경우(VALIDATION_*)에는 값을 고친 뒤 새 키로 다시 냅니다.
- true 여서 다시 실행할 때도 새 키를 씁니다. 같은 키로 보내면 그때 실패한 작업이 그대로 돌아옵니다.
자세한 규칙은 재시도(멱등성)에 있습니다.
되돌릴 수 없는 작업이 PROVIDER_OUTCOME_UNCONFIRMED 로 끝났다면 다시 제출하지 마세요.두 번 처리될 위험이 있습니다. 발행, 신고, 신청 같은 작업이 그렇습니다. 기관에서 이미 처리됐을 수 있으니 오류 메시지에 적힌 기관 화면에서, 없으면 해당 기관 사이트에서 처리 여부를 먼저 확인합니다.
결과 가져오기
GET /v1/jobs/{job_id}/result 는 상태가 SUCCEEDED 일 때만 결과를 돌려줍니다.그 밖의 상태에서는 409, 없는 작업이거나 제출 때와 다른 환경으로 조회하면 404 입니다.
결과는 result.data 로 바로 옵니다.
- PDF나 엑셀 같은 파일을 만드는 작업은 result.artifacts 에 파일마다 이름, 크기, download_url 을 함께 돌려줍니다.
- 이 주소는 15분 동안만 유효합니다. 만료되면 결과를 다시 조회해 새 주소를 받습니다.
- 파일 자체는 7일 동안 보관됩니다.
목록을 엑셀 파일로도 받기
목록을 돌려주는 작업 중 일부는 같은 결과를 엑셀 파일로도 만들어 줍니다. 파일은 청할 때만 만듭니다.
- 되는 작업은 API 레퍼런스의 그 작업 params 표에 output_formats 행이 있습니다. 그 행이 없으면 파일을 만들지 않는 작업입니다.
- 제출할 때 params 에 "output_formats": ["xlsx"] 를 더하면, 결과의 result.artifacts 에 그 파일이 함께 옵니다.파일의 행은 result.data 의 목록과 같습니다.
- 파일 형식을 고를 수 없는 작업에 이 칸을 보내면 작업이 만들어지지 않고 400 VALIDATION_INVALID_FIELD 로 거부됩니다.
- MCP 에서도 같습니다. 파일을 만들 수 있는 도구만 입력 스키마에 output_formats 가 있고, 같은 값(["xlsx"])을 도구 인자로 보냅니다.
- 파일을 같이 받아도 사용량은 늘지 않습니다. 같은 작업 안에서 만들어지기 때문입니다.