개발자 문서
API 레퍼런스

기업지원금 - 고용24

1. 고용24 기업지원금 첨부 파일 삭제work24.subsidy.application.attachment_delete

MCP 도구 이름 work24__subsidy__application__attachment_delete

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

작성중인 신청 초안에 잘못 붙인 첨부 파일 한 건을 삭제합니다.

  • 작성중인 신청서의 첨부만 지울 수 있습니다. [고용24 로그인]
  • 삭제 요청 뒤 첨부서류 목록을 되읽어 그 파일(file_id)이 사라진 것을 확인하면 확정됩니다(outcome=confirmed).
  • 요청 거절(HTTP 400, 작업은 만들어지지 않음).
  • 요청 거절(HTTP 409, 작업은 만들어지지 않음).

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • work24이 API 고정값 (기본값)

예시 : work24

actionstring-Y호출할 작업입니다.
  • work24.subsidy.application.attachment_delete이 API 고정값 (기본값)

예시 : work24.subsidy.application.attachment_delete

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
programme_keystringY카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다

예시 : w24_b0010

business_management_nostringN고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다
receipt_nostringY민원신청접수번호 (2단계 저장이 발급)
confirmbooleanY실제로 첨부 파일을 삭제한다는 확인값입니다. 빠지거나 true 로 읽히지 않는 값이면 기관에 아무것도 보내지 않고 확인이 필요하다는 오류로 끝납니다. 이 칸만으로는 실행되지 않습니다. 첫 요청은 작업을 만들지 않고 HTTP 400 WRITE_CONFIRMATION_REQUIRED 와 error.confirmation_token 을 돌려주므로, 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 이 칸은 첫 요청부터 true 로 넣습니다. 토큰을 받은 뒤에 더하면 본문이 달라져 토큰이 맞지 않습니다
file_idstringYdraft_validate 의 documents[].attached_files[].file_id
confirmation_tokenstringN1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: attachment_delete-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "work24",
  "action": "work24.subsidy.application.attachment_delete",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "programme_key": "w24_b0010",
    "receipt_no": "<필수>",
    "confirm": "<필수: boolean>",
    "file_id": "<필수>"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • outcome=unconfirmed(위 '성공도 실패도 아님' 행)는 작업 자체가 FAILED 로 끝나 아래 필드가 전혀 오지 않습니다 - error.message 한 줄만 옵니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
programme_keystring지원사업 키
programme_label_kostring | number | boolean | object | array | null지원사업 한글명
business_management_nostring사업장관리번호
receipt_nostring첨부를 지운 신청 건의 접수번호
outcomestring판정 결과 - 이 표가 오는 경우는 항상 confirmed 입니다
deleted_file_idstring지운 첨부 파일의 번호 - 요청에 보낸 file_id 와 같은 값입니다
documentsobject삭제 뒤 첨부서류 목록 조회 결과 객체 - draft_validate 의 documents 와 같은 모양입니다(resolved, documents 목록 등)
verdict_detailobject확정 시 판정 근거 객체 - 삭제 요청에 대한 기관 응답 관찰값(http_status 등), 삭제 뒤 그 파일이 남았는지(file_still_attached), 삭제 전후의 서류에 맞지 않는 파일 수와 기관 저장소에서 사라진 파일 수를 담습니다
acknowledgementobject명시 확인 처리 결과 객체 - confirm·confirm_message_ko·confirm_message_measured 를 담고, 행정정보 동의가 필요한 액션(submit·modify)은 admin_info_sharing_consent 등도 함께 옵니다
actionstring이번에 처리한 액션 이름
stepnumber신청 진행 단계 식별자
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "work24",
    "action": "work24.subsidy.application.attachment_delete",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED성공도 실패도 아님(미확인) — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 삭제 요청은 나갔지만 삭제 뒤 목록을 되읽지 못했거나, 되읽은 목록에 그 파일이 아직 있거나, 기관 응답이 성공이 아니었습니다. 다시 삭제를 시도하지 말고 draft_validate 로 첨부서류 목록을 확인합니다. 파일이 아직 보이면 고용24 [기업지원금 > 신청] 화면에서 직접 지웁니다. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다.
AUTH_REQUIRED세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다.
PROVIDER_IP_REJECTED접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다.
PROVIDER_TIMEOUT_READ응답 지연 — 고용24 응답이 지연됐습니다. 재시도 불가로 표시되므로 바로 다시 부르지 말고 잠시 뒤 상태를 확인한 뒤 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다.
PROVIDER_UNAVAILABLE연결 오류 — 고용24 접속에 실패했습니다. 잠시 후 다시 호출합니다.
VALIDATION_SEMANTIC_ERROR파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다.
VALIDATION_INVALID_FIELD사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다.
POLICY_FEATURE_DISABLED쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다.
VALIDATION_MISSING_FIELD확인 누락 — confirm=true 가 없습니다. 파일을 지우는 되돌리기 어려운 요청이라 API 가 명시 확인을 요구합니다(이 확인은 고용24 화면의 확인창을 옮긴 것이 아니라 XBOSS 가 정한 확인입니다).
RESOURCE_NOT_FOUND접수번호 미확인 — receipt_no 의 신청서를 첨부 화면에서 확인하지 못했습니다(DRAFT_NOT_FOUND).
RESOURCE_NOT_FOUND파일 번호 없음 — 이 접수번호에 file_id 인 파일이 붙어 있지 않습니다(ATTACHMENT_NOT_FOUND). draft_validate 응답의 documents.documents[].attached_files[].file_id 에서 다시 확인합니다.
RESOURCE_CONFLICT첨부서류 목록 확인 불가 — 이 신청서의 첨부서류 목록을 확인하지 못해 멈췄습니다(ATTACHMENT_LIST_UNRESOLVED). 첨부 영역이 아직 확인하지 못한 방식이라 멈추는 경우(ATTACHMENT_MODULE_UNSUPPORTED)도 같은 코드이고, 그때는 고용24 [기업지원금 > 신청] 화면에서 직접 지웁니다. 삭제 요청은 보내지 않았습니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)은 신청서 화면을 여는 과정의 저장이 이미 반영됐을 수 있습니다. draft_validate 로 첨부서류 목록이 보이는지 먼저 확인합니다.
RESOURCE_CONFLICT첨부를 바꿀 수 없는 상태 — 첨부는 작성중인 신청서에서만 바꿉니다. 처리상태를 확인하지 못했거나(ATTACHMENT_STATE_UNVERIFIED), 작성중이 아니거나(ATTACHMENT_NOT_EDITABLE), 보완요청 상태라 첨부를 저장하면 보완 제출이 되는 경우(ATTACHMENT_ON_SUPPLEMENT_UNSUPPORTED)에 삭제 전에 멈춥니다. 삭제 요청은 보내지 않았습니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)은 신청서 화면을 여는 과정의 저장이 이미 반영됐을 수 있습니다. 보완요청 상태의 첨부는 고용24 화면에서 직접 보완합니다.

2. 고용24 기업지원금 작성중 초안 삭제work24.subsidy.application.delete

MCP 도구 이름 work24__subsidy__application__delete

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

아직 제출하지 않은 신청 초안을 삭제합니다.

  • 작성중 초안만 지울 수 있습니다(제출된 신청서는 withdraw 로 철회합니다). confirm=true 를 함께 보냅니다. 이 상품의 신청서 쓰기 기능이 정책으로 켜져 있어야 합니다. [고용24 로그인]
  • 삭제 전후 이력을 되읽어 실제로 사라진 것을 확인하면 deleted:true 로 확정됩니다(outcome=confirmed).
  • 요청 거절(HTTP 400, 작업은 만들어지지 않음).
  • 요청 거절(HTTP 409, 작업은 만들어지지 않음).

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • work24이 API 고정값 (기본값)

예시 : work24

actionstring-Y호출할 작업입니다.
  • work24.subsidy.application.delete이 API 고정값 (기본값)

예시 : work24.subsidy.application.delete

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
programme_keystringY카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다

예시 : w24_b0010

business_management_nostringN고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다
receipt_nostringY민원신청접수번호 (2단계 저장이 발급)
confirmbooleanY실제로 신청서를 삭제한다는 확인값입니다. 빠지거나 true 로 읽히지 않는 값이면 기관에 아무것도 보내지 않고 확인이 필요하다는 오류로 끝납니다. 이 칸만으로는 실행되지 않습니다. 첫 요청은 작업을 만들지 않고 HTTP 400 WRITE_CONFIRMATION_REQUIRED 와 error.confirmation_token 을 돌려주므로, 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 이 칸은 첫 요청부터 true 로 넣습니다. 토큰을 받은 뒤에 더하면 본문이 달라져 토큰이 맞지 않습니다
confirmation_tokenstringN1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: delete-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "work24",
  "action": "work24.subsidy.application.delete",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "programme_key": "w24_b0010",
    "receipt_no": "<필수>",
    "confirm": "<필수: boolean>"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • outcome=unconfirmed(위 '성공도 실패도 아님' 행)는 작업 자체가 FAILED 로 끝나 아래 필드가 전혀 오지 않습니다 - error.message 한 줄만 옵니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
