개발자 문서
개발자 문서

작업 처리 흐름

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

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

  1. STEP 01
    제출

    POST /v1/jobs 로 보내고 job_id 를 받습니다.

  2. STEP 02
    상태 확인

    GET /v1/jobs/{job_id} 로 지금 상태를 봅니다.

  3. STEP 03
    다시 확인

    retry_after_seconds 만큼 기다렸다 반복합니다.

  4. STEP 04
    결과 받기

    SUCCEEDED 가 되면 /result 를 호출합니다.

작업을 제출하고, 상태를 확인하고, 권장 간격만큼 기다렸다 다시 확인해 성공하면 결과를 가져옵니다.

작업 상태

  1. QUEUED대기

    접수되어 처리 순서를 기다립니다.

  2. 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: real_test'

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

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

상태가 QUEUED 나 RUNNING 이면 retry_after_seconds 만큼 기다렸다 다시 확인합니다. SUCCEEDED 가 되면 결과를 가져옵니다.

같은 연동(account_link_id)으로 낸 작업은 한 번에 하나씩 실행됩니다.

그대로 실행할 수 있는 코드는 전체 예제에 있습니다.

재시도와 중복 방지

Idempotency-Key 는 "같은 요청"을 가리키는 키입니다.

네트워크 오류로 응답을 받지 못했다면 같은 키와 같은 본문으로 다시 보냅니다.

작업이 실패로 끝난 뒤에는 판단이 갈립니다. 다시 낼 때는 새 키를 씁니다.

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

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

되돌릴 수 없는 작업이 PROVIDER_OUTCOME_UNCONFIRMED 로 끝났다면 다시 제출하지 마세요.

결과 가져오기

GET /v1/jobs/{job_id}/result 는 상태가 SUCCEEDED 일 때만 결과를 돌려줍니다.

결과는 result.data 로 바로 옵니다.

  • PDF나 엑셀 같은 파일을 만드는 작업은 result.artifacts 에 파일마다 이름, 크기, download_url 을 함께 돌려줍니다.
  • 이 주소는 15분 동안만 유효합니다. 만료되면 결과를 다시 조회해 새 주소를 받습니다.
  • 파일 자체는 7일 동안 보관됩니다.

목록을 엑셀 파일로도 받기

목록을 돌려주는 작업 중 일부는 같은 결과를 엑셀 파일로도 만들어 줍니다. 파일은 청할 때만 만듭니다.

  • 되는 작업은 API 레퍼런스의 그 작업 params 표에 output_formats 행이 있습니다. 그 행이 없으면 파일을 만들지 않는 작업입니다.
  • 제출할 때 params 에 "output_formats": ["xlsx"] 를 더하면, 결과의 result.artifacts 에 그 파일이 함께 옵니다.
  • 파일 형식을 고를 수 없는 작업에 이 칸을 보내면 작업이 만들어지지 않고 400 VALIDATION_INVALID_FIELD 로 거부됩니다.
  • MCP 에서도 같습니다. 파일을 만들 수 있는 도구만 입력 스키마에 output_formats 가 있고, 같은 값(["xlsx"])을 도구 인자로 보냅니다.
  • 파일을 같이 받아도 사용량은 늘지 않습니다. 같은 작업 안에서 만들어지기 때문입니다.