기업지원금 - 고용24
1. 고용24 기업지원금 첨부 파일 삭제work24. subsidy. application. attachment_ delete
MCP 도구 이름 work24__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
작성중인 신청 초안에 잘못 붙인 첨부 파일 한 건을 삭제합니다.
- 작성중인 신청서의 첨부만 지울 수 있습니다. [고용24 로그인]지울 파일의 file_id 는 draft_validate 응답의 documents.documents[].attached_files[].file_id 에서 확인합니다. confirm=true 를 함께 보냅니다.이 상품의 신청서 쓰기 기능이 정책으로 켜져 있어야 합니다.
- 삭제 요청 뒤 첨부서류 목록을 되읽어 그 파일(file_id)이 사라진 것을 확인하면 확정됩니다(outcome=confirmed).지운 파일 번호(deleted_file_id)와 삭제 뒤의 첨부서류 목록(documents)을 함께 돌려줍니다.
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 기관에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이 함께 옵니다(error.preview 도 오지만 이 액션에서는 비어 있습니다).안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm=true 는 첫 요청부터 넣습니다. 토큰을 받은 뒤에 더하면 본문이 달라져 확인 토큰 불일치로 끝나고, 빼고 보내면 토큰은 쓰이고 작업이 「확인 누락」 으로 끝납니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 기관에 아무것도 보내지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| programme_ | string | Y | 카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다 | |
| business_ | string | N | 고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다 | |
| receipt_ | string | Y | 민원신청접수번호 (2단계 저장이 발급) | |
| confirm | boolean | Y | 실제로 첨부 파일을 삭제한다는 확인값입니다. 빠지거나 true 로 읽히지 않는 값이면 기관에 아무것도 보내지 않고 확인이 필요하다는 오류로 끝납니다. 이 칸만으로는 실행되지 않습니다. 첫 요청은 작업을 만들지 않고 HTTP 400 WRITE_CONFIRMATION_REQUIRED 와 error.confirmation_token 을 돌려주므로, 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 이 칸은 첫 요청부터 true 로 넣습니다. 토큰을 받은 뒤에 더하면 본문이 달라져 토큰이 맞지 않습니다 | |
| file_ | string | Y | draft_validate 의 documents[].attached_files[].file_id | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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 한 줄만 옵니다.아래는 outcome=confirmed 일 때만 유효합니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| programme_ | string | 지원사업 키 | |
| programme_ | string | number | boolean | object | array | null | 지원사업 한글명 | |
| business_ | string | 사업장관리번호 | |
| receipt_ | string | 첨부를 지운 신청 건의 접수번호 | |
| outcome | string | 판정 결과 - 이 표가 오는 경우는 항상 confirmed 입니다 | |
| deleted_ | string | 지운 첨부 파일의 번호 - 요청에 보낸 file_id 와 같은 값입니다 | |
| documents | object | 삭제 뒤 첨부서류 목록 조회 결과 객체 - draft_validate 의 documents 와 같은 모양입니다(resolved, documents 목록 등) | |
| verdict_ | object | 확정 시 판정 근거 객체 - 삭제 요청에 대한 기관 응답 관찰값(http_status 등), 삭제 뒤 그 파일이 남았는지(file_still_attached), 삭제 전후의 서류에 맞지 않는 파일 수와 기관 저장소에서 사라진 파일 수를 담습니다 | |
| acknowledgement | object | 명시 확인 처리 결과 객체 - confirm·confirm_message_ko·confirm_message_measured 를 담고, 행정정보 동의가 필요한 액션(submit·modify)은 admin_info_sharing_consent 등도 함께 옵니다 | |
| action | string | 이번에 처리한 액션 이름 | |
| step | number | 신청 진행 단계 식별자 |
{
"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_ | 성공도 실패도 아님(미확인) — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 삭제 요청은 나갔지만 삭제 뒤 목록을 되읽지 못했거나, 되읽은 목록에 그 파일이 아직 있거나, 기관 응답이 성공이 아니었습니다. 다시 삭제를 시도하지 말고 draft_validate 로 첨부서류 목록을 확인합니다. 파일이 아직 보이면 고용24 [기업지원금 > 신청] 화면에서 직접 지웁니다. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다. | |
| AUTH_ | 세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다. | |
| PROVIDER_ | 접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다. | |
| PROVIDER_ | 응답 지연 — 고용24 응답이 지연됐습니다. 재시도 불가로 표시되므로 바로 다시 부르지 말고 잠시 뒤 상태를 확인한 뒤 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다. | |
| PROVIDER_ | 연결 오류 — 고용24 접속에 실패했습니다. 잠시 후 다시 호출합니다. | |
| VALIDATION_ | 파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다. | |
| VALIDATION_ | 사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다. | |
| POLICY_ | 쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다. | |
| VALIDATION_ | 확인 누락 — confirm=true 가 없습니다. 파일을 지우는 되돌리기 어려운 요청이라 API 가 명시 확인을 요구합니다(이 확인은 고용24 화면의 확인창을 옮긴 것이 아니라 XBOSS 가 정한 확인입니다). | |
| RESOURCE_ | 접수번호 미확인 — receipt_no 의 신청서를 첨부 화면에서 확인하지 못했습니다(DRAFT_NOT_FOUND). | |
| RESOURCE_ | 파일 번호 없음 — 이 접수번호에 file_id 인 파일이 붙어 있지 않습니다(ATTACHMENT_NOT_FOUND). draft_validate 응답의 documents.documents[].attached_files[].file_id 에서 다시 확인합니다. | |
| RESOURCE_ | 첨부서류 목록 확인 불가 — 이 신청서의 첨부서류 목록을 확인하지 못해 멈췄습니다(ATTACHMENT_LIST_UNRESOLVED). 첨부 영역이 아직 확인하지 못한 방식이라 멈추는 경우(ATTACHMENT_MODULE_UNSUPPORTED)도 같은 코드이고, 그때는 고용24 [기업지원금 > 신청] 화면에서 직접 지웁니다. 삭제 요청은 보내지 않았습니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)은 신청서 화면을 여는 과정의 저장이 이미 반영됐을 수 있습니다. draft_validate 로 첨부서류 목록이 보이는지 먼저 확인합니다. | |
| RESOURCE_ | 첨부를 바꿀 수 없는 상태 — 첨부는 작성중인 신청서에서만 바꿉니다. 처리상태를 확인하지 못했거나(ATTACHMENT_STATE_UNVERIFIED), 작성중이 아니거나(ATTACHMENT_NOT_EDITABLE), 보완요청 상태라 첨부를 저장하면 보완 제출이 되는 경우(ATTACHMENT_ON_SUPPLEMENT_UNSUPPORTED)에 삭제 전에 멈춥니다. 삭제 요청은 보내지 않았습니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)은 신청서 화면을 여는 과정의 저장이 이미 반영됐을 수 있습니다. 보완요청 상태의 첨부는 고용24 화면에서 직접 보완합니다. |
2. 고용24 기업지원금 작성중 초안 삭제work24. subsidy. application. delete
MCP 도구 이름 work24__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
아직 제출하지 않은 신청 초안을 삭제합니다.
- 작성중 초안만 지울 수 있습니다(제출된 신청서는 withdraw 로 철회합니다). confirm=true 를 함께 보냅니다. 이 상품의 신청서 쓰기 기능이 정책으로 켜져 있어야 합니다. [고용24 로그인]
- 삭제 전후 이력을 되읽어 실제로 사라진 것을 확인하면 deleted:true 로 확정됩니다(outcome=confirmed).
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 기관에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이 함께 옵니다(error.preview 도 오지만 이 액션에서는 비어 있습니다).안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm=true 는 첫 요청부터 넣습니다. 토큰을 받은 뒤에 더하면 본문이 달라져 확인 토큰 불일치로 끝나고, 빼고 보내면 토큰은 쓰이고 작업이 「확인 누락」 으로 끝납니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 기관에 아무것도 보내지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| programme_ | string | Y | 카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다 | |
| business_ | string | N | 고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다 | |
| receipt_ | string | Y | 민원신청접수번호 (2단계 저장이 발급) | |
| confirm | boolean | Y | 실제로 신청서를 삭제한다는 확인값입니다. 빠지거나 true 로 읽히지 않는 값이면 기관에 아무것도 보내지 않고 확인이 필요하다는 오류로 끝납니다. 이 칸만으로는 실행되지 않습니다. 첫 요청은 작업을 만들지 않고 HTTP 400 WRITE_CONFIRMATION_REQUIRED 와 error.confirmation_token 을 돌려주므로, 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 이 칸은 첫 요청부터 true 로 넣습니다. 토큰을 받은 뒤에 더하면 본문이 달라져 토큰이 맞지 않습니다 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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 한 줄만 옵니다.아래는 outcome=confirmed 일 때만 유효합니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| programme_ | string | 지원사업 키 | |
| programme_ | string | number | boolean | object | array | null | 지원사업 한글명 | |
| business_ | string | 사업장관리번호 | |
| receipt_ | string | 삭제를 시도한 접수번호 | |
| outcome | string | 판정 결과 - 이 표가 오는 경우는 항상 confirmed 입니다 | |
| deleted | boolean | 삭제 확정 여부 - 이 표가 오는 경우는 항상 true 입니다 | |
| verdict_ | object | 확정 시 판정 근거 객체 - 삭제 전/후 이력 조회 결과를 대조한 값입니다 | |
| provider_ | number | 기관 응답 HTTP 상태 코드(증거 기록용) | |
| prss_ | string | 기관에 보낸 처리 모드 코드(삭제 DELT) | |
| acknowledgement | object | 명시 확인 처리 결과 객체 - confirm·confirm_message_ko·confirm_message_measured 를 담고, 행정정보 동의가 필요한 액션(submit·modify)은 admin_info_sharing_consent 등도 함께 옵니다 | |
| action | string | 이번에 처리한 액션 이름 | |
| step | null | 신청 진행 단계 식별자 - 이 액션은 신청 단계 밖이라 항상 null 입니다 |
{
"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_ | 성공도 실패도 아님(미확인) — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 세 경우 중 하나입니다 - ① 이 사업의 이력 화면을 아직 충분히 지원하지 못해 삭제 전에도 목록에서 존재를 확인하지 못했거나(그래서 삭제 후 '없다'도 증거가 못 됨), ② 삭제 전·후 이력 조회 자체가 실패했거나, ③ 삭제 요청을 보낸 뒤에 실패가 생겼습니다(아래 「요청을 보낸 뒤의 실패」 행). deleted:false 로 확인 안 됨을 알립니다. 다시 삭제를 시도하지 말고 고용24 화면에서 직접 확인합니다. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다. | |
| AUTH_ | 세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다. | |
| PROVIDER_ | 접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다. | |
| PROVIDER_ | 응답 지연 — 고용24 응답이 지연됐습니다. 재시도 불가로 표시되므로 바로 다시 부르지 말고 잠시 뒤 상태를 확인한 뒤 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다. | |
| PROVIDER_ | 연결 오류 — 고용24 접속에 실패했습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 요청을 보낸 뒤의 실패 — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 쓰기 요청이 기관에 나간 뒤에 생긴 실패는 원인(기관의 5xx 나 4xx 응답, 접근 제한, 응답 지연, 연결 끊김)과 관계없이 이 코드로 끝납니다. 처리됐는지 알 수 없으므로 다시 실행하지 말고 history 로 접수번호의 현재 상태를 확인합니다. 위의 접근 제한, 응답 지연, 업스트림 오류, 연결 오류 행은 쓰기 요청이 나가기 전에 생긴 실패(화면을 여는 단계, 연결을 맺지 못함)에 해당합니다. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다. | |
| VALIDATION_ | 파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다. | |
| VALIDATION_ | 사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다. | |
| POLICY_ | 쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다. | |
| VALIDATION_ | 확인 누락 — confirm=true 가 없습니다. 이 액션은 고용24 화면에서도 확인 대화상자를 거치는 되돌리기 어려운 요청이라 API 도 명시 확인을 요구합니다. | |
| RESOURCE_ | 접수번호 미확인 — receipt_no 의 초안을 화면에서 확인하지 못했습니다(DRAFT_NOT_FOUND). | |
| RESOURCE_ | 삭제 실패(남아있음) — 삭제 요청 뒤에도 접수번호가 신청 이력에 남아 있습니다(DELETE_FAILED). 이력을 되읽어 확인한 결과라 결과 모름이 아니라 삭제되지 않은 것이 확인된 상태입니다. 고용24 화면에서 직접 삭제해야 하며, error.message 에 그 화면 위치를 알리는 다음 단계 안내가 함께 옵니다. |
3. 고용24 기업지원금 제출 전 확인work24. subsidy. application. draft_ validate
MCP 도구 이름 work24__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
작성한 신청서를 제출 전에 점검하고 첨부서류 목록을 받습니다.
- workplace_save 로 발급받은 receipt_no 가 있어야 합니다. 고용24 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [고용24 로그인]
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| programme_ | string | Y | 카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다 | |
| business_ | string | N | 고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다 | |
| receipt_ | string | Y | 민원신청접수번호 (2단계 저장이 발급) |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| programme_ | string | 지원사업 키 | |
| programme_ | string | number | boolean | object | array | null | 지원사업 한글명 | |
| business_ | string | 사업장관리번호 | |
| receipt_ | string | 이 신청 건의 접수번호 | |
| screen_ | number | 기관 화면 진행 상태 코드 | |
| attachment_ | object | 첨부서류 모듈 안내 객체 | |
| documents | object | 첨부서류 목록 조회 결과 객체 - resolved · documents(목록) · document_count · mandatory_count · missing_required_documents 등을 담습니다 | |
| missing_ | array | 빠진 필수 첨부서류 목록 | |
| fraud_ | object | null | 부정수급 방지 교육 영상 시청 확인 객체 | |
| safety | object | 저장·제출 실행 여부를 나타내는 안전 상태 객체 | |
| workflow_ | object | 제출 가능 여부 객체 - can_submit 과, 막혀 있으면 그 사유(blocked_reason_ko) | |
| normalized_ | object | 지금까지 입력한 값을 표준화한 객체 | |
| draft_ | object | 제출 전 신청서 미리보기 객체 | |
| field_ | object | 입력값과 기관 화면 필드의 대응 관계 객체 | |
| required_ | array | 필수 입력 필드 이름 목록 | |
| missing_ | array | 빠진 필수 입력 필드 이름 목록 | |
| field_ | array | 필드별 오류 목록 - 정상이면 항상 빈 배열입니다 | |
| warnings | array | 제출 전 참고할 경고 목록 | |
| screen_ | array | 기관 화면이 보여주는 참고 문구 목록 | |
| followup_ | array | 이어서 호출할 수 있는 후속 액션 목록 | |
| action | string | 이번에 처리한 액션 이름 | |
| step | number | 신청 진행 단계 식별자 |
{
"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_ | 세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다. | |
| PROVIDER_ | 접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다. | |
| PROVIDER_ | 업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다. | |
| PROVIDER_ | 연결 오류 — 고용24 접속에 실패했습니다. 응답 지연(타임아웃)도 이 코드로 옵니다 - 조회는 재시도해도 안전한 요청이라 재시도 가능으로 표시됩니다. 잠시 후 다시 호출합니다. | |
| VALIDATION_ | 파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다. | |
| VALIDATION_ | 사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다. | |
| VALIDATION_ | 지원사업 키 확인 불가 — programme_key 가 카탈로그에 없거나 아직 이 상품에서 지원하지 않는 사업입니다. 카탈로그 사업 중 신청을 지원하는 것은 일부뿐입니다 - 값을 다시 확인합니다. | |
| POLICY_ | 쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다. |
4. 고용24 기업지원금 신청 이력 조회work24. subsidy. application. history
MCP 도구 이름 work24__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
지금까지 신청한 지원금 건과 처리 상태를 조회합니다.
- 고용24 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [고용24 로그인]
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| programme_ | string | - | Y | 카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다 | |
| business_ | string | - | N | 고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다 | |
| date_ | string | 8 | N | 조회 시작일. date_to 와 함께 입력하거나 둘 다 비웁니다. 둘 다 비우면 오늘(한국 시간)까지 최근 30일을 조회합니다 | |
| date_ | string | 8 | N | 조회 종료일. date_from 과 함께 입력하거나 둘 다 비웁니다 | |
| output_ | array | - | N | 이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다 |
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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| programme_ | string | 지원사업 키 | |
| programme_ | string | number | boolean | object | array | null | 지원사업 한글명 | |
| business_ | string | 사업장관리번호 | |
| date_ | string | 조회 시작일 | |
| date_ | string | 조회 종료일 | |
| row_ | number | 조회된 신청 건수 | |
| rows | array | 신청 이력 목록 - 건별 접수번호와 처리 상태를 담습니다 | |
| rows[]. | string | number | boolean | object | array | null | 접수번호 | |
| rows[]. | string | number | boolean | object | array | null | 신청 일자 | |
| rows[]. | string | number | boolean | object | array | null | 처리 상태 (값: AGC0B = 작성중, AGC0D = 처리중, AGC0E = 보완요청, AGC0F = 반려, AGC0G = 처리완료, AGC0K = 결재완료, AGC0H = 접수취소, AGC0M = 변경승인) | |
| rows[]. | string | number | boolean | object | array | null | 신청 귀속연도 | |
| rows[]. | string | number | boolean | object | array | null | 신청 순번 | |
| rows[]. | string | number | boolean | object | array | null | 민원서식코드 | |
| rows[]. | string | number | boolean | object | array | null | 조회한 지원사업의 서비스 코드입니다. 이 값으로 목록을 거르므로 모든 행의 값이 같습니다. | |
| rows[]. | string | number | boolean | object | array | null | 이 행의 status_code 에 해당하는 한글 처리 상태입니다. 응답 최상위 status_code_labels_ko 의 같은 항목이며, 그 표에 없는 코드이면 null 입니다. | |
| status_ | string | number | boolean | object | array | null | 처리 상태 코드별 한글 라벨 객체 | |
| note_ | string | 조회 결과에 대한 한국어 안내 문구 | |
| action | string | 이번에 처리한 액션 이름 | |
| step | null | 신청 진행 단계 식별자 - 이 액션은 신청 단계 밖이라 항상 null 입니다 |
{
"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_ | 세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다. | |
| PROVIDER_ | 접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다. | |
| PROVIDER_ | 업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다. | |
| PROVIDER_ | 연결 오류 — 고용24 접속에 실패했습니다. 응답 지연(타임아웃)도 이 코드로 옵니다 - 조회는 재시도해도 안전한 요청이라 재시도 가능으로 표시됩니다. 잠시 후 다시 호출합니다. | |
| VALIDATION_ | 파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다. | |
| VALIDATION_ | 사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다. | |
| VALIDATION_ | 지원사업 키 확인 불가 — programme_key 가 카탈로그에 없거나 아직 이 상품에서 지원하지 않는 사업입니다. 카탈로그 사업 중 신청을 지원하는 것은 일부뿐입니다 - 값을 다시 확인합니다. | |
| INTERNAL_ | 그 밖의 오류 — 화면 경로를 해석하지 못했거나, 이 화면에서 사업자 식별 정보를 확인하지 못했거나, 응답에 이력 목록 자체가 없거나, 이 사업의 이력 화면을 아직 지원하지 않는 경우입니다. 응답의 error.message 는 이 사유가 아니라 일반 안내('서버 내부 오류로 작업을 마치지 못했습니다. 서비스문의로 알려 주세요.')로 옵니다. |
5. 고용24 기업지원금 신청 진입work24. subsidy. application. init
MCP 도구 이름 work24__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
지원사업 신청을 시작하고 우리 사업장이 신청할 수 있는지 확인합니다.
- 고용24 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [고용24 로그인]
- 사전진단이 있는 사업에서 그 진단 조회가 기관 쪽에서 실패해도 작업 오류가 아니라 diagnosis 안에 verdict:"undetermined"·error 가 담기고 최상위 can_apply 는 false 로 옵니다.접속 실패·시간 초과·5xx 가 전부 이 형태로 흡수됩니다. 사전진단이 없는 사업은 애초에 기관을 호출하지 않아 이 변형이 없습니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| programme_ | string | Y | 카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다 | |
| business_ | string | N | 고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다 | |
| application_ | number | N | 신청 귀속연도입니다. options 가 있으면 그 value 중 하나를 입력해 주세요(예: 2026) |
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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| programme_ | string | 지원사업 키 | |
| programme_ | string | number | boolean | object | array | null | 지원사업 한글명 | |
| business_ | string | 사업장관리번호 | |
| diagnosis | object | null | 사전진단 결과 객체 - 그 사업이 사전진단 대상이 아니면 available·reason·evidence 3키만, 대상이면 subsidy.diagnosis.search 의 결과 항목 하나와 같은 모양입니다 | |
| can_ | boolean | null | 신청 가능 여부 - 사전진단이 없는 사업은 항상 true 이거나 판정 없음(null)입니다 | |
| message_ | string | 안내 문구 - 사전진단이 없는 사업에서만 옵니다. 진단이 있는 사업은 대신 diagnosis 안의 문구를 봅니다 | |
| next_ | string | 다음 호출로 이어갈 액션 힌트 | |
| action | string | 이번에 처리한 액션 이름 | |
| step | number | 신청 진행 단계 식별자 |
{
"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_ | 세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다. | |
| VALIDATION_ | 파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다. | |
| VALIDATION_ | 사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다. | |
| VALIDATION_ | 지원사업 키 확인 불가 — programme_key 가 카탈로그에 없거나 아직 이 상품에서 지원하지 않는 사업입니다. 카탈로그 사업 중 신청을 지원하는 것은 일부뿐입니다 - 값을 다시 확인합니다. |
6. 고용24 기업지원금 신청 수정work24. subsidy. application. modify
MCP 도구 이름 work24__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
기관이 보완을 요청한 지원금 신청서에 같은 접수번호로 수정 요청을 보냅니다.
- 제출한 신청서가 기관으로부터 '보완요청'을 받은 상태여야 합니다(작성중 초안은 workplace_save 로 이어서 작성합니다). [고용24 로그인]confirm=true 와 admin_info_sharing_consent 를 함께 보냅니다. 이 상품의 신청서 쓰기 기능이 정책으로 켜져 있어야 합니다.
- outcome=confirmed 로 확정되면 modified:true 와 함께 '보완요청' 상태를 벗어났는지 확인합니다. 수정 제출을 되돌리는 액션은 없습니다.
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 기관에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이 함께 옵니다(error.preview 도 오지만 이 액션에서는 비어 있습니다).안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm=true 는 첫 요청부터 넣습니다. 토큰을 받은 뒤에 더하면 본문이 달라져 확인 토큰 불일치로 끝나고, 빼고 보내면 토큰은 쓰이고 작업이 「확인 누락」 으로 끝납니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 기관에 아무것도 보내지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| programme_ | string | Y | 카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다 | |
| business_ | string | N | 고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다 | |
| receipt_ | string | Y | 민원신청접수번호 (2단계 저장이 발급) | |
| confirm | boolean | Y | 실제로 제출한 신청서를 수정한다는 확인값입니다. 빠지거나 true 로 읽히지 않는 값이면 기관에 아무것도 보내지 않고 확인이 필요하다는 오류로 끝납니다. 이 칸만으로는 실행되지 않습니다. 첫 요청은 작업을 만들지 않고 HTTP 400 WRITE_CONFIRMATION_REQUIRED 와 error.confirmation_token 을 돌려주므로, 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 이 칸은 첫 요청부터 true 로 넣습니다. 토큰을 받은 뒤에 더하면 본문이 달라져 토큰이 맞지 않습니다 | |
| admin_ | boolean | Y | 행정정보 공동이용 동의 여부입니다. 동의하면 true, 동의하지 않으면 false 를 보냅니다. 보내지 않으면 제출하지 않고 입력 오류(400, WORK24_SUBSIDY_APPLICATION_ADMIN_INFO_CONSENT_REQUIRED)로 답합니다. 동의 여부는 고객이 직접 정하는 사항이라 XBOSS가 대신 정하지 않습니다 | |
| attachments | array | N | 첨부 서류입니다. 첨부 서류가 포함된 신청은 지금 준비 중이라 비워서 보냅니다. 값이 있으면 기관에 보내기 전에 멈추고 501(WORK24_SUBSIDY_APPLICATION_ATTACHMENT_UPLOAD_NOT_MEASURED)로 답합니다. 첨부가 필요 없는 신청은 그대로 이용하실 수 있습니다 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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 한 줄만 옵니다.아래는 outcome=confirmed 일 때만 유효합니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| programme_ | string | 지원사업 키 | |
| programme_ | string | number | boolean | object | array | null | 지원사업 한글명 | |
| business_ | string | 사업장관리번호 | |
| receipt_ | string | 이 신청 건의 접수번호 | |
| outcome | string | 판정 결과 - 이 표가 오는 경우는 항상 confirmed 입니다 | |
| prss_ | string | 기관에 보낸 처리 모드 코드(제출 SNDG · 수정 UPDT) | |
| provider_ | number | 기관 응답 HTTP 상태 코드(증거 기록용 - 판정에는 쓰이지 않습니다) | |
| submitted | boolean | 제출 확정 여부(submit 호출일 때만 true 일 수 있습니다) | |
| modified | boolean | 수정 확정 여부(modify 호출일 때만 true 일 수 있습니다) | |
| verdict_ | object | 확정 시 판정 근거 객체 - 이력·화면 상태를 전/후로 대조한 값입니다 | |
| documents | object | 제출 시점의 첨부서류 목록 조회 결과 객체 | |
| fraud_ | object | null | 부정수급 방지 교육 영상 시청 확인 객체 - modify 호출에도 이 키는 오지만 값은 항상 null 입니다(그 사업 로직이 submit 에만 있습니다) | |
| undo_ | string | 되돌리는 방법 안내 - submit 은 withdraw, modify 는 되돌리는 액션 없음 | |
| acknowledgement | object | 명시 확인 처리 결과 객체 - confirm·confirm_message_ko·confirm_message_measured 를 담고, 행정정보 동의가 필요한 액션(submit·modify)은 admin_info_sharing_consent 등도 함께 옵니다 | |
| action | string | 이번에 처리한 액션 이름 | |
| step | number | 신청 진행 단계 식별자 |
{
"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_ | 성공도 실패도 아님(미확인) — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 제출 응답 본문만으로는 성공을 확정하지 않고 제출 전후 이력을 되읽어 판정합니다. 요청을 보낸 뒤에 생긴 실패도 이 코드로 끝납니다(아래 「요청을 보낸 뒤의 실패」 행). 처리상태가 아직 '보완요청'이면 기관이 수정을 처리로 가져가지 않은 것일 수 있습니다. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다. | |
| AUTH_ | 세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다. | |
| PROVIDER_ | 접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다. | |
| PROVIDER_ | 응답 지연 — 고용24 응답이 지연됐습니다. 재시도 불가로 표시되므로 바로 다시 부르지 말고 잠시 뒤 상태를 확인한 뒤 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다. | |
| PROVIDER_ | 연결 오류 — 고용24 접속에 실패했습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 요청을 보낸 뒤의 실패 — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 쓰기 요청이 기관에 나간 뒤에 생긴 실패는 원인(기관의 5xx 나 4xx 응답, 접근 제한, 응답 지연, 연결 끊김)과 관계없이 이 코드로 끝납니다. 처리됐는지 알 수 없으므로 다시 실행하지 말고 history 로 접수번호의 현재 상태를 확인합니다. 위의 접근 제한, 응답 지연, 업스트림 오류, 연결 오류 행은 쓰기 요청이 나가기 전에 생긴 실패(화면을 여는 단계, 연결을 맺지 못함)에 해당합니다. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다. | |
| VALIDATION_ | 파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다. | |
| VALIDATION_ | 사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다. | |
| POLICY_ | 쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다. | |
| VALIDATION_ | 확인 누락 — confirm=true 가 없습니다. 이 액션은 고용24 화면에서도 확인 대화상자를 거치는 되돌리기 어려운 요청이라 API 도 명시 확인을 요구합니다. | |
| VALIDATION_ | 행정정보 동의 미지정 — admin_info_sharing_consent(true/false)가 없습니다. 기관 제출 화면이 필수로 요구하는 동의 항목이고 고객이 직접 정할 법적 동의라 XBOSS가 대신 정하지 않습니다. 동의하지 않아도 제출은 되지만, 행정정보로 대체 확인하지 못하는 서류는 직접 첨부해야 할 수 있습니다. | |
| INTERNAL_ | 첨부 동시 업로드 불가 — attachments 에 값을 채워 보내면 제출 자체를 중단합니다(파일을 기관으로 보내는 기능은 아직 지원하지 않고, 조용히 무시하면 첨부 없이 접수되어 서류 누락 반려로 이어지기 때문입니다). 첨부는 고용24 화면에서 먼저 올린 뒤 draft_validate 로 붙었는지 확인하고 제출합니다. 응답의 error.message 는 '신청이 기관에 전송되기 전에 중단됐습니다. 접수된 내용은 없으니 중복 걱정은 하지 않으셔도 됩니다.' 로 시작하고, 줄을 바꿔 '다음 단계:' 뒤에 이 사유와 다음 행동이 이어집니다. 기관에 반영된 것이 없으므로 같은 요청을 다시 호출해도 중복 처리가 되지 않습니다. | |
| RESOURCE_ | 접수번호 화면에서 확인 안 됨 — receipt_no 의 신청서를 제출 화면에서 확인하지 못했습니다(DRAFT_NOT_FOUND). | |
| RESOURCE_ | 수정 대상 상태 아님 — 셋 중 하나입니다: 처리상태를 확인하지 못했거나(MODIFY_STATE_UNVERIFIED), 아직 작성중 초안이라 수정이 의미가 없거나(MODIFY_ON_DRAFT — 이때는 workplace_save 로 이어서 작성합니다), 보완요청 상태가 아닌 다른 처리상태입니다(NOT_MODIFIABLE — 수정은 '보완요청' 상태에만 가능합니다. 실무에서 가장 자주 맞는 경우입니다). 보내기 전에 막습니다. |
7. 고용24 기업지원금 신청 필요입력 안내work24. subsidy. application. requirements
MCP 도구 이름 work24__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
지원금을 신청하기 전에 준비해야 할 입력값과 서류, 등록된 지급계좌를 알려줍니다.
- 고용24 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [고용24 로그인]
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| programme_ | string | Y | 카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다 | |
| business_ | string | N | 고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다 | |
| application_ | number | N | 신청 귀속연도입니다. options 가 있으면 그 value 중 하나를 입력해 주세요(예: 2026) |
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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| programme_ | string | 지원사업 키 | |
| programme_ | string | number | boolean | object | array | null | 지원사업 한글명 | |
| business_ | string | 사업장관리번호 | |
| inputs | array | 신청서 작성에 필요한 입력값 목록 | |
| blocked | boolean | 필요입력 확인 결과 신청이 막혀 있는지 여부 | |
| blocking_ | array | 막혀 있다면 그 사유 목록 | |
| safety | object | 이 호출은 입력 안내만 하며 저장과 제출을 하지 않았다는 고정 표시 객체 - input_only true, save_executed false, submit_executed false 입니다 | |
| registered_ | object | 등록된 지급계좌 조회 결과 객체 - 읽으면 resolved true 와 기관이 준 전체 건수 count, 계좌 목록 accounts(은행명 bank_name, 계좌번호 account_no, 화면 표기 account_no_display, 예금주 holder)가 옵니다. 첫 쪽만 읽어 받은 줄이 건수보다 적으면 partial true 가 붙습니다. 조회하지 못했거나 이 화면에 지급계좌 칸이 없으면 오류가 아니라 resolved false 와 사유 코드 reason 으로 옵니다 - 계좌가 없다는 뜻이 아니므로 accounts 가 늘 있다고 기대하지 마세요 | |
| declared_ | array | 다른 화면에서만 확인되는, 이 응답에는 없는 선언 항목 목록 | |
| attachments | object | 필요한 첨부서류 안내 객체 | |
| action | string | 이번에 처리한 액션 이름 | |
| step | number | 신청 진행 단계 식별자 |
{
"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_ | 세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다. | |
| PROVIDER_ | 접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다. | |
| PROVIDER_ | 업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다. | |
| PROVIDER_ | 연결 오류 — 고용24 접속에 실패했습니다. 응답 지연(타임아웃)도 이 코드로 옵니다 - 조회는 재시도해도 안전한 요청이라 재시도 가능으로 표시됩니다. 잠시 후 다시 호출합니다. | |
| VALIDATION_ | 파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다. | |
| VALIDATION_ | 사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다. | |
| VALIDATION_ | 지원사업 키 확인 불가 — programme_key 가 카탈로그에 없거나 아직 이 상품에서 지원하지 않는 사업입니다. 카탈로그 사업 중 신청을 지원하는 것은 일부뿐입니다 - 값을 다시 확인합니다. |
8. 고용24 기업지원금 신청 제출work24. subsidy. application. submit
MCP 도구 이름 work24__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
작성을 마친 지원금 신청서를 고용노동부에 제출합니다.
- workplace_save 로 발급받은 receipt_no 가 있어야 하고, draft_validate 로 제출 가능 상태(첨부서류·부정수급 방지 영상)를 먼저 확인해야 합니다. [고용24 로그인]confirm=true 와 admin_info_sharing_consent(행정정보 공동이용 동의 여부)를 함께 보냅니다. 이 상품의 신청서 쓰기 기능이 정책으로 켜져 있어야 합니다.
- outcome=confirmed 로 확정되면 submitted:true 와 함께 접수 이탈을 확인합니다. undo_hint_ko 로 되돌리는 방법(withdraw)을 안내합니다.
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 기관에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이 함께 옵니다(error.preview 도 오지만 이 액션에서는 비어 있습니다).안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm=true 는 첫 요청부터 넣습니다. 토큰을 받은 뒤에 더하면 본문이 달라져 확인 토큰 불일치로 끝나고, 빼고 보내면 토큰은 쓰이고 작업이 「확인 누락」 으로 끝납니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 기관에 아무것도 보내지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| programme_ | string | Y | 카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다 | |
| business_ | string | N | 고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다 | |
| receipt_ | string | Y | 민원신청접수번호 (2단계 저장이 발급) | |
| confirm | boolean | Y | 실제로 신청서를 제출한다는 확인값입니다. 빠지거나 true 로 읽히지 않는 값이면 기관에 아무것도 보내지 않고 확인이 필요하다는 오류로 끝납니다. 이 칸만으로는 실행되지 않습니다. 첫 요청은 작업을 만들지 않고 HTTP 400 WRITE_CONFIRMATION_REQUIRED 와 error.confirmation_token 을 돌려주므로, 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 이 칸은 첫 요청부터 true 로 넣습니다. 토큰을 받은 뒤에 더하면 본문이 달라져 토큰이 맞지 않습니다 | |
| admin_ | boolean | Y | 행정정보 공동이용 동의 여부입니다. 동의하면 true, 동의하지 않으면 false 를 보냅니다. 보내지 않으면 제출하지 않고 입력 오류(400, WORK24_SUBSIDY_APPLICATION_ADMIN_INFO_CONSENT_REQUIRED)로 답합니다. 동의 여부는 고객이 직접 정하는 사항이라 XBOSS가 대신 정하지 않습니다 | |
| attachments | array | N | 첨부 서류입니다. 첨부 서류가 포함된 신청은 지금 준비 중이라 비워서 보냅니다. 값이 있으면 기관에 보내기 전에 멈추고 501(WORK24_SUBSIDY_APPLICATION_ATTACHMENT_UPLOAD_NOT_MEASURED)로 답합니다. 첨부가 필요 없는 신청은 그대로 이용하실 수 있습니다 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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 한 줄만 옵니다.아래는 outcome=confirmed 일 때만 유효합니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| programme_ | string | 지원사업 키 | |
| programme_ | string | number | boolean | object | array | null | 지원사업 한글명 | |
| business_ | string | 사업장관리번호 | |
| receipt_ | string | 이 신청 건의 접수번호 | |
| outcome | string | 판정 결과 - 이 표가 오는 경우는 항상 confirmed 입니다 | |
| prss_ | string | 기관에 보낸 처리 모드 코드(제출 SNDG · 수정 UPDT) | |
| provider_ | number | 기관 응답 HTTP 상태 코드(증거 기록용 - 판정에는 쓰이지 않습니다) | |
| submitted | boolean | 제출 확정 여부(submit 호출일 때만 true 일 수 있습니다) | |
| modified | boolean | 수정 확정 여부(modify 호출일 때만 true 일 수 있습니다) | |
| verdict_ | object | 확정 시 판정 근거 객체 - 이력·화면 상태를 전/후로 대조한 값입니다 | |
| documents | object | 제출 시점의 첨부서류 목록 조회 결과 객체 | |
| fraud_ | object | null | 부정수급 방지 교육 영상 시청 확인 객체 - modify 호출에도 이 키는 오지만 값은 항상 null 입니다(그 사업 로직이 submit 에만 있습니다) | |
| undo_ | string | 되돌리는 방법 안내 - submit 은 withdraw, modify 는 되돌리는 액션 없음 | |
| acknowledgement | object | 명시 확인 처리 결과 객체 - confirm·confirm_message_ko·confirm_message_measured 를 담고, 행정정보 동의가 필요한 액션(submit·modify)은 admin_info_sharing_consent 등도 함께 옵니다 | |
| action | string | 이번에 처리한 액션 이름 | |
| step | number | 신청 진행 단계 식별자 |
{
"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_ | 성공도 실패도 아님(미확인) — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 제출 응답 본문만으로는 성공을 확정하지 않고 제출 전후 이력을 되읽어 판정합니다. 요청을 보낸 뒤에 생긴 실패도 이 코드로 끝납니다(아래 「요청을 보낸 뒤의 실패」 행). history 로 현재 상태를 확인한 뒤, 아직 '작성중'이면 그때 다시 제출하세요. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다. | |
| AUTH_ | 세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다. | |
| PROVIDER_ | 접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다. | |
| PROVIDER_ | 응답 지연 — 고용24 응답이 지연됐습니다. 재시도 불가로 표시되므로 바로 다시 부르지 말고 잠시 뒤 상태를 확인한 뒤 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다. | |
| PROVIDER_ | 연결 오류 — 고용24 접속에 실패했습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 요청을 보낸 뒤의 실패 — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 쓰기 요청이 기관에 나간 뒤에 생긴 실패는 원인(기관의 5xx 나 4xx 응답, 접근 제한, 응답 지연, 연결 끊김)과 관계없이 이 코드로 끝납니다. 처리됐는지 알 수 없으므로 다시 실행하지 말고 history 로 접수번호의 현재 상태를 확인합니다. 위의 접근 제한, 응답 지연, 업스트림 오류, 연결 오류 행은 쓰기 요청이 나가기 전에 생긴 실패(화면을 여는 단계, 연결을 맺지 못함)에 해당합니다. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다. | |
| VALIDATION_ | 파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다. | |
| VALIDATION_ | 사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다. | |
| POLICY_ | 쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다. | |
| VALIDATION_ | 확인 누락 — confirm=true 가 없습니다. 이 액션은 고용24 화면에서도 확인 대화상자를 거치는 되돌리기 어려운 요청이라 API 도 명시 확인을 요구합니다. | |
| VALIDATION_ | 행정정보 동의 미지정 — admin_info_sharing_consent(true/false)가 없습니다. 기관 제출 화면이 필수로 요구하는 동의 항목이고 고객이 직접 정할 법적 동의라 XBOSS가 대신 정하지 않습니다. 동의하지 않아도 제출은 되지만, 행정정보로 대체 확인하지 못하는 서류는 직접 첨부해야 할 수 있습니다. | |
| INTERNAL_ | 첨부 동시 업로드 불가 — attachments 에 값을 채워 보내면 제출 자체를 중단합니다(파일을 기관으로 보내는 기능은 아직 지원하지 않고, 조용히 무시하면 첨부 없이 접수되어 서류 누락 반려로 이어지기 때문입니다). 첨부는 고용24 화면에서 먼저 올린 뒤 draft_validate 로 붙었는지 확인하고 제출합니다. 응답의 error.message 는 '신청이 기관에 전송되기 전에 중단됐습니다. 접수된 내용은 없으니 중복 걱정은 하지 않으셔도 됩니다.' 로 시작하고, 줄을 바꿔 '다음 단계:' 뒤에 이 사유와 다음 행동이 이어집니다. 기관에 반영된 것이 없으므로 같은 요청을 다시 호출해도 중복 처리가 되지 않습니다. | |
| RESOURCE_ | 접수번호 화면에서 확인 안 됨 — receipt_no 의 신청서를 제출 화면에서 확인하지 못했습니다(DRAFT_NOT_FOUND). | |
| RESOURCE_ | 미완성 초안 — 첨부서류 목록을 확인하지 못했거나(attachment_list_unresolved) 필수 서류가 비었거나(required_documents_missing) 최초 신청인데 부정수급 방지 영상을 아직 안 봤을 때(fraud_prevention_video_required) 제출을 막습니다(NOT_SUBMITTABLE). draft_validate 로 먼저 무엇이 빠졌는지 확인합니다. | |
| RESOURCE_ | 이미 작성중 아님 — 접수번호가 이미 작성중을 벗어난 상태(제출됨·반려 등)라 제출 대상이 아닙니다(NOT_A_DRAFT). history 로 현재 상태를 확인합니다. |
9. 고용24 기업지원금 대상자정보 단계 진입work24. subsidy. application. target_ init
MCP 도구 이름 work24__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
작성 중인 신청서의 대상자정보 단계를 열고 입력 항목을 확인합니다.
- 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
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| programme_ | string | Y | 카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다 | |
| business_ | string | N | 고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다 | |
| receipt_ | string | Y | 민원신청접수번호 (2단계 저장이 발급) |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| programme_ | string | 지원사업 키 | |
| programme_ | string | number | boolean | object | array | null | 지원사업 한글명 | |
| business_ | string | 사업장관리번호 | |
| target_ | string | 이 키가 오면 그 사업에 대상자정보 단계가 없다는 표시입니다(값은 고정 문자열 target_stage_absent). 단계가 있는 사업에서는 이 키 자체가 오지 않습니다 | |
| targets | array | 지정된 대상자 목록 - target_stage 가 올 때(단계 없음)만 오고 항상 빈 배열입니다 | |
| message_ | string | 대상자정보 단계가 없다는 안내 문구 - target_stage 가 올 때만 옵니다 | |
| receipt_ | string | 이 신청 건의 접수번호 - target_stage 가 오지 않을 때(단계 있음)만 옵니다 | |
| screen_ | number | 기관 화면 진행 상태 코드 - target_stage 가 오지 않을 때만 옵니다 | |
| attachment_ | object | 첨부서류 모듈 안내 객체 - target_stage 가 오지 않을 때만 옵니다 | |
| screen_ | object | 화면 진입 제약 객체 - target_stage 가 오지 않을 때만 옵니다 | |
| safety | object | 저장(save_executed)·제출(submit_executed) 실행 여부를 나타내는 안전 상태 객체 - target_stage 가 오지 않을 때만 옵니다 | |
| next_ | string | 다음 호출로 이어갈 액션 힌트 - 두 경우 모두 옵니다 | |
| action | string | 이번에 처리한 액션 이름 | |
| step | number | 신청 진행 단계 식별자 |
{
"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_ | 세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다. | |
| PROVIDER_ | 접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다. | |
| PROVIDER_ | 업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다. | |
| PROVIDER_ | 연결 오류 — 고용24 접속에 실패했습니다. 응답 지연(타임아웃)도 이 코드로 옵니다 - 조회는 재시도해도 안전한 요청이라 재시도 가능으로 표시됩니다. 잠시 후 다시 호출합니다. | |
| VALIDATION_ | 파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다. | |
| VALIDATION_ | 사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다. | |
| VALIDATION_ | 지원사업 키 확인 불가 — programme_key 가 카탈로그에 없거나 아직 이 상품에서 지원하지 않는 사업입니다. 카탈로그 사업 중 신청을 지원하는 것은 일부뿐입니다 - 값을 다시 확인합니다. | |
| POLICY_ | 쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다. |
10. 고용24 기업지원금 대상자 저장work24. subsidy. application. target_ save
MCP 도구 이름 work24__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
선택한 근로자를 신청서의 지원 대상으로 지정합니다.
- target_search 로 조회한 후보 중에서 지정합니다. [고용24 로그인]대상자정보 단계가 없는 사업이면 호출은 되지만 저장할 대상이 없다는 안내만 돌아옵니다(오류로 막히지 않습니다. target_init 으로 미리 확인할 수 있습니다). 이 상품의 신청서 쓰기 기능이 정책으로 켜져 있어야 합니다.
- 이 사업에 대상자정보 단계 자체가 없으면 오류가 아니라 성공 응답으로 오지만, 지정한 대상자 정보는 실제로 저장되지 않습니다.
- 이때 target_stage 키가 오고(값은 빈 값이 아니라 고정 문자열 target_stage_absent 입니다), targets 는 빈 배열로 오고 message_ko 로 이 단계가 없다는 안내가, next_action_hint 로 다음 단계가 옵니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| programme_ | string | Y | 카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다 | |
| business_ | string | N | 고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다 | |
| receipt_ | string | Y | 민원신청접수번호 (2단계 저장이 발급) | |
| target_ | array | Y | target_search 결과의 irno 배열. 순서가 신청서 행 순서가 된다 | |
| worker_ | string | Y | 근로자유형 코드. P2/P3/P(취업지원프로그램 관련), S(중증장애인), W(여성가장), R(섬지역 거주자). target_search 응답의 selection_options 참조 | |
| labor_ | string | Y | 근로계약유형 코드. ACV00(기간의 정함 없음), ACV01(2년 초과), ACV02(1년 이상), ACV03(기타 기간제) |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| programme_ | string | 지원사업 키 | |
| programme_ | string | number | boolean | object | array | null | 지원사업 한글명 | |
| business_ | string | 사업장관리번호 | |
| outcome | string | 판정 결과 - 대상자정보 단계가 있는 사업에서만 옵니다. 이 칸이 오는 경우는 항상 confirmed 입니다 | |
| receipt_ | string | 이 신청 건의 접수번호 - 대상자정보 단계가 있는 사업에서만 옵니다 | |
| targets_ | number | 이번에 지정 저장된 대상자 수 - 대상자정보 단계가 있는 사업에서만 옵니다 | |
| targets | array | 저장된 대상자 요약 목록(row_summary) - 단계가 없으면 빈 배열입니다 | |
| request_ | number | null | 화면에서 읽은, 대상자 1인당 신청금액 - 대상자정보 단계가 있는 사업에서만 옵니다 | |
| target_ | string | 이 키가 오면 그 사업에 대상자정보 단계가 없다는 표시입니다(값은 빈 값이 아니라 고정 문자열 target_stage_absent 입니다). 단계가 있는 사업의 정상 응답에는 이 키 자체가 오지 않습니다. | |
| message_ | string | 안내 문구 - 대상자정보 단계가 없는 사업에서만 옵니다 | |
| next_ | string | 다음 호출로 이어갈 액션 힌트 - draft_validate | |
| action | string | 이번에 처리한 액션 이름 | |
| step | number | 신청 진행 단계 식별자 |
{
"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_ | 세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다. | |
| PROVIDER_ | 접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다. | |
| PROVIDER_ | 응답 지연 — 고용24 응답이 지연됐습니다. 재시도 불가로 표시되므로 바로 다시 부르지 말고 잠시 뒤 상태를 확인한 뒤 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다. | |
| PROVIDER_ | 연결 오류 — 고용24 접속에 실패했습니다. 잠시 후 다시 호출합니다. | |
| VALIDATION_ | 파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다. | |
| VALIDATION_ | 사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다. | |
| POLICY_ | 쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다. | |
| INTERNAL_ | 후보 미확인 — 지정 가능한 피보험자 목록을 먼저 확인하지 못해 저장을 중단했습니다. target_search 를 먼저 호출합니다. 응답의 error.message 는 '신청이 기관에 전송되기 전에 중단됐습니다. 접수된 내용은 없으니 중복 걱정은 하지 않으셔도 됩니다.' 로 시작하고, 줄을 바꿔 '다음 단계:' 뒤에 이 사유와 다음 행동이 이어집니다. 기관에 반영된 것이 없으므로 같은 요청을 다시 호출해도 중복 처리가 되지 않습니다. 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)에서 화면을 옮기는 동안 중간 저장 요청이 이미 나갔다면 이 행이 아니라 아래 「중간 저장 후 중단」 행으로 끝납니다. | |
| INTERNAL_ | 신청금액 미확인 — 화면에서 신청금액을 읽지 못해 임의로 채우지 않고 중단했습니다. 응답의 error.message 는 '신청이 기관에 전송되기 전에 중단됐습니다. 접수된 내용은 없으니 중복 걱정은 하지 않으셔도 됩니다.' 로 시작하고, 줄을 바꿔 '다음 단계:' 뒤에 이 사유와 다음 행동이 이어집니다. 기관에 반영된 것이 없으므로 같은 요청을 다시 호출해도 중복 처리가 되지 않습니다. 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)에서 화면을 옮기는 동안 중간 저장 요청이 이미 나갔다면 이 행이 아니라 아래 「중간 저장 후 중단」 행으로 끝납니다. | |
| PROVIDER_ | 중간 저장 후 중단 — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 후보 목록이나 신청금액을 읽지 못해 대상자 저장을 중단했지만, 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)은 그 앞에서 화면을 옮기는 동안 중간 저장 요청이 이미 기관에 나갔습니다. 그래서 위 두 행과 달리 기관에 반영된 것이 없다고 말할 수 없습니다. 다시 실행하지 말고 고용24 [기업지원금 > 참여 사업관리(기존 신청자)] 화면에서 해당 신청서의 저장 내용과 처리상태를 먼저 확인합니다. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다. | |
| PROVIDER_ | 기관이 저장 요청을 거절 — 기관이 대상자 저장 요청 자체를 오류(500)로 거절했습니다. 지정하려는 근로자가 이번 차수에 지정 가능한 대상이 아니면(선택 가능 인원 0명 포함) 기관이 이렇게 거절합니다 - target_search 응답의 selectable 여부를 먼저 확인합니다. | |
| VALIDATION_ | 기관이 사유를 말하며 거절 — 기관이 저장 응답에 사유를 담아 대상자 저장을 받아 주지 않았습니다(TARGET_SAVE_NOT_ACCEPTED). error.message 에 기관이 알려 준 사유가 오고 다음 단계 안내가 함께 옵니다. 사유대로 대상자 선택을 고친 뒤 같은 단계를 다시 저장합니다. | |
| INTERNAL_ | 저장 실패 — 기관이 저장 결과를 0/빈 값으로 응답했고 사유는 주지 않았습니다. 응답의 error.message 는 이 사유가 아니라 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')로 옵니다. |
11. 고용24 기업지원금 대상자 후보 조회work24. subsidy. application. target_ search
MCP 도구 이름 work24__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
지원 대상으로 지정할 수 있는 사업장 고용보험 피보험자를 조회합니다.
- 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
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| programme_ | string | Y | 카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다 | |
| business_ | string | N | 고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다 | |
| receipt_ | string | Y | 민원신청접수번호 (2단계 저장이 발급) | |
| query | string | N | 성명 부분검색. 비우면 사업장 피보험자 전체를 돌려준다 | |
| page | number | N | 페이지 번호 (1부터) | |
| page_ | number | N | 한 쪽에 받을 대상자 수입니다. 1 이상 100 이하의 정수이고 보내지 않으면 10 입니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| programme_ | string | 지원사업 키 | |
| programme_ | string | number | boolean | object | array | null | 지원사업 한글명 | |
| business_ | string | 사업장관리번호 | |
| target_ | string | 이 키가 오면 그 사업에 대상자정보 단계가 없다는 표시입니다(값은 고정 문자열 target_stage_absent). 단계가 있는 사업에서는 이 키 자체가 오지 않습니다 | |
| targets | array | target_stage 가 올 때(단계 없음)만 오고 항상 빈 배열입니다 | |
| message_ | string | 대상자정보 단계가 없다는 안내 문구 - target_stage 가 올 때만 옵니다 | |
| receipt_ | string | 이 신청 건의 접수번호 - target_stage 가 오지 않을 때(단계 있음)만 옵니다 | |
| resolved | boolean | 후보 조회가 됐는지 여부 - target_stage 가 오지 않을 때만 옵니다. false 면 reason· provider_message_ko 에 안 된 사유가, true 면 count·selectable_count·candidates· how_to_select_ko·why_selectable_matters_ko 에 결과가 담깁니다 | |
| reason | string | resolved:false 일 때의 사유 코드(target_list_not_in_response) - resolved:true 면 오지 않습니다 | |
| count | number | 조회된 후보 총 인원 - resolved:true 일 때만 옵니다 | |
| selectable_ | number | 그중 이번 차수에 지정 가능한(selectable:true) 인원 - resolved:true 일 때만 옵니다 | |
| candidates | array | 지정할 수 있는 근로자 후보 목록 - target_stage 가 오지 않을 때만 옵니다 | |
| note_ | string | 조회 결과에 대한 한국어 안내 문구 - target_stage 가 오지 않을 때만 옵니다 | |
| provider_ | string | 기관 원문 안내 문구(msgTxt, 최대 300자) - 후보가 0명일 때가 아니라 기관 응답에서 후보 목록 자체를 읽지 못했을 때(resolved:false) 옵니다. 후보가 0명인 것은 정상 응답(resolved:true·count:0)이라 이 필드가 오지 않습니다 | |
| how_ | string | target_save 호출 방법 안내 문구 - resolved:true 일 때만 옵니다 | |
| why_ | string | selectable 판정의 의미(사전진단은 사업장 요건만 본다는 안내) - resolved:true 일 때만 옵니다 | |
| selection_ | object | 지정 시 선택할 수 있는 옵션 객체 - worker_type · labor_contract - target_stage 가 오지 않을 때만 옵니다 | |
| required_ | string | 대상자 저장(target_save)에 필요한 값을 안내하는 문구 - target_stage 가 오지 않을 때만 옵니다 | |
| safety | object | 저장·제출 실행 여부를 나타내는 안전 상태 객체 - target_stage 가 오지 않을 때만 옵니다 | |
| next_ | string | 다음 호출로 이어갈 액션 힌트 - target_stage 가 올 때만 옵니다 | |
| action | string | 이번에 처리한 액션 이름 | |
| step | number | 신청 진행 단계 식별자 |
{
"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_ | 세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다. | |
| PROVIDER_ | 접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다. | |
| PROVIDER_ | 업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다. | |
| PROVIDER_ | 연결 오류 — 고용24 접속에 실패했습니다. 응답 지연(타임아웃)도 이 코드로 옵니다 - 조회는 재시도해도 안전한 요청이라 재시도 가능으로 표시됩니다. 잠시 후 다시 호출합니다. | |
| VALIDATION_ | 파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다. | |
| VALIDATION_ | 사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다. | |
| VALIDATION_ | 지원사업 키 확인 불가 — programme_key 가 카탈로그에 없거나 아직 이 상품에서 지원하지 않는 사업입니다. 카탈로그 사업 중 신청을 지원하는 것은 일부뿐입니다 - 값을 다시 확인합니다. | |
| POLICY_ | 쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다. |
12. 고용24 기업지원금 신청 철회work24. subsidy. application. withdraw
MCP 도구 이름 work24__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
제출한 지원금 신청을 정식 절차로 철회하고 처리 결과를 확인합니다.
- 제출이 완료된 신청서만 대상입니다(작성중 초안은 delete 로 지웁니다). confirm=true 를 함께 보냅니다. 이 상품의 신청서 쓰기 기능이 정책으로 켜져 있어야 합니다. [고용24 로그인]
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 기관에 아무것도 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이 함께 옵니다(error.preview 도 오지만 이 액션에서는 비어 있습니다).안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm=true 는 첫 요청부터 넣습니다. 토큰을 받은 뒤에 더하면 본문이 달라져 확인 토큰 불일치로 끝나고, 빼고 보내면 토큰은 쓰이고 작업이 「확인 누락」 으로 끝납니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 기관에 아무것도 보내지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| programme_ | string | Y | 카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다 | |
| business_ | string | N | 고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다 | |
| receipt_ | string | Y | 민원신청접수번호 (2단계 저장이 발급) | |
| confirm | boolean | Y | 실제로 신청을 철회(반려 요청)한다는 확인값입니다. 빠지거나 true 로 읽히지 않는 값이면 기관에 아무것도 보내지 않고 확인이 필요하다는 오류로 끝납니다. 이 칸만으로는 실행되지 않습니다. 첫 요청은 작업을 만들지 않고 HTTP 400 WRITE_CONFIRMATION_REQUIRED 와 error.confirmation_token 을 돌려주므로, 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 이 칸은 첫 요청부터 true 로 넣습니다. 토큰을 받은 뒤에 더하면 본문이 달라져 토큰이 맞지 않습니다 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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).0 이하이면 아래 철회 실패 행이고, 응답 본문을 읽지 못했거나 그 칸이 비어 있으면 아래 미확인 행입니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| programme_ | string | 지원사업 키 | |
| programme_ | string | number | boolean | object | array | null | 지원사업 한글명 | |
| business_ | string | 사업장관리번호 | |
| receipt_ | string | 철회한 신청 건의 접수번호 | |
| outcome | string | 판정 결과 - 이 표가 오는 경우는 항상 confirmed 입니다 | |
| withdrawn | boolean | 철회 확정 여부 - 이 표가 오는 경우는 항상 true 입니다(실패와 확인 안 됨은 작업이 FAILED 로 끝나 이 표가 오지 않습니다) | |
| acknowledgement | object | 명시 확인 처리 결과 객체 - confirm·confirm_message_ko·confirm_message_measured 를 담고, 행정정보 동의가 필요한 액션(submit·modify)은 admin_info_sharing_consent 등도 함께 옵니다 | |
| action | string | 이번에 처리한 액션 이름 | |
| step | null | 신청 진행 단계 식별자 - 이 액션은 신청 단계 밖이라 항상 null 입니다 |
{
"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_ | 성공도 실패도 아님(미확인) — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 반려요청 응답 본문을 읽지 못했거나 처리 결과(resultMap.result)가 없거나 숫자가 아닐 때입니다. 다시 철회하지 말고 고용24 화면이나 history 로 접수번호의 처리상태를 확인합니다. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다. | |
| AUTH_ | 세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다. | |
| PROVIDER_ | 접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다. | |
| PROVIDER_ | 응답 지연 — 고용24 응답이 지연됐습니다. 재시도 불가로 표시되므로 바로 다시 부르지 말고 잠시 뒤 상태를 확인한 뒤 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다. | |
| PROVIDER_ | 연결 오류 — 고용24 접속에 실패했습니다. 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 요청을 보낸 뒤의 실패 — 기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 쓰기 요청이 기관에 나간 뒤에 생긴 실패는 원인(기관의 5xx 나 4xx 응답, 접근 제한, 응답 지연, 연결 끊김)과 관계없이 이 코드로 끝납니다. 처리됐는지 알 수 없으므로 다시 실행하지 말고 history 로 접수번호의 현재 상태를 확인합니다. 위의 접근 제한, 응답 지연, 업스트림 오류, 연결 오류 행은 쓰기 요청이 나가기 전에 생긴 실패(화면을 여는 단계, 연결을 맺지 못함)에 해당합니다. 이 상태는 작업을 FAILED 로 만들어 result.data 가 저장되지 않습니다 - 아래 응답 필드 표는 이 경우에 적용되지 않고, error.message 한 줄(위 안내 문구 + 다음 문장을 이어붙인 것)만 받습니다. | |
| VALIDATION_ | 파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다. | |
| VALIDATION_ | 사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다. | |
| POLICY_ | 쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다. | |
| VALIDATION_ | 확인 누락 — confirm=true 가 없습니다. 이 액션은 고용24 화면에서도 확인 대화상자를 거치는 되돌리기 어려운 요청이라 API 도 명시 확인을 요구합니다. | |
| RESOURCE_ | 철회 값 확인 불가 — 철회에 필요한 기관 부여 값(issn 등)을 화면에서 확인하지 못했습니다(WITHDRAW_KEYS_MISSING). 제출이 완료된 신청서가 맞는지 먼저 확인합니다 - 작성중 초안은 delete 로 지웁니다. | |
| INTERNAL_ | 철회 실패 — 기관이 처리 결과를 0 이하로 응답했습니다. 응답의 error.message 는 이 사유가 아니라 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')로 옵니다. |
13. 고용24 기업지원금 사업장정보 저장work24. subsidy. application. workplace_ save
MCP 도구 이름 work24__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
신청서에 사업장정보를 저장하고 접수번호를 받습니다.
- 고용24 세션 로그인 후 init 으로 신청 가능 여부를, requirements 로 필요한 입력을 먼저 확인합니다. [고용24 로그인]이 상품의 신청서 쓰기 기능이 정책으로 켜져 있어야 합니다. 이어서 작성하려면 receipt_no 를 함께 보냅니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| programme_ | string | Y | 카탈로그 사업 키. 서식코드·화면경로가 여기서 나온다 | |
| business_ | string | N | 고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다 | |
| applicant_ | string | N | 신청인 우편번호 | |
| applicant_ | string | N | 신청인 기본주소 | |
| applicant_ | string | N | 신청인 상세주소 | |
| manager_ | string | N | 담당자 성명 | |
| manager_ | string | N | 담당자 일반전화 앞자리 | |
| manager_ | string | N | 담당자 일반전화 뒷자리 | |
| manager_ | string | N | 담당자 휴대전화 앞자리 | |
| manager_ | string | N | 담당자 휴대전화 뒷자리 | |
| manager_ | string | N | 담당자 이메일 | |
| payment_ | string | N | 지급계좌 은행명 | |
| payment_ | string | N | 지급계좌 계좌번호 | |
| payment_ | string | N | 지급계좌 예금주 (기관 필수 아님) | |
| receipt_ | string | N | 기존 초안을 이어서 저장할 때만 지정한다. 비우면 신규 초안 | |
| application_ | number | N | 신청 귀속연도. requirements 의 options 가 있으면 그 값 중 하나 | |
| application_ | number | N | 신청 차수. requirements 의 options 값 중 하나(분기 1 또는 월 9 등). 숫자로 보내면 화면 값('09' 등)으로 맞춰 넣는다 |
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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| programme_ | string | 지원사업 키 | |
| programme_ | string | number | boolean | object | array | null | 지원사업 한글명 | |
| business_ | string | 사업장관리번호 | |
| outcome | string | 판정 결과 - 이 응답이 오는 경우는 항상 confirmed 입니다(접수번호가 발급되지 않으면 오류로 끝납니다) | |
| receipt_ | string | 새로 발급됐거나 이어서 쓴 접수번호 - 이후 모든 단계가 이 값을 씁니다 | |
| draft_ | string | 저장 직후의 작성중 상태 코드 | |
| next_ | string | 다음 호출로 이어갈 액션 힌트 - target_init | |
| action | string | 이번에 처리한 액션 이름 | |
| step | number | 신청 진행 단계 식별자 |
{
"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_ | 세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다. | |
| PROVIDER_ | 접근 제한 — 고용24가 요청을 일시적으로 제한했습니다. 짧은 시간에 너무 많이 호출했다면 잠시 후 다시 시도할 수 있지만, 접근 자체가 차단된 경우에는 재시도해도 풀리지 않으므로 계속되면 문의합니다. | |
| PROVIDER_ | 응답 지연 — 고용24 응답이 지연됐습니다. 재시도 불가로 표시되므로 바로 다시 부르지 말고 잠시 뒤 상태를 확인한 뒤 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 고용24가 일시적으로 응답하지 않거나 올바르지 않은 응답을 줬습니다. 일시적 무응답은 잠시 후 다시 호출하면 되지만, 기관이 명확히 오류로 답한 경우에는 재시도해도 같은 결과이므로 보낸 값부터 다시 확인합니다. | |
| PROVIDER_ | 연결 오류 — 고용24 접속에 실패했습니다. 잠시 후 다시 호출합니다. | |
| VALIDATION_ | 파라미터 형식 오류 — 보낸 값이 이 액션의 요청 형식과 맞지 않습니다(예: 필수 필드 누락·타입 불일치·정의되지 않은 필드 포함 - 이 계약은 모르는 필드를 허용하지 않습니다). 메시지는 원인이 된 필드 이름을 pydantic 원문 그대로 담아 영문이 섞일 수 있습니다. | |
| VALIDATION_ | 사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다. | |
| POLICY_ | 쓰기 잠금 — 이 상품의 신청서 쓰기 기능이 정책으로 잠겨 있습니다. 다시 시도해도 풀리지 않으니 서비스문의로 알려 주세요. 사전진단·신청 진입·필요입력 안내·신청 이력 조회는 잠긴 동안에도 그대로 됩니다. 다만 중간 저장이 필요한 일부 사업(카탈로그에 선언된 경우)의 대상자 조회(target_init · target_search)·제출 전 확인(draft_validate)은 그 화면 진입 자체가 실제 저장을 수반해 함께 잠깁니다. | |
| RESOURCE_ | 사전진단 불통과 — 사업주 사전진단을 통과하지 못해 신청할 수 없습니다(DIAGNOSIS_BLOCKS). init 또는 diagnosis.search 로 사유를 먼저 확인합니다. | |
| RESOURCE_ | 이어쓰기 대상 없음 — receipt_no 로 지정한 작성중 신청서를 사업장정보 화면에서 찾지 못했습니다(DRAFT_NOT_FOUND). 이 상태로 저장하면 새 초안이 생기므로 중단합니다 - history 로 확인 후 다시 시도합니다. | |
| RESOURCE_ | 중복 신청 방지 — receipt_no 를 생략했는데 같은 사업장·서식·귀속연도로 이미 신청한 이력이 있으면(PRIOR_APPLICATION_EXISTS) 또는 그 확인 자체가 안 되면(WORK24_SUBSIDY_APPLICATION_IDEMPOTENCY_UNVERIFIED) 중복 신청을 막기 위해 저장을 중단합니다. 이어서 작성하려면 안내된 접수번호를 receipt_no 로 함께 보냅니다. | |
| VALIDATION_ | 필수 입력 누락 — 화면에도 기관이 채워 주는 값도 없는 필수 항목이 있습니다(REQUIRED_FIELDS_MISSING). requirements 로 무엇이 필요한지 먼저 확인합니다. | |
| VALIDATION_ | 계좌 거절 — 기관이 등록한 지급계좌를 문제 삼아 접수번호를 발급하지 않았습니다(ACCOUNT_REJECTED). 계좌를 다시 등록·확인한 뒤 다시 시도합니다. | |
| VALIDATION_ | 사업장 저장 거절 — 기관이 사유를 말하며 사업장 저장을 받아 주지 않았습니다(WORKPLACE_REJECTED). error.message 에 기관이 알려 준 사유가 오고 다음 단계 안내가 함께 옵니다. 사유대로 사업장 정보를 고친 뒤 같은 단계를 다시 저장합니다. | |
| INTERNAL_ | 접수번호 미발급 — 기관이 접수번호도 사유도 주지 않아 결과를 알 수 없습니다. 재시도보다 문의를 권합니다. 응답의 error.message 는 이 사유가 아니라 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')로 옵니다. | |
| VALIDATION_ | 선택값 오류 — 귀속연도·차수 같은 코드값 필드에 화면이 허용하지 않는 값을 보냈습니다(CHOICE_INVALID). 오류 메시지가 그 필드의 실제 허용값 목록을 함께 알려줍니다 - requirements 의 field_options 로도 미리 확인할 수 있습니다. |
14. 고용24 기업지원금 사전진단 조회work24. subsidy. diagnosis. search
MCP 도구 이름 work24__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
사업장 하나에 대해 사전진단이 있는 기업지원금 사업을 한 번에 조회해 사업별 적합 여부를 돌려줍니다.
- 고용24 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [고용24 로그인]
- 기관 조회가 실패한 사업은 작업 오류가 아니라 results[] 안에서 verdict:"undetermined" · can_apply:false · error 로 표시됩니다(다른 사업 결과는 그대로 옵니다).접속 실패· 시간 초과·5xx 응답이 전부 이 형태로 흡수되고 작업 자체는 실패하지 않습니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| application_ | number | 4 | N | 신청연도. 입력하지 않으면 올해입니다 | |
| business_ | string | - | N | 고용보험 사업장관리번호 11자리. 입력하지 않으면 로그인할 때 저장한 번호를 씁니다 | |
| programme_ | array | - | N | 진단할 지원금 사업 키 목록(예: w24_b0010). 입력하지 않으면 사전진단이 있는 모든 사업을 진단합니다 | |
| output_ | array | - | N | 이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다 |
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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| schema | string | 내부 스키마 식별자(고객 응답에 그대로 포함되는 값입니다) | |
| business_ | string | 사업장관리번호 | |
| application_ | string | 진단 기준 연도 | |
| catalog_ | string | 지원사업 카탈로그 확인 기준일 | |
| programme_ | number | 진단한 지원사업 수 | |
| summary | object | 판정 건수 요약 객체 - applicable(신청가능) · eligible(적격) · conditional(조건부) · ineligible(부적격) · undetermined(미확정) 각각의 사업 수 | |
| applicable_ | array | 신청 가능한 사업 키 목록 | |
| eligible_ | array | 적격 판정을 받은 사업 키 목록 | |
| applicable_ | array | 신청 가능하면서 이 API 로 신청 자동화까지 되는 사업 키 목록 - 다음 단계로 바로 갈 수 있는 사업입니다 | |
| results | array | 사업별 진단 결과 목록 - 각 행은 programme_key · programme_label_ko · category · automation(자동화 가능 여부) 과, 판정 상세(can_apply · message_ko · items 배열 - 항목별 충족 여부 · 근거 법령)를 담습니다 | |
| results[]. | string | 사업장관리번호 | |
| results[]. | string | number | boolean | object | array | null | 지원사업 | |
| results[]. | string | number | boolean | object | array | null | 분류 (값: new_hire = 신규채용, maternity_childcare = 출산 육아, reduced_flexible_hours = 단축 유연근무, employment_retention = 고용유지, conversion_transition = 정규직 산업 일자리전환) | |
| results[]. | string | 판정 (값: eligible = 적격, conditional = 조건부, ineligible = 부적격, undetermined = 미확정) | |
| results[]. | boolean | 신청 가능 여부 (값: true = 가능, false = 불가) | |
| results[]. | string | 안내 문구 | |
| results[]. | string | 자동화 가능 여부 | |
| warnings_ | array | 진단 전반에 대한 한국어 경고 문구 목록 | |
| automation_ | array | 진단 대상이 아닌 사업까지 포함한 전체 자동화 지원 범위 장부 |
{
"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_ | 세션 없음 — 고용24 세션이 없습니다. 고용24 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 세션 만료 — 고용24 세션이 만료됐습니다. 고용24 세션 로그인을 다시 호출합니다. | |
| VALIDATION_ | 사업장관리번호 확인 불가 — 사업장관리번호(business_management_no)를 생략했는데 계정에서 자동으로 확인할 수 없습니다. 값을 직접 지정합니다. | |
| VALIDATION_ | 지원사업 키 확인 불가 — programme_keys 로 보낸 사업 키 중 카탈로그에 없거나 아직 지원하지 않는 것이 있습니다. 값을 다시 확인합니다(생략하면 카탈로그 전체를 진단하므로 이 행은 값을 보낼 때만 해당합니다). |