programme_keystring지원사업 키
programme_label_kostring | number | boolean | object | array | null지원사업 한글명
business_management_nostring사업장관리번호
receipt_nostring삭제를 시도한 접수번호
outcomestring판정 결과 - 이 표가 오는 경우는 항상 confirmed 입니다
deletedboolean삭제 확정 여부 - 이 표가 오는 경우는 항상 true 입니다
verdict_detailobject확정 시 판정 근거 객체 - 삭제 전/후 이력 조회 결과를 대조한 값입니다
provider_statusnumber기관 응답 HTTP 상태 코드(증거 기록용)
prss_modestring기관에 보낸 처리 모드 코드(삭제 DELT)
acknowledgementobject명시 확인 처리 결과 객체 - confirm·confirm_message_ko·confirm_message_measured 를 담고, 행정정보 동의가 필요한 액션(submit·modify)은 admin_info_sharing_consent 등도 함께 옵니다
actionstring이번에 처리한 액션 이름
stepnull신청 진행 단계 식별자 - 이 액션은 신청 단계 밖이라 항상 null 입니다
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "work24",
    "action": "work24.subsidy.application.delete",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED성공도 실패도 아님(미확인) — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 세 경우 중 하나입니다 - ① 이 사업의 이력 화면을 아직 충분히 지원하지 못해 삭제 전에도 목록에서 존재를 확인하지 못했거나(그래서 삭제 후 '없다'도 증거가 못 됨), ② 삭제 전·후 이력 조회 자체가 실패했거나, ③ 삭제 요청을 보낸 뒤에 실패가 생겼습니다(아래 「요청을 보낸 뒤의 실패」 행). deleted:false 로 확인 안 됨을 알립니다. 다시 삭제를 시도하지 말고 고용24 화면에서 직접 확인합니다. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다.
AUTH_REQUIRED세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다.
PROVIDER_IP_REJECTED접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다.
PROVIDER_TIMEOUT_READ응답 지연 — 고용24 응답이 지연됐습니다. 재시도 불가로 표시되므로 바로 다시 부르지 말고 잠시 뒤 상태를 확인한 뒤 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다.
PROVIDER_UNAVAILABLE연결 오류 — 고용24 접속에 실패했습니다. 잠시 후 다시 호출합니다.
PROVIDER_OUTCOME_UNCONFIRMED요청을 보낸 뒤의 실패 — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 쓰기 요청이 기관에 나간 뒤에 생긴 실패는 원인(기관의 5xx 나 4xx 응답, 접근 제한, 응답 지연, 연결 끊김)과 관계없이 이 코드로 끝납니다. 처리됐는지 알 수 없으므로 다시 실행하지 말고 history 로 접수번호의 현재 상태를 확인합니다. 위의 접근 제한, 응답 지연, 업스트림 오류, 연결 오류 행은 쓰기 요청이 나가기 전에 생긴 실패(화면을 여는 단계, 연결을 맺지 못함)에 해당합니다. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다.
VALIDATION_SEMANTIC_ERROR파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다.
VALIDATION_INVALID_FIELD사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다.
POLICY_FEATURE_DISABLED쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다.
VALIDATION_MISSING_FIELD확인 누락 — confirm=true 가 없습니다. 이 액션은 고용24 화면에서도 확인 대화상자를 거치는 되돌리기 어려운 요청이라 API 도 명시 확인을 요구합니다.
RESOURCE_NOT_FOUND접수번호 미확인 — receipt_no 의 초안을 화면에서 확인하지 못했습니다(DRAFT_NOT_FOUND).
RESOURCE_CONFLICT삭제 실패(남아있음) — 삭제 요청 뒤에도 접수번호가 신청 이력에 남아 있습니다(DELETE_FAILED). 이력을 되읽어 확인한 결과라 결과 모름이 아니라 삭제되지 않은 것이 확인된 상태입니다. 고용24 화면에서 직접 삭제해야 하며, error.message 에 그 화면 위치를 알리는 다음 단계 안내가 함께 옵니다.

3. 고용24 기업지원금 제출 전 확인work24.subsidy.application.draft_validate

MCP 도구 이름 work24__subsidy__application__draft_validate

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

작성한 신청서를 제출 전에 점검하고 첨부서류 목록을 받습니다.

  • workplace_save 로 발급받은 receipt_no 가 있어야 합니다. 고용24 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [고용24 로그인]

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • work24이 API 고정값 (기본값)

예시 : work24

actionstring-Y호출할 작업입니다.
  • work24.subsidy.application.draft_validate이 API 고정값 (기본값)

예시 : work24.subsidy.application.draft_validate

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
programme_keystringY카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다

예시 : w24_b0010

business_management_nostringN고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다
receipt_nostringY민원신청접수번호 (2단계 저장이 발급)
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: draft_validate-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "work24",
  "action": "work24.subsidy.application.draft_validate",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "programme_key": "w24_b0010",
    "receipt_no": "<필수>"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • result.data 의 missing_required_documents · missing_required_fields 로 제출 전 빠진 것이 있는지 확인합니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
programme_keystring지원사업 키
programme_label_kostring | number | boolean | object | array | null지원사업 한글명
business_management_nostring사업장관리번호
receipt_nostring이 신청 건의 접수번호
screen_statusnumber기관 화면 진행 상태 코드
attachment_moduleobject첨부서류 모듈 안내 객체
documentsobject첨부서류 목록 조회 결과 객체 - resolved · documents(목록) · document_count · mandatory_count · missing_required_documents 등을 담습니다
missing_required_documentsarray빠진 필수 첨부서류 목록
fraud_prevention_videoobject | null부정수급 방지 교육 영상 시청 확인 객체
safetyobject저장·제출 실행 여부를 나타내는 안전 상태 객체
workflow_gateobject제출 가능 여부 객체 - can_submit 과, 막혀 있으면 그 사유(blocked_reason_ko)
normalized_inputobject지금까지 입력한 값을 표준화한 객체
draft_form_previewobject제출 전 신청서 미리보기 객체
field_bindingsobject입력값과 기관 화면 필드의 대응 관계 객체
required_fieldsarray필수 입력 필드 이름 목록
missing_required_fieldsarray빠진 필수 입력 필드 이름 목록
field_errorsarray필드별 오류 목록 - 정상이면 항상 빈 배열입니다
warningsarray제출 전 참고할 경고 목록
screen_notesarray기관 화면이 보여주는 참고 문구 목록
followup_endpointsarray이어서 호출할 수 있는 후속 액션 목록
actionstring이번에 처리한 액션 이름
stepnumber신청 진행 단계 식별자
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "work24",
    "action": "work24.subsidy.application.draft_validate",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다.
PROVIDER_IP_REJECTED접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다.
PROVIDER_UNAVAILABLE연결 오류 — 고용24 접속에 실패했습니다. 응답 지연(타임아웃)도 이 코드로 옵니다 - 조회는 재시도해도 안전한 요청이라 재시도 가능으로 표시됩니다. 잠시 후 다시 호출합니다.
VALIDATION_SEMANTIC_ERROR파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다.
VALIDATION_INVALID_FIELD사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다.
VALIDATION_INVALID_FIELD지원사업 키 확인 불가 — programme_key 가 카탈로그에 없거나 아직 이 상품에서 지원하지 않는 사업입니다. 카탈로그 사업 중 신청을 지원하는 것은 일부뿐입니다 - 값을 다시 확인합니다.
POLICY_FEATURE_DISABLED쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다.

4. 고용24 기업지원금 신청 이력 조회work24.subsidy.application.history

MCP 도구 이름 work24__subsidy__application__history

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

지금까지 신청한 지원금 건과 처리 상태를 조회합니다.

  • 고용24 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [고용24 로그인]

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • work24이 API 고정값 (기본값)

예시 : work24

actionstring-Y호출할 작업입니다.
  • work24.subsidy.application.history이 API 고정값 (기본값)

예시 : work24.subsidy.application.history

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
programme_keystring-Y카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다

예시 : w24_b0010

business_management_nostring-N고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다
date_fromstring8N조회 시작일. date_to 와 함께 입력하거나 둘 다 비웁니다. 둘 다 비우면 오늘(한국 시간)까지 최근 30일을 조회합니다

형식 : YYYYMMDD

date_tostring8N조회 종료일. date_from 과 함께 입력하거나 둘 다 비웁니다

형식 : YYYYMMDD

output_formatsarray-N이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: history-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "work24",
  "action": "work24.subsidy.application.history",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "programme_key": "w24_b0010"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • result.data 의 rows 로 지금까지 신청한 건과 처리 상태를 확인합니다.
  • 아래 표의 rows[] 줄 가운데 svc_cd 와 status_label_ko 줄을 뺀 나머지는 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 엑셀 파일 맨 윗줄의 머리글입니다.
  • svc_cd 와 status_label_ko 칸은 엑셀 파일에 없고 응답에만 있으며, 이 표가 응답 행의 칸 전부입니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
programme_keystring지원사업 키
programme_label_kostring | number | boolean | object | array | null지원사업 한글명
business_management_nostring사업장관리번호
date_fromstring조회 시작일
date_tostring조회 종료일
row_countnumber조회된 신청 건수
rowsarray신청 이력 목록 - 건별 접수번호와 처리 상태를 담습니다
rows[].receipt_nostring | number | boolean | object | array | null접수번호
rows[].applied_onstring | number | boolean | object | array | null신청 일자
rows[].status_codestring | number | boolean | object | array | null처리 상태 (값: AGC0B = 작성중, AGC0D = 처리중, AGC0E = 보완요청, AGC0F = 반려, AGC0G = 처리완료, AGC0K = 결재완료, AGC0H = 접수취소, AGC0M = 변경승인)
rows[].application_yearstring | number | boolean | object | array | null신청 귀속연도
rows[].application_roundstring | number | boolean | object | array | null신청 순번
rows[].cvpl_fomt_cdstring | number | boolean | object | array | null민원서식코드
rows[].svc_cdstring | number | boolean | object | array | null조회한 지원사업의 서비스 코드입니다. 이 값으로 목록을 거르므로 모든 행의 값이 같습니다.
rows[].status_label_kostring | number | boolean | object | array | null이 행의 status_code 에 해당하는 한글 처리 상태입니다. 응답 최상위 status_code_labels_ko 의 같은 항목이며, 그 표에 없는 코드이면 null 입니다.
status_code_labels_kostring | number | boolean | object | array | null처리 상태 코드별 한글 라벨 객체
note_kostring조회 결과에 대한 한국어 안내 문구
actionstring이번에 처리한 액션 이름
stepnull신청 진행 단계 식별자 - 이 액션은 신청 단계 밖이라 항상 null 입니다
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "work24",
    "action": "work24.subsidy.application.history",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다.
PROVIDER_IP_REJECTED접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다.
PROVIDER_UNAVAILABLE연결 오류 — 고용24 접속에 실패했습니다. 응답 지연(타임아웃)도 이 코드로 옵니다 - 조회는 재시도해도 안전한 요청이라 재시도 가능으로 표시됩니다. 잠시 후 다시 호출합니다.
VALIDATION_SEMANTIC_ERROR파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다.
VALIDATION_INVALID_FIELD사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다.
VALIDATION_INVALID_FIELD지원사업 키 확인 불가 — programme_key 가 카탈로그에 없거나 아직 이 상품에서 지원하지 않는 사업입니다. 카탈로그 사업 중 신청을 지원하는 것은 일부뿐입니다 - 값을 다시 확인합니다.
INTERNAL_ERROR그 밖의 오류 — 화면 경로를 해석하지 못했거나, 이 화면에서 사업자 식별 정보를 확인하지 못했거나, 응답에 이력 목록 자체가 없거나, 이 사업의 이력 화면을 아직 지원하지 않는 경우입니다. 응답의 error.message 는 이 사유가 아니라 일반 안내('서버 내부 오류로 작업을 마치지 못했습니다. 서비스문의로 알려 주세요.')로 옵니다.

5. 고용24 기업지원금 신청 진입work24.subsidy.application.init

MCP 도구 이름 work24__subsidy__application__init

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

지원사업 신청을 시작하고 우리 사업장이 신청할 수 있는지 확인합니다.

  • 고용24 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [고용24 로그인]
  • 사전진단이 있는 사업에서 그 진단 조회가 기관 쪽에서 실패해도 작업 오류가 아니라 diagnosis 안에 verdict:"undetermined"·error 가 담기고 최상위 can_apply 는 false 로 옵니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • work24이 API 고정값 (기본값)

예시 : work24

actionstring-Y호출할 작업입니다.
  • work24.subsidy.application.init이 API 고정값 (기본값)

예시 : work24.subsidy.application.init

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
programme_keystringY카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다

예시 : w24_b0010

business_management_nostringN고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다
application_yearnumberN신청 귀속연도입니다. options 가 있으면 그 value 중 하나를 입력해 주세요(예: 2026)
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: init-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "work24",
  "action": "work24.subsidy.application.init",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "programme_key": "w24_b0010"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • result.data 의 can_apply 로 신청 가능 여부를, diagnosis 로 사전진단 결과를 확인합니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
programme_keystring지원사업 키
programme_label_kostring | number | boolean | object | array | null지원사업 한글명
business_management_nostring사업장관리번호
diagnosisobject | null사전진단 결과 객체 - 그 사업이 사전진단 대상이 아니면 available·reason·evidence 3키만, 대상이면 subsidy.diagnosis.search 의 결과 항목 하나와 같은 모양입니다
can_applyboolean | null신청 가능 여부 - 사전진단이 없는 사업은 항상 true 이거나 판정 없음(null)입니다
message_kostring안내 문구 - 사전진단이 없는 사업에서만 옵니다. 진단이 있는 사업은 대신 diagnosis 안의 문구를 봅니다
next_action_hintstring다음 호출로 이어갈 액션 힌트
actionstring이번에 처리한 액션 이름
stepnumber신청 진행 단계 식별자
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "work24",
    "action": "work24.subsidy.application.init",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다.
VALIDATION_SEMANTIC_ERROR파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다.
VALIDATION_INVALID_FIELD사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다.
VALIDATION_INVALID_FIELD지원사업 키 확인 불가 — programme_key 가 카탈로그에 없거나 아직 이 상품에서 지원하지 않는 사업입니다. 카탈로그 사업 중 신청을 지원하는 것은 일부뿐입니다 - 값을 다시 확인합니다.

6. 고용24 기업지원금 신청 수정work24.subsidy.application.modify

MCP 도구 이름 work24__subsidy__application__modify

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

기관이 보완을 요청한 지원금 신청서에 같은 접수번호로 수정 요청을 보냅니다.

  • 제출한 신청서가 기관으로부터 '보완요청'을 받은 상태여야 합니다(작성중 초안은 workplace_save 로 이어서 작성합니다). [고용24 로그인]
  • outcome=confirmed 로 확정되면 modified:true 와 함께 '보완요청' 상태를 벗어났는지 확인합니다. 수정 제출을 되돌리는 액션은 없습니다.
  • 요청 거절(HTTP 400, 작업은 만들어지지 않음).
  • 요청 거절(HTTP 409, 작업은 만들어지지 않음).

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • work24이 API 고정값 (기본값)

예시 : work24

actionstring-Y호출할 작업입니다.
  • work24.subsidy.application.modify이 API 고정값 (기본값)

예시 : work24.subsidy.application.modify

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
programme_keystringY카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다

예시 : w24_b0010

business_management_nostringN고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다
receipt_nostringY민원신청접수번호 (2단계 저장이 발급)
confirmbooleanY실제로 제출한 신청서를 수정한다는 확인값입니다. 빠지거나 true 로 읽히지 않는 값이면 기관에 아무것도 보내지 않고 확인이 필요하다는 오류로 끝납니다. 이 칸만으로는 실행되지 않습니다. 첫 요청은 작업을 만들지 않고 HTTP 400 WRITE_CONFIRMATION_REQUIRED 와 error.confirmation_token 을 돌려주므로, 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 이 칸은 첫 요청부터 true 로 넣습니다. 토큰을 받은 뒤에 더하면 본문이 달라져 토큰이 맞지 않습니다
admin_info_sharing_consentbooleanY행정정보 공동이용 동의 여부입니다. 동의하면 true, 동의하지 않으면 false 를 보냅니다. 보내지 않으면 제출하지 않고 입력 오류(400, WORK24_SUBSIDY_APPLICATION_ADMIN_INFO_CONSENT_REQUIRED)로 답합니다. 동의 여부는 고객이 직접 정하는 사항이라 XBOSS가 대신 정하지 않습니다
attachmentsarrayN첨부 서류입니다. 첨부 서류가 포함된 신청은 지금 준비 중이라 비워서 보냅니다. 값이 있으면 기관에 보내기 전에 멈추고 501(WORK24_SUBSIDY_APPLICATION_ATTACHMENT_UPLOAD_NOT_MEASURED)로 답합니다. 첨부가 필요 없는 신청은 그대로 이용하실 수 있습니다
confirmation_tokenstringN1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: modify-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "work24",
  "action": "work24.subsidy.application.modify",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "programme_key": "w24_b0010",
    "receipt_no": "<필수>",
    "confirm": "<필수: boolean>",
    "admin_info_sharing_consent": "<필수: boolean>"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • outcome=unconfirmed(위 '성공도 실패도 아님' 행)는 작업 자체가 FAILED 로 끝나 아래 필드가 전혀 오지 않습니다 - error.message 한 줄만 옵니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
programme_keystring지원사업 키
programme_label_kostring | number | boolean | object | array | null지원사업 한글명
business_management_nostring사업장관리번호
receipt_nostring이 신청 건의 접수번호
outcomestring판정 결과 - 이 표가 오는 경우는 항상 confirmed 입니다
prss_modestring기관에 보낸 처리 모드 코드(제출 SNDG · 수정 UPDT)
provider_statusnumber기관 응답 HTTP 상태 코드(증거 기록용 - 판정에는 쓰이지 않습니다)
submittedboolean제출 확정 여부(submit 호출일 때만 true 일 수 있습니다)
modifiedboolean수정 확정 여부(modify 호출일 때만 true 일 수 있습니다)
verdict_detailobject확정 시 판정 근거 객체 - 이력·화면 상태를 전/후로 대조한 값입니다
documentsobject제출 시점의 첨부서류 목록 조회 결과 객체
fraud_prevention_videoobject | null부정수급 방지 교육 영상 시청 확인 객체 - modify 호출에도 이 키는 오지만 값은 항상 null 입니다(그 사업 로직이 submit 에만 있습니다)
undo_hint_kostring되돌리는 방법 안내 - submit 은 withdraw, modify 는 되돌리는 액션 없음
acknowledgementobject명시 확인 처리 결과 객체 - confirm·confirm_message_ko·confirm_message_measured 를 담고, 행정정보 동의가 필요한 액션(submit·modify)은 admin_info_sharing_consent 등도 함께 옵니다
actionstring이번에 처리한 액션 이름
stepnumber신청 진행 단계 식별자
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "work24",
    "action": "work24.subsidy.application.modify",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED성공도 실패도 아님(미확인) — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 제출 응답 본문만으로는 성공을 확정하지 않고 제출 전후 이력을 되읽어 판정합니다. 요청을 보낸 뒤에 생긴 실패도 이 코드로 끝납니다(아래 「요청을 보낸 뒤의 실패」 행). 처리상태가 아직 '보완요청'이면 기관이 수정을 처리로 가져가지 않은 것일 수 있습니다. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다.
AUTH_REQUIRED세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다.
PROVIDER_IP_REJECTED접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다.
PROVIDER_TIMEOUT_READ응답 지연 — 고용24 응답이 지연됐습니다. 재시도 불가로 표시되므로 바로 다시 부르지 말고 잠시 뒤 상태를 확인한 뒤 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다.
PROVIDER_UNAVAILABLE연결 오류 — 고용24 접속에 실패했습니다. 잠시 후 다시 호출합니다.
PROVIDER_OUTCOME_UNCONFIRMED요청을 보낸 뒤의 실패 — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 쓰기 요청이 기관에 나간 뒤에 생긴 실패는 원인(기관의 5xx 나 4xx 응답, 접근 제한, 응답 지연, 연결 끊김)과 관계없이 이 코드로 끝납니다. 처리됐는지 알 수 없으므로 다시 실행하지 말고 history 로 접수번호의 현재 상태를 확인합니다. 위의 접근 제한, 응답 지연, 업스트림 오류, 연결 오류 행은 쓰기 요청이 나가기 전에 생긴 실패(화면을 여는 단계, 연결을 맺지 못함)에 해당합니다. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다.
VALIDATION_SEMANTIC_ERROR파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다.
VALIDATION_INVALID_FIELD사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다.
POLICY_FEATURE_DISABLED쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다.
VALIDATION_MISSING_FIELD확인 누락 — confirm=true 가 없습니다. 이 액션은 고용24 화면에서도 확인 대화상자를 거치는 되돌리기 어려운 요청이라 API 도 명시 확인을 요구합니다.
VALIDATION_MISSING_FIELD행정정보 동의 미지정 — admin_info_sharing_consent(true/false)가 없습니다. 기관 제출 화면이 필수로 요구하는 동의 항목이고 고객이 직접 정할 법적 동의라 XBOSS가 대신 정하지 않습니다. 동의하지 않아도 제출은 되지만, 행정정보로 대체 확인하지 못하는 서류는 직접 첨부해야 할 수 있습니다.
INTERNAL_ERROR첨부 동시 업로드 불가 — attachments 에 값을 채워 보내면 제출 자체를 중단합니다(파일을 기관으로 보내는 기능은 아직 지원하지 않고, 조용히 무시하면 첨부 없이 접수되어 서류 누락 반려로 이어지기 때문입니다). 첨부는 고용24 화면에서 먼저 올린 뒤 draft_validate 로 붙었는지 확인하고 제출합니다. 응답의 error.message 는 '신청이 기관에 전송되기 전에 중단됐습니다. 접수된 내용은 없으니 중복 걱정은 하지 않으셔도 됩니다.' 로 시작하고, 줄을 바꿔 '다음 단계:' 뒤에 이 사유와 다음 행동이 이어집니다. 기관에 반영된 것이 없으므로 같은 요청을 다시 호출해도 중복 처리가 되지 않습니다.
RESOURCE_NOT_FOUND접수번호 화면에서 확인 안 됨 — receipt_no 의 신청서를 제출 화면에서 확인하지 못했습니다(DRAFT_NOT_FOUND).
RESOURCE_CONFLICT수정 대상 상태 아님 — 셋 중 하나입니다: 처리상태를 확인하지 못했거나(MODIFY_STATE_UNVERIFIED), 아직 작성중 초안이라 수정이 의미가 없거나(MODIFY_ON_DRAFT — 이때는 workplace_save 로 이어서 작성합니다), 보완요청 상태가 아닌 다른 처리상태입니다(NOT_MODIFIABLE — 수정은 '보완요청' 상태에만 가능합니다. 실무에서 가장 자주 맞는 경우입니다). 보내기 전에 막습니다.

7. 고용24 기업지원금 신청 필요입력 안내work24.subsidy.application.requirements

MCP 도구 이름 work24__subsidy__application__requirements

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

지원금을 신청하기 전에 준비해야 할 입력값과 서류, 등록된 지급계좌를 알려줍니다.

  • 고용24 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [고용24 로그인]

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • work24이 API 고정값 (기본값)

예시 : work24

actionstring-Y호출할 작업입니다.
  • work24.subsidy.application.requirements이 API 고정값 (기본값)

예시 : work24.subsidy.application.requirements

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
programme_keystringY카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다

예시 : w24_b0010

business_management_nostringN고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다
application_yearnumberN신청 귀속연도입니다. options 가 있으면 그 value 중 하나를 입력해 주세요(예: 2026)
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: requirements-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "work24",
  "action": "work24.subsidy.application.requirements",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "programme_key": "w24_b0010"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • result.data 의 inputs · attachments 로 준비할 입력값과 서류를 확인합니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
programme_keystring지원사업 키
programme_label_kostring | number | boolean | object | array | null지원사업 한글명
business_management_nostring사업장관리번호
inputsarray신청서 작성에 필요한 입력값 목록
blockedboolean필요입력 확인 결과 신청이 막혀 있는지 여부
blocking_reasonsarray막혀 있다면 그 사유 목록
safetyobject이 호출은 입력 안내만 하며 저장과 제출을 하지 않았다는 고정 표시 객체 - input_only true, save_executed false, submit_executed false 입니다
registered_accountsobject등록된 지급계좌 조회 결과 객체 - 읽으면 resolved true 와 기관이 준 전체 건수 count, 계좌 목록 accounts(은행명 bank_name, 계좌번호 account_no, 화면 표기 account_no_display, 예금주 holder)가 옵니다. 첫 쪽만 읽어 받은 줄이 건수보다 적으면 partial true 가 붙습니다. 조회하지 못했거나 이 화면에 지급계좌 칸이 없으면 오류가 아니라 resolved false 와 사유 코드 reason 으로 옵니다 - 계좌가 없다는 뜻이 아니므로 accounts 가 늘 있다고 기대하지 마세요
declared_but_not_on_this_screenarray다른 화면에서만 확인되는, 이 응답에는 없는 선언 항목 목록
attachmentsobject필요한 첨부서류 안내 객체
actionstring이번에 처리한 액션 이름
stepnumber신청 진행 단계 식별자
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "work24",
    "action": "work24.subsidy.application.requirements",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다.
PROVIDER_IP_REJECTED접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다.
PROVIDER_UNAVAILABLE연결 오류 — 고용24 접속에 실패했습니다. 응답 지연(타임아웃)도 이 코드로 옵니다 - 조회는 재시도해도 안전한 요청이라 재시도 가능으로 표시됩니다. 잠시 후 다시 호출합니다.
VALIDATION_SEMANTIC_ERROR파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다.
VALIDATION_INVALID_FIELD사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다.
VALIDATION_INVALID_FIELD지원사업 키 확인 불가 — programme_key 가 카탈로그에 없거나 아직 이 상품에서 지원하지 않는 사업입니다. 카탈로그 사업 중 신청을 지원하는 것은 일부뿐입니다 - 값을 다시 확인합니다.

8. 고용24 기업지원금 신청 제출work24.subsidy.application.submit

MCP 도구 이름 work24__subsidy__application__submit

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

작성을 마친 지원금 신청서를 고용노동부에 제출합니다.

  • workplace_save 로 발급받은 receipt_no 가 있어야 하고, draft_validate 로 제출 가능 상태(첨부서류·부정수급 방지 영상)를 먼저 확인해야 합니다. [고용24 로그인]
  • outcome=confirmed 로 확정되면 submitted:true 와 함께 접수 이탈을 확인합니다. undo_hint_ko 로 되돌리는 방법(withdraw)을 안내합니다.
  • 요청 거절(HTTP 400, 작업은 만들어지지 않음).
  • 요청 거절(HTTP 409, 작업은 만들어지지 않음).

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • work24이 API 고정값 (기본값)

예시 : work24

actionstring-Y호출할 작업입니다.
  • work24.subsidy.application.submit이 API 고정값 (기본값)

예시 : work24.subsidy.application.submit

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
programme_keystringY카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다

예시 : w24_b0010

business_management_nostringN고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다
receipt_nostringY민원신청접수번호 (2단계 저장이 발급)
confirmbooleanY실제로 신청서를 제출한다는 확인값입니다. 빠지거나 true 로 읽히지 않는 값이면 기관에 아무것도 보내지 않고 확인이 필요하다는 오류로 끝납니다. 이 칸만으로는 실행되지 않습니다. 첫 요청은 작업을 만들지 않고 HTTP 400 WRITE_CONFIRMATION_REQUIRED 와 error.confirmation_token 을 돌려주므로, 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 이 칸은 첫 요청부터 true 로 넣습니다. 토큰을 받은 뒤에 더하면 본문이 달라져 토큰이 맞지 않습니다
admin_info_sharing_consentbooleanY행정정보 공동이용 동의 여부입니다. 동의하면 true, 동의하지 않으면 false 를 보냅니다. 보내지 않으면 제출하지 않고 입력 오류(400, WORK24_SUBSIDY_APPLICATION_ADMIN_INFO_CONSENT_REQUIRED)로 답합니다. 동의 여부는 고객이 직접 정하는 사항이라 XBOSS가 대신 정하지 않습니다
attachmentsarrayN첨부 서류입니다. 첨부 서류가 포함된 신청은 지금 준비 중이라 비워서 보냅니다. 값이 있으면 기관에 보내기 전에 멈추고 501(WORK24_SUBSIDY_APPLICATION_ATTACHMENT_UPLOAD_NOT_MEASURED)로 답합니다. 첨부가 필요 없는 신청은 그대로 이용하실 수 있습니다
confirmation_tokenstringN1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: submit-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "work24",
  "action": "work24.subsidy.application.submit",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "programme_key": "w24_b0010",
    "receipt_no": "<필수>",
    "confirm": "<필수: boolean>",
    "admin_info_sharing_consent": "<필수: boolean>"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • outcome=unconfirmed(위 '성공도 실패도 아님' 행)는 작업 자체가 FAILED 로 끝나 아래 필드가 전혀 오지 않습니다 - error.message 한 줄만 옵니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
programme_keystring지원사업 키
programme_label_kostring | number | boolean | object | array | null지원사업 한글명
business_management_nostring사업장관리번호
receipt_nostring이 신청 건의 접수번호
outcomestring판정 결과 - 이 표가 오는 경우는 항상 confirmed 입니다
prss_modestring기관에 보낸 처리 모드 코드(제출 SNDG · 수정 UPDT)
provider_statusnumber기관 응답 HTTP 상태 코드(증거 기록용 - 판정에는 쓰이지 않습니다)
submittedboolean제출 확정 여부(submit 호출일 때만 true 일 수 있습니다)
modifiedboolean수정 확정 여부(modify 호출일 때만 true 일 수 있습니다)
verdict_detailobject확정 시 판정 근거 객체 - 이력·화면 상태를 전/후로 대조한 값입니다
documentsobject제출 시점의 첨부서류 목록 조회 결과 객체
fraud_prevention_videoobject | null부정수급 방지 교육 영상 시청 확인 객체 - modify 호출에도 이 키는 오지만 값은 항상 null 입니다(그 사업 로직이 submit 에만 있습니다)
undo_hint_kostring되돌리는 방법 안내 - submit 은 withdraw, modify 는 되돌리는 액션 없음
acknowledgementobject명시 확인 처리 결과 객체 - confirm·confirm_message_ko·confirm_message_measured 를 담고, 행정정보 동의가 필요한 액션(submit·modify)은 admin_info_sharing_consent 등도 함께 옵니다
actionstring이번에 처리한 액션 이름
stepnumber신청 진행 단계 식별자
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "work24",
    "action": "work24.subsidy.application.submit",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED성공도 실패도 아님(미확인) — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 제출 응답 본문만으로는 성공을 확정하지 않고 제출 전후 이력을 되읽어 판정합니다. 요청을 보낸 뒤에 생긴 실패도 이 코드로 끝납니다(아래 「요청을 보낸 뒤의 실패」 행). history 로 현재 상태를 확인한 뒤, 아직 '작성중'이면 그때 다시 제출하세요. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다.
AUTH_REQUIRED세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다.
PROVIDER_IP_REJECTED접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다.
PROVIDER_TIMEOUT_READ응답 지연 — 고용24 응답이 지연됐습니다. 재시도 불가로 표시되므로 바로 다시 부르지 말고 잠시 뒤 상태를 확인한 뒤 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다.
PROVIDER_UNAVAILABLE연결 오류 — 고용24 접속에 실패했습니다. 잠시 후 다시 호출합니다.
PROVIDER_OUTCOME_UNCONFIRMED요청을 보낸 뒤의 실패 — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 쓰기 요청이 기관에 나간 뒤에 생긴 실패는 원인(기관의 5xx 나 4xx 응답, 접근 제한, 응답 지연, 연결 끊김)과 관계없이 이 코드로 끝납니다. 처리됐는지 알 수 없으므로 다시 실행하지 말고 history 로 접수번호의 현재 상태를 확인합니다. 위의 접근 제한, 응답 지연, 업스트림 오류, 연결 오류 행은 쓰기 요청이 나가기 전에 생긴 실패(화면을 여는 단계, 연결을 맺지 못함)에 해당합니다. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다.
VALIDATION_SEMANTIC_ERROR파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다.
VALIDATION_INVALID_FIELD사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다.
POLICY_FEATURE_DISABLED쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다.
VALIDATION_MISSING_FIELD확인 누락 — confirm=true 가 없습니다. 이 액션은 고용24 화면에서도 확인 대화상자를 거치는 되돌리기 어려운 요청이라 API 도 명시 확인을 요구합니다.
VALIDATION_MISSING_FIELD행정정보 동의 미지정 — admin_info_sharing_consent(true/false)가 없습니다. 기관 제출 화면이 필수로 요구하는 동의 항목이고 고객이 직접 정할 법적 동의라 XBOSS가 대신 정하지 않습니다. 동의하지 않아도 제출은 되지만, 행정정보로 대체 확인하지 못하는 서류는 직접 첨부해야 할 수 있습니다.
INTERNAL_ERROR첨부 동시 업로드 불가 — attachments 에 값을 채워 보내면 제출 자체를 중단합니다(파일을 기관으로 보내는 기능은 아직 지원하지 않고, 조용히 무시하면 첨부 없이 접수되어 서류 누락 반려로 이어지기 때문입니다). 첨부는 고용24 화면에서 먼저 올린 뒤 draft_validate 로 붙었는지 확인하고 제출합니다. 응답의 error.message 는 '신청이 기관에 전송되기 전에 중단됐습니다. 접수된 내용은 없으니 중복 걱정은 하지 않으셔도 됩니다.' 로 시작하고, 줄을 바꿔 '다음 단계:' 뒤에 이 사유와 다음 행동이 이어집니다. 기관에 반영된 것이 없으므로 같은 요청을 다시 호출해도 중복 처리가 되지 않습니다.
RESOURCE_NOT_FOUND접수번호 화면에서 확인 안 됨 — receipt_no 의 신청서를 제출 화면에서 확인하지 못했습니다(DRAFT_NOT_FOUND).
RESOURCE_CONFLICT미완성 초안 — 첨부서류 목록을 확인하지 못했거나(attachment_list_unresolved) 필수 서류가 비었거나(required_documents_missing) 최초 신청인데 부정수급 방지 영상을 아직 안 봤을 때(fraud_prevention_video_required) 제출을 막습니다(NOT_SUBMITTABLE). draft_validate 로 먼저 무엇이 빠졌는지 확인합니다.
RESOURCE_CONFLICT이미 작성중 아님 — 접수번호가 이미 작성중을 벗어난 상태(제출됨·반려 등)라 제출 대상이 아닙니다(NOT_A_DRAFT). history 로 현재 상태를 확인합니다.

9. 고용24 기업지원금 대상자정보 단계 진입work24.subsidy.application.target_init

MCP 도구 이름 work24__subsidy__application__target_init

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

작성 중인 신청서의 대상자정보 단계를 열고 입력 항목을 확인합니다.

  • workplace_save 로 발급받은 receipt_no 가 있어야 합니다. 고용24 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [고용24 로그인]
  • target_stage 키가 오면(값은 고정 문자열 target_stage_absent) 이 사업엔 대상자정보 단계가 없는 것입니다 - targets: []·message_ko·next_action_hint 가 함께 오고, receipt_no·screen_status·attachment_module·screen_guards·safety 는 오지 않습니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • work24이 API 고정값 (기본값)

예시 : work24

actionstring-Y호출할 작업입니다.
  • work24.subsidy.application.target_init이 API 고정값 (기본값)

예시 : work24.subsidy.application.target_init

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
programme_keystringY카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다

예시 : w24_b0010

business_management_nostringN고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다
receipt_nostringY민원신청접수번호 (2단계 저장이 발급)
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: target_init-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "work24",
  "action": "work24.subsidy.application.target_init",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "programme_key": "w24_b0010",
    "receipt_no": "<필수>"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • result.data 에 target_stage 키가 있으면 이 사업엔 대상자정보 단계가 없는 것이고, 키가 없고 receipt_no 등이 오면 단계가 있는 것입니다(아래 성공 행 참고).
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
programme_keystring지원사업 키
programme_label_kostring | number | boolean | object | array | null지원사업 한글명
business_management_nostring사업장관리번호
target_stagestring이 키가 오면 그 사업에 대상자정보 단계가 없다는 표시입니다(값은 고정 문자열 target_stage_absent). 단계가 있는 사업에서는 이 키 자체가 오지 않습니다
targetsarray지정된 대상자 목록 - target_stage 가 올 때(단계 없음)만 오고 항상 빈 배열입니다
message_kostring대상자정보 단계가 없다는 안내 문구 - target_stage 가 올 때만 옵니다
receipt_nostring이 신청 건의 접수번호 - target_stage 가 오지 않을 때(단계 있음)만 옵니다
screen_statusnumber기관 화면 진행 상태 코드 - target_stage 가 오지 않을 때만 옵니다
attachment_moduleobject첨부서류 모듈 안내 객체 - target_stage 가 오지 않을 때만 옵니다
screen_guardsobject화면 진입 제약 객체 - target_stage 가 오지 않을 때만 옵니다
safetyobject저장(save_executed)·제출(submit_executed) 실행 여부를 나타내는 안전 상태 객체 - target_stage 가 오지 않을 때만 옵니다
next_action_hintstring다음 호출로 이어갈 액션 힌트 - 두 경우 모두 옵니다
actionstring이번에 처리한 액션 이름
stepnumber신청 진행 단계 식별자
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "work24",
    "action": "work24.subsidy.application.target_init",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다.
PROVIDER_IP_REJECTED접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다.
PROVIDER_UNAVAILABLE연결 오류 — 고용24 접속에 실패했습니다. 응답 지연(타임아웃)도 이 코드로 옵니다 - 조회는 재시도해도 안전한 요청이라 재시도 가능으로 표시됩니다. 잠시 후 다시 호출합니다.
VALIDATION_SEMANTIC_ERROR파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다.
VALIDATION_INVALID_FIELD사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다.
VALIDATION_INVALID_FIELD지원사업 키 확인 불가 — programme_key 가 카탈로그에 없거나 아직 이 상품에서 지원하지 않는 사업입니다. 카탈로그 사업 중 신청을 지원하는 것은 일부뿐입니다 - 값을 다시 확인합니다.
POLICY_FEATURE_DISABLED쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다.

10. 고용24 기업지원금 대상자 저장work24.subsidy.application.target_save

MCP 도구 이름 work24__subsidy__application__target_save

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

선택한 근로자를 신청서의 지원 대상으로 지정합니다.

  • target_search 로 조회한 후보 중에서 지정합니다. [고용24 로그인]
  • 이 사업에 대상자정보 단계 자체가 없으면 오류가 아니라 성공 응답으로 오지만, 지정한 대상자 정보는 실제로 저장되지 않습니다.
  • 이때 target_stage 키가 오고(값은 빈 값이 아니라 고정 문자열 target_stage_absent 입니다), targets 는 빈 배열로 오고 message_ko 로 이 단계가 없다는 안내가, next_action_hint 로 다음 단계가 옵니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • work24이 API 고정값 (기본값)

예시 : work24

actionstring-Y호출할 작업입니다.
  • work24.subsidy.application.target_save이 API 고정값 (기본값)

예시 : work24.subsidy.application.target_save

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
programme_keystringY카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다

예시 : w24_b0010

business_management_nostringN고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다
receipt_nostringY민원신청접수번호 (2단계 저장이 발급)
target_irnosarrayYtarget_search 결과의 irno 배열. 순서가 신청서 행 순서가 된다
worker_typestringY근로자유형 코드. P2/P3/P(취업지원프로그램 관련), S(중증장애인), W(여성가장), R(섬지역 거주자). target_search 응답의 selection_options 참조
labor_contractstringY근로계약유형 코드. ACV00(기간의 정함 없음), ACV01(2년 초과), ACV02(1년 이상), ACV03(기타 기간제)
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: target_save-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "work24",
  "action": "work24.subsidy.application.target_save",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "programme_key": "w24_b0010",
    "receipt_no": "<필수>",
    "target_irnos": "<필수: array>",
    "worker_type": "<필수>",
    "labor_contract": "<필수>"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • targets_saved 로 지정된 대상자 수를, targets 로 그 명단(row_summary)을 확인합니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
programme_keystring지원사업 키
programme_label_kostring | number | boolean | object | array | null지원사업 한글명
business_management_nostring사업장관리번호
outcomestring판정 결과 - 대상자정보 단계가 있는 사업에서만 옵니다. 이 칸이 오는 경우는 항상 confirmed 입니다
receipt_nostring이 신청 건의 접수번호 - 대상자정보 단계가 있는 사업에서만 옵니다
targets_savednumber이번에 지정 저장된 대상자 수 - 대상자정보 단계가 있는 사업에서만 옵니다
targetsarray저장된 대상자 요약 목록(row_summary) - 단계가 없으면 빈 배열입니다
request_amount_per_targetnumber | null화면에서 읽은, 대상자 1인당 신청금액 - 대상자정보 단계가 있는 사업에서만 옵니다
target_stagestring이 키가 오면 그 사업에 대상자정보 단계가 없다는 표시입니다(값은 빈 값이 아니라 고정 문자열 target_stage_absent 입니다). 단계가 있는 사업의 정상 응답에는 이 키 자체가 오지 않습니다.
message_kostring안내 문구 - 대상자정보 단계가 없는 사업에서만 옵니다
next_action_hintstring다음 호출로 이어갈 액션 힌트 - draft_validate
actionstring이번에 처리한 액션 이름
stepnumber신청 진행 단계 식별자
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "work24",
    "action": "work24.subsidy.application.target_save",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다.
PROVIDER_IP_REJECTED접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다.
PROVIDER_TIMEOUT_READ응답 지연 — 고용24 응답이 지연됐습니다. 재시도 불가로 표시되므로 바로 다시 부르지 말고 잠시 뒤 상태를 확인한 뒤 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다.
PROVIDER_UNAVAILABLE연결 오류 — 고용24 접속에 실패했습니다. 잠시 후 다시 호출합니다.
VALIDATION_SEMANTIC_ERROR파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다.
VALIDATION_INVALID_FIELD사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다.
POLICY_FEATURE_DISABLED쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다.
INTERNAL_ERROR후보 미확인 — 지정 가능한 피보험자 목록을 먼저 확인하지 못해 저장을 중단했습니다. target_search 를 먼저 호출합니다. 응답의 error.message 는 '신청이 기관에 전송되기 전에 중단됐습니다. 접수된 내용은 없으니 중복 걱정은 하지 않으셔도 됩니다.' 로 시작하고, 줄을 바꿔 '다음 단계:' 뒤에 이 사유와 다음 행동이 이어집니다. 기관에 반영된 것이 없으므로 같은 요청을 다시 호출해도 중복 처리가 되지 않습니다. 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)에서 화면을 옮기는 동안 중간 저장 요청이 이미 나갔다면 이 행이 아니라 아래 「중간 저장 후 중단」 행으로 끝납니다.
INTERNAL_ERROR신청금액 미확인 — 화면에서 신청금액을 읽지 못해 임의로 채우지 않고 중단했습니다. 응답의 error.message 는 '신청이 기관에 전송되기 전에 중단됐습니다. 접수된 내용은 없으니 중복 걱정은 하지 않으셔도 됩니다.' 로 시작하고, 줄을 바꿔 '다음 단계:' 뒤에 이 사유와 다음 행동이 이어집니다. 기관에 반영된 것이 없으므로 같은 요청을 다시 호출해도 중복 처리가 되지 않습니다. 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)에서 화면을 옮기는 동안 중간 저장 요청이 이미 나갔다면 이 행이 아니라 아래 「중간 저장 후 중단」 행으로 끝납니다.
PROVIDER_OUTCOME_UNCONFIRMED중간 저장 후 중단 — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 후보 목록이나 신청금액을 읽지 못해 대상자 저장을 중단했지만, 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)은 그 앞에서 화면을 옮기는 동안 중간 저장 요청이 이미 기관에 나갔습니다. 그래서 위 두 행과 달리 기관에 반영된 것이 없다고 말할 수 없습니다. 다시 실행하지 말고 고용24 [기업지원금 > 참여 사업관리(기존 신청자)] 화면에서 해당 신청서의 저장 내용과 처리상태를 먼저 확인합니다. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다.
PROVIDER_UPSTREAM_ERROR기관이 저장 요청을 거절 — 기관이 대상자 저장 요청 자체를 오류(500)로 거절했습니다. 지정하려는 근로자가 이번 차수에 지정 가능한 대상이 아니면(선택 가능 인원 0명 포함) 기관이 이렇게 거절합니다 - target_search 응답의 selectable 여부를 먼저 확인합니다.
VALIDATION_SEMANTIC_ERROR기관이 사유를 말하며 거절 — 기관이 저장 응답에 사유를 담아 대상자 저장을 받아 주지 않았습니다(TARGET_SAVE_NOT_ACCEPTED). error.message 에 기관이 알려 준 사유가 오고 다음 단계 안내가 함께 옵니다. 사유대로 대상자 선택을 고친 뒤 같은 단계를 다시 저장합니다.
INTERNAL_ERROR저장 실패 — 기관이 저장 결과를 0/빈 값으로 응답했고 사유는 주지 않았습니다. 응답의 error.message 는 이 사유가 아니라 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')로 옵니다.

MCP 도구 이름 work24__subsidy__application__target_search

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

지원 대상으로 지정할 수 있는 사업장 고용보험 피보험자를 조회합니다.

  • workplace_save 로 발급받은 receipt_no 가 있어야 합니다. 고용24 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [고용24 로그인]
  • target_init 과 똑같이 target_stage(고정 문자열 target_stage_absent)·targets: []· message_ko·next_action_hint 만 오고, resolved·candidates 등 아래 8개 필드는 오지 않습니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • work24이 API 고정값 (기본값)

예시 : work24

actionstring-Y호출할 작업입니다.
  • work24.subsidy.application.target_search이 API 고정값 (기본값)

예시 : work24.subsidy.application.target_search

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
programme_keystringY카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다

예시 : w24_b0010

business_management_nostringN고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다
receipt_nostringY민원신청접수번호 (2단계 저장이 발급)
querystringN성명 부분검색. 비우면 사업장 피보험자 전체를 돌려준다
pagenumberN페이지 번호 (1부터)

예시 : 1

page_sizenumberN한 쪽에 받을 대상자 수입니다. 1 이상 100 이하의 정수이고 보내지 않으면 10 입니다

예시 : 10

  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: target_search-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "work24",
  "action": "work24.subsidy.application.target_search",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "programme_key": "w24_b0010",
    "receipt_no": "<필수>",
    "page": 1,
    "page_size": 10
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • result.data 의 candidates 로 지정 가능한 근로자 후보를 확인합니다(대상자정보 단계가 있는 사업만 - 아래 성공 행 참고).
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
programme_keystring지원사업 키
programme_label_kostring | number | boolean | object | array | null지원사업 한글명
business_management_nostring사업장관리번호
target_stagestring이 키가 오면 그 사업에 대상자정보 단계가 없다는 표시입니다(값은 고정 문자열 target_stage_absent). 단계가 있는 사업에서는 이 키 자체가 오지 않습니다
targetsarraytarget_stage 가 올 때(단계 없음)만 오고 항상 빈 배열입니다
message_kostring대상자정보 단계가 없다는 안내 문구 - target_stage 가 올 때만 옵니다
receipt_nostring이 신청 건의 접수번호 - target_stage 가 오지 않을 때(단계 있음)만 옵니다
resolvedboolean후보 조회가 됐는지 여부 - target_stage 가 오지 않을 때만 옵니다. false 면 reason· provider_message_ko 에 안 된 사유가, true 면 count·selectable_count·candidates· how_to_select_ko·why_selectable_matters_ko 에 결과가 담깁니다
reasonstringresolved:false 일 때의 사유 코드(target_list_not_in_response) - resolved:true 면 오지 않습니다
countnumber조회된 후보 총 인원 - resolved:true 일 때만 옵니다
selectable_countnumber그중 이번 차수에 지정 가능한(selectable:true) 인원 - resolved:true 일 때만 옵니다
candidatesarray지정할 수 있는 근로자 후보 목록 - target_stage 가 오지 않을 때만 옵니다
note_kostring조회 결과에 대한 한국어 안내 문구 - target_stage 가 오지 않을 때만 옵니다
provider_message_kostring기관 원문 안내 문구(msgTxt, 최대 300자) - 후보가 0명일 때가 아니라 기관 응답에서 후보 목록 자체를 읽지 못했을 때(resolved:false) 옵니다. 후보가 0명인 것은 정상 응답(resolved:true·count:0)이라 이 필드가 오지 않습니다
how_to_select_kostringtarget_save 호출 방법 안내 문구 - resolved:true 일 때만 옵니다
why_selectable_matters_kostringselectable 판정의 의미(사전진단은 사업장 요건만 본다는 안내) - resolved:true 일 때만 옵니다
selection_optionsobject지정 시 선택할 수 있는 옵션 객체 - worker_type · labor_contract - target_stage 가 오지 않을 때만 옵니다
required_for_save_kostring대상자 저장(target_save)에 필요한 값을 안내하는 문구 - target_stage 가 오지 않을 때만 옵니다
safetyobject저장·제출 실행 여부를 나타내는 안전 상태 객체 - target_stage 가 오지 않을 때만 옵니다
next_action_hintstring다음 호출로 이어갈 액션 힌트 - target_stage 가 올 때만 옵니다
actionstring이번에 처리한 액션 이름
stepnumber신청 진행 단계 식별자
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "work24",
    "action": "work24.subsidy.application.target_search",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다.
PROVIDER_IP_REJECTED접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다.
PROVIDER_UNAVAILABLE연결 오류 — 고용24 접속에 실패했습니다. 응답 지연(타임아웃)도 이 코드로 옵니다 - 조회는 재시도해도 안전한 요청이라 재시도 가능으로 표시됩니다. 잠시 후 다시 호출합니다.
VALIDATION_SEMANTIC_ERROR파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다.
VALIDATION_INVALID_FIELD사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다.
VALIDATION_INVALID_FIELD지원사업 키 확인 불가 — programme_key 가 카탈로그에 없거나 아직 이 상품에서 지원하지 않는 사업입니다. 카탈로그 사업 중 신청을 지원하는 것은 일부뿐입니다 - 값을 다시 확인합니다.
POLICY_FEATURE_DISABLED쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다.

12. 고용24 기업지원금 신청 철회work24.subsidy.application.withdraw

MCP 도구 이름 work24__subsidy__application__withdraw

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

제출한 지원금 신청을 정식 절차로 철회하고 처리 결과를 확인합니다.

  • 제출이 완료된 신청서만 대상입니다(작성중 초안은 delete 로 지웁니다). confirm=true 를 함께 보냅니다. 이 상품의 신청서 쓰기 기능이 정책으로 켜져 있어야 합니다. [고용24 로그인]
  • 요청 거절(HTTP 400, 작업은 만들어지지 않음).
  • 요청 거절(HTTP 409, 작업은 만들어지지 않음).

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • work24이 API 고정값 (기본값)

예시 : work24

actionstring-Y호출할 작업입니다.
  • work24.subsidy.application.withdraw이 API 고정값 (기본값)

예시 : work24.subsidy.application.withdraw

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
programme_keystringY카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다

예시 : w24_b0010

business_management_nostringN고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다
receipt_nostringY민원신청접수번호 (2단계 저장이 발급)
confirmbooleanY실제로 신청을 철회(반려 요청)한다는 확인값입니다. 빠지거나 true 로 읽히지 않는 값이면 기관에 아무것도 보내지 않고 확인이 필요하다는 오류로 끝납니다. 이 칸만으로는 실행되지 않습니다. 첫 요청은 작업을 만들지 않고 HTTP 400 WRITE_CONFIRMATION_REQUIRED 와 error.confirmation_token 을 돌려주므로, 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 이 칸은 첫 요청부터 true 로 넣습니다. 토큰을 받은 뒤에 더하면 본문이 달라져 토큰이 맞지 않습니다
confirmation_tokenstringN1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: withdraw-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "work24",
  "action": "work24.subsidy.application.withdraw",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "programme_key": "w24_b0010",
    "receipt_no": "<필수>",
    "confirm": "<필수: boolean>"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • 반려요청 처리 결과(resultMap.result)가 0보다 크면 withdrawn:true 로 확정됩니다(outcome=confirmed).
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
programme_keystring지원사업 키
programme_label_kostring | number | boolean | object | array | null지원사업 한글명
business_management_nostring사업장관리번호
receipt_nostring철회한 신청 건의 접수번호
outcomestring판정 결과 - 이 표가 오는 경우는 항상 confirmed 입니다
withdrawnboolean철회 확정 여부 - 이 표가 오는 경우는 항상 true 입니다(실패와 확인 안 됨은 작업이 FAILED 로 끝나 이 표가 오지 않습니다)
acknowledgementobject명시 확인 처리 결과 객체 - confirm·confirm_message_ko·confirm_message_measured 를 담고, 행정정보 동의가 필요한 액션(submit·modify)은 admin_info_sharing_consent 등도 함께 옵니다
actionstring이번에 처리한 액션 이름
stepnull신청 진행 단계 식별자 - 이 액션은 신청 단계 밖이라 항상 null 입니다
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "work24",
    "action": "work24.subsidy.application.withdraw",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
PROVIDER_OUTCOME_UNCONFIRMED성공도 실패도 아님(미확인) — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 반려요청 응답 본문을 읽지 못했거나 처리 결과(resultMap.result)가 없거나 숫자가 아닐 때입니다. 다시 철회하지 말고 고용24 화면이나 history 로 접수번호의 처리상태를 확인합니다. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다.
AUTH_REQUIRED세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다.
PROVIDER_IP_REJECTED접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다.
PROVIDER_TIMEOUT_READ응답 지연 — 고용24 응답이 지연됐습니다. 재시도 불가로 표시되므로 바로 다시 부르지 말고 잠시 뒤 상태를 확인한 뒤 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다.
PROVIDER_UNAVAILABLE연결 오류 — 고용24 접속에 실패했습니다. 잠시 후 다시 호출합니다.
PROVIDER_OUTCOME_UNCONFIRMED요청을 보낸 뒤의 실패 — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 쓰기 요청이 기관에 나간 뒤에 생긴 실패는 원인(기관의 5xx 나 4xx 응답, 접근 제한, 응답 지연, 연결 끊김)과 관계없이 이 코드로 끝납니다. 처리됐는지 알 수 없으므로 다시 실행하지 말고 history 로 접수번호의 현재 상태를 확인합니다. 위의 접근 제한, 응답 지연, 업스트림 오류, 연결 오류 행은 쓰기 요청이 나가기 전에 생긴 실패(화면을 여는 단계, 연결을 맺지 못함)에 해당합니다. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다.
VALIDATION_SEMANTIC_ERROR파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다.
VALIDATION_INVALID_FIELD사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다.
POLICY_FEATURE_DISABLED쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다.
VALIDATION_MISSING_FIELD확인 누락 — confirm=true 가 없습니다. 이 액션은 고용24 화면에서도 확인 대화상자를 거치는 되돌리기 어려운 요청이라 API 도 명시 확인을 요구합니다.
RESOURCE_CONFLICT철회 값 확인 불가 — 철회에 필요한 기관 부여 값(issn 등)을 화면에서 확인하지 못했습니다(WITHDRAW_KEYS_MISSING). 제출이 완료된 신청서가 맞는지 먼저 확인합니다 - 작성중 초안은 delete 로 지웁니다.
INTERNAL_ERROR철회 실패 — 기관이 처리 결과를 0 이하로 응답했습니다. 응답의 error.message 는 이 사유가 아니라 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')로 옵니다.

13. 고용24 기업지원금 사업장정보 저장work24.subsidy.application.workplace_save

MCP 도구 이름 work24__subsidy__application__workplace_save

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

신청서에 사업장정보를 저장하고 접수번호를 받습니다.

  • 고용24 세션 로그인 후 init 으로 신청 가능 여부를, requirements 로 필요한 입력을 먼저 확인합니다. [고용24 로그인]

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • work24이 API 고정값 (기본값)

예시 : work24

actionstring-Y호출할 작업입니다.
  • work24.subsidy.application.workplace_save이 API 고정값 (기본값)

예시 : work24.subsidy.application.workplace_save

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
programme_keystringY카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다

예시 : w24_b0010

business_management_nostringN고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다
applicant_zipstringN신청인 우편번호
applicant_base_addressstringN신청인 기본주소
applicant_detail_addressstringN신청인 상세주소
manager_namestringN담당자 성명
manager_phone1stringN담당자 일반전화 앞자리
manager_phone2stringN담당자 일반전화 뒷자리
manager_mobile1stringN담당자 휴대전화 앞자리
manager_mobile2stringN담당자 휴대전화 뒷자리
manager_emailstringN담당자 이메일

예시 : manager@example.com

payment_bank_namestringN지급계좌 은행명
payment_account_nostringN지급계좌 계좌번호
payment_account_holderstringN지급계좌 예금주 (기관 필수 아님)
receipt_nostringN기존 초안을 이어서 저장할 때만 지정한다. 비우면 신규 초안
application_yearnumberN신청 귀속연도. requirements 의 options 가 있으면 그 값 중 하나
application_quarternumberN신청 차수. requirements 의 options 값 중 하나(분기 1 또는 월 9 등). 숫자로 보내면 화면 값('09' 등)으로 맞춰 넣는다
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: workplace_save-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "work24",
  "action": "work24.subsidy.application.workplace_save",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "programme_key": "w24_b0010",
    "manager_email": "manager@example.com"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • receipt_no 로 접수번호를 발급받습니다. 이 호출부터 신청서가 기관에 실제로 남는 첫 되돌릴 수 없는 단계입니다(조회와 다릅니다).
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
programme_keystring지원사업 키
programme_label_kostring | number | boolean | object | array | null지원사업 한글명
business_management_nostring사업장관리번호
outcomestring판정 결과 - 이 응답이 오는 경우는 항상 confirmed 입니다(접수번호가 발급되지 않으면 오류로 끝납니다)
receipt_nostring새로 발급됐거나 이어서 쓴 접수번호 - 이후 모든 단계가 이 값을 씁니다
draft_status_codestring저장 직후의 작성중 상태 코드
next_action_hintstring다음 호출로 이어갈 액션 힌트 - target_init
actionstring이번에 처리한 액션 이름
stepnumber신청 진행 단계 식별자
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "work24",
    "action": "work24.subsidy.application.workplace_save",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다.
PROVIDER_IP_REJECTED접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다.
PROVIDER_TIMEOUT_READ응답 지연 — 고용24 응답이 지연됐습니다. 재시도 불가로 표시되므로 바로 다시 부르지 말고 잠시 뒤 상태를 확인한 뒤 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다.
PROVIDER_UNAVAILABLE연결 오류 — 고용24 접속에 실패했습니다. 잠시 후 다시 호출합니다.
VALIDATION_SEMANTIC_ERROR파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다.
VALIDATION_INVALID_FIELD사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다.
POLICY_FEATURE_DISABLED쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다.
RESOURCE_CONFLICT사전진단 불통과 — 사업주 사전진단을 통과하지 못해 신청할 수 없습니다(DIAGNOSIS_BLOCKS). init 또는 diagnosis.search 로 사유를 먼저 확인합니다.
RESOURCE_NOT_FOUND이어쓰기 대상 없음 — receipt_no 로 지정한 작성중 신청서를 사업장정보 화면에서 찾지 못했습니다(DRAFT_NOT_FOUND). 이 상태로 저장하면 새 초안이 생기므로 중단합니다 - history 로 확인 후 다시 시도합니다.
RESOURCE_CONFLICT중복 신청 방지 — receipt_no 를 생략했는데 같은 사업장·서식·귀속연도로 이미 신청한 이력이 있으면(PRIOR_APPLICATION_EXISTS) 또는 그 확인 자체가 안 되면(WORK24_SUBSIDY_APPLICATION_IDEMPOTENCY_UNVERIFIED) 중복 신청을 막기 위해 저장을 중단합니다. 이어서 작성하려면 안내된 접수번호를 receipt_no 로 함께 보냅니다.
VALIDATION_SEMANTIC_ERROR필수 입력 누락 — 화면에도 기관이 채워 주는 값도 없는 필수 항목이 있습니다(REQUIRED_FIELDS_MISSING). requirements 로 무엇이 필요한지 먼저 확인합니다.
VALIDATION_SEMANTIC_ERROR계좌 거절 — 기관이 등록한 지급계좌를 문제 삼아 접수번호를 발급하지 않았습니다(ACCOUNT_REJECTED). 계좌를 다시 등록·확인한 뒤 다시 시도합니다.
VALIDATION_SEMANTIC_ERROR사업장 저장 거절 — 기관이 사유를 말하며 사업장 저장을 받아 주지 않았습니다(WORKPLACE_REJECTED). error.message 에 기관이 알려 준 사유가 오고 다음 단계 안내가 함께 옵니다. 사유대로 사업장 정보를 고친 뒤 같은 단계를 다시 저장합니다.
INTERNAL_ERROR접수번호 미발급 — 기관이 접수번호도 사유도 주지 않아 결과를 알 수 없습니다. 재시도보다 문의를 권합니다. 응답의 error.message 는 이 사유가 아니라 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')로 옵니다.
VALIDATION_SEMANTIC_ERROR선택값 오류 — 귀속연도·차수 같은 코드값 필드에 화면이 허용하지 않는 값을 보냈습니다(CHOICE_INVALID). 오류 메시지가 그 필드의 실제 허용값 목록을 함께 알려줍니다 - requirements 의 field_options 로도 미리 확인할 수 있습니다.

MCP 도구 이름 work24__subsidy__diagnosis__search

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

사업장 하나에 대해 사전진단이 있는 기업지원금 사업을 한 번에 조회해 사업별 적합 여부를 돌려줍니다.

  • 고용24 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [고용24 로그인]
  • 기관 조회가 실패한 사업은 작업 오류가 아니라 results[] 안에서 verdict:"undetermined" · can_apply:false · error 로 표시됩니다(다른 사업 결과는 그대로 옵니다).

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • work24이 API 고정값 (기본값)

예시 : work24

actionstring-Y호출할 작업입니다.
  • work24.subsidy.diagnosis.search이 API 고정값 (기본값)

예시 : work24.subsidy.diagnosis.search

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
application_yearnumber4N신청연도. 입력하지 않으면 올해입니다

형식 : YYYY

business_management_nostring-N고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다
programme_keysarray-N진단할 지원금 사업 키 목록(예: w24_b0010). 입력하지 않으면 사전진단이 있는 모든 사업을 진단합니다
output_formatsarray-N이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: search-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "work24",
  "action": "work24.subsidy.diagnosis.search",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • result.data 의 summary · results 로 사업별 신청 가능 여부를 확인합니다.
  • 아래 표의 results[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 엑셀 파일 맨 윗줄의 머리글입니다.
  • 아래 표의 줄은 엑셀로 내보내는 열이라 응답 행의 칸 전부가 아닐 수 있습니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
schemastring내부 스키마 식별자(고객 응답에 그대로 포함되는 값입니다)
business_management_nostring사업장관리번호
application_yearstring진단 기준 연도
catalog_measured_onstring지원사업 카탈로그 확인 기준일
programme_countnumber진단한 지원사업 수
summaryobject판정 건수 요약 객체 - applicable(신청가능) · eligible(적격) · conditional(조건부) · ineligible(부적격) · undetermined(미확정) 각각의 사업 수
applicable_programme_keysarray신청 가능한 사업 키 목록
eligible_programme_keysarray적격 판정을 받은 사업 키 목록
applicable_and_automatable_keysarray신청 가능하면서 이 API 로 신청 자동화까지 되는 사업 키 목록 - 다음 단계로 바로 갈 수 있는 사업입니다
resultsarray사업별 진단 결과 목록 - 각 행은 programme_key · programme_label_ko · category · automation(자동화 가능 여부) 과, 판정 상세(can_apply · message_ko · items 배열 - 항목별 충족 여부 · 근거 법령)를 담습니다
results[].bzmnstring사업장관리번호
results[].programme_label_kostring | number | boolean | object | array | null지원사업
results[].categorystring | number | boolean | object | array | null분류 (값: new_hire = 신규채용, maternity_childcare = 출산 육아, reduced_flexible_hours = 단축 유연근무, employment_retention = 고용유지, conversion_transition = 정규직 산업 일자리전환)
results[].verdictstring판정 (값: eligible = 적격, conditional = 조건부, ineligible = 부적격, undetermined = 미확정)
results[].can_applyboolean신청 가능 여부 (값: true = 가능, false = 불가)
results[].message_kostring안내 문구
results[].automation.label_kostring자동화 가능 여부
warnings_koarray진단 전반에 대한 한국어 경고 문구 목록
automation_ledgerarray진단 대상이 아닌 사업까지 포함한 전체 자동화 지원 범위 장부
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "work24",
    "action": "work24.subsidy.diagnosis.search",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다.
VALIDATION_INVALID_FIELD사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다.
VALIDATION_INVALID_FIELD지원사업 키 확인 불가 — programme_keys 로 보낸 사업 키 중 카탈로그에 없거나 아직 지원하지 않는 것이 있습니다. 값을 다시 확인합니다(생략하면 카탈로그 전체를 진단하므로 이 행은 값을 보낼 때만 해당합니다).