자격 - 4대보험
1. 공통코드 목록 조회fourinsure. b1. common. com_ cd. list
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
분류 아이디 하나를 넣으면 기관 코드 찾기 창에 보이는 그 분류의 공통코드를 코드 값과 이름의 짝으로 돌려줍니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| com_ | string | Y | 공통코드 분류 id(예: B112, D114, A101) | |
| insurance_ | string | N | 보험 구분 필터(선택) | |
| levy_ | string | N | 부과 구분 코드 필터(선택) | |
| workplace_ | string | N | 사업장 구분 코드 필터(선택) |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: list-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.common.com_cd.list",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"com_cd_clsf_id": "<필수>"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- result.data 의 items(행마다 code 와 name)로 com_cd_clsf_id 분류의 코드 목록을 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| com_ | string | 조회한 공통코드 분류 id | |
| items | array | 조회 결과 행 배열 | |
| save_ | boolean | 기관 저장 수행 여부(조회라 항상 false) | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "fourinsure",
"action": "fourinsure.b1.common.com_cd.list",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 코드 없음 — 그 분류에 코드가 하나도 없으면 빈 목록이 아니라 이 오류로 끝납니다. com_cd_clsf_id 를 확인합니다. | |
| AUTH_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| VALIDATION_ | 필수 칸 누락 — 필수 칸(com_cd_clsf_id)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다. | |
| PROVIDER_ | 검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다. |
2. 자격취득 신고 입력 초안 검증fourinsure. b1. member_ qualification. acqs_ draft_ validate
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
입사자의 성명과 주민등록번호, 자격취득일, 보험별 값을 넣으면 저장 없이 점검해 빠진 항목과 형식 오류, 신고 가능 여부를 돌려줍니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
- params 를 빈 객체로 보내도 작업은 성공하지만, 그러면 필수 입력이 missing_required_fields 로 돌아오고 workflow_gate.input_ready 가 false 입니다.검증할 초안 값을 params 에 담아 보냅니다. 사용할 인증서는 account_link_id 로 지정합니다.
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 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| selected_ | array | N | 신고할 보험 목록(national_pension, health_insurance, employment_insurance, workers_compensation) | |
| applicant_ | string | N | 대상자 성명(한글) | |
| resident_ | string | N | 주민등록번호 | |
| rrno_ | string | N | 주민등록번호 앞자리 | |
| rrno_ | string | N | 주민등록번호 뒷자리 | |
| common_ | string | N | 공통 자격취득일 | |
| common_ | string | number | N | 공통 월 소득액. 저장할 때는 0 보다 큰 값을 입력해야 합니다 | |
| nationality_ | string | N | 국적 코드 | |
| nationality_ | string | N | 국적 | |
| stay_ | string | N | 체류자격 코드 | |
| stay_ | string | N | 체류자격 | |
| representative_ | string | boolean | N | 대표자 여부 | |
| national_ | object | N | 국민연금 | |
| national_ | string | number | N | 국민연금 소득월액 생략 시 기본값: null | |
| national_ | string | N | 국민연금 자격취득일 생략 시 기본값: "" | |
| national_ | string | N | 국민연금 자격취득부호 생략 시 기본값: "" | |
| national_ | string | N | 국민연금 자격취득 사유 이름입니다. 생략 시 기본값: "" | |
| national_ | string | boolean | N | 국민연금 취득월납부여부 생략 시 기본값: null | |
| national_ | string | N | 국민연금 특수직종부호 생략 시 기본값: "" | |
| national_ | string | N | 국민연금 특수직종 이름입니다. 생략 시 기본값: "" | |
| national_ | string | N | 국민연금 직역연금부호 생략 시 기본값: "" | |
| national_ | string | N | 특수직역연금 이름입니다. 생략 시 기본값: "" | |
| health_ | object | N | 건강보험 | |
| health_ | string | number | N | 건강보험 보수월액 생략 시 기본값: null | |
| health_ | string | N | 건강보험 자격취득일 생략 시 기본값: "" | |
| health_ | string | N | 건강보험 자격취득부호 생략 시 기본값: "" | |
| health_ | string | N | 건강보험 자격취득 사유 이름입니다. 생략 시 기본값: "" | |
| health_ | string | N | 건강보험 감면부호 생략 시 기본값: "" | |
| health_ | string | N | 건강보험 감면부호명 생략 시 기본값: "" | |
| health_ | string | N | 건강보험 회계코드 생략 시 기본값: "" | |
| health_ | string | N | 건강보험 회계명 생략 시 기본값: "" | |
| health_ | string | N | 건강보험 직종코드 생략 시 기본값: "" | |
| health_ | string | N | 건강보험 직종명 생략 시 기본값: "" | |
| employment_ | object | N | 고용보험 | |
| employment_ | string | number | N | 고용보험 월평균 보수 생략 시 기본값: null | |
| employment_ | string | N | 고용보험 자격취득일 생략 시 기본값: "" | |
| employment_ | string | N | 고용보험 직종 생략 시 기본값: "" | |
| employment_ | string | N | 고용보험 직종명 생략 시 기본값: "" | |
| employment_ | string | number | N | 고용보험 1주 소정근로시간 생략 시 기본값: null | |
| employment_ | string | N | 고용보험 비고코드 생략 시 기본값: "" | |
| employment_ | string | N | 고용보험 비고명 생략 시 기본값: "" | |
| employment_ | string | boolean | N | 고용보험 계약직 여부 생략 시 기본값: null | |
| employment_ | string | N | 고용보험 계약종료연월 생략 시 기본값: "" | |
| employment_ | string | N | 고용보험 보험료 부과구분 부호 생략 시 기본값: "" | |
| employment_ | string | N | 고용보험 보험료 부과구분 부호명 생략 시 기본값: "" | |
| employment_ | string | N | 고용보험 보험료 부과구분 사유코드 생략 시 기본값: "" | |
| employment_ | string | N | 고용보험 보험료 부과구분 사유명 생략 시 기본값: "" | |
| workers_ | object | N | 산재보험 | |
| workers_ | string | number | N | 산재보험 월평균 보수 생략 시 기본값: null | |
| workers_ | string | N | 산재보험 자격취득일 생략 시 기본값: "" | |
| workers_ | string | N | 산재보험 직종코드 생략 시 기본값: "" | |
| workers_ | string | N | 산재보험 직종명 생략 시 기본값: "" | |
| workers_ | string | number | N | 산재보험 1주 소정근로시간 생략 시 기본값: null | |
| workers_ | string | N | 산재보험 비고코드 생략 시 기본값: "" | |
| workers_ | string | N | 산재보험 비고명 생략 시 기본값: "" | |
| workers_ | string | boolean | N | 산재보험 계약직 여부 생략 시 기본값: null | |
| workers_ | string | N | 산재보험 계약종료연월 생략 시 기본값: "" | |
| workers_ | string | N | 산재보험 보험료 부과구분 부호 생략 시 기본값: "" | |
| workers_ | string | N | 산재보험 보험료 부과구분 부호명 생략 시 기본값: "" | |
| workers_ | string | N | 산재보험 보험료 부과구분 사유코드 생략 시 기본값: "" | |
| workers_ | string | N | 산재보험 보험료 부과구분 사유명 생략 시 기본값: "" |
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: acqs_draft_validate-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.acqs_draft_validate",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- 저장 · 신고 없이 입력만 검증합니다. result.data 의 missing_required_fields 와 field_errors 로 고칠 항목을, workflow_gate 의 input_ready 와 can_submit_report 로 다음 단계로 갈 수 있는지 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| feature_ | string | 기능 식별자 | |
| phase | string | 처리 단계(draft_validate) | |
| workflow_ | string | 처리 단계 식별자 | |
| route_ | string | 처리 방식 — live_context_local_validation(화면 계약을 불러와 서버에서 검증) | |
| source_ | string | 서버가 요청한 기관 화면 주소 | |
| current_ | string | 현재 화면 식별자 | |
| target_ | boolean | 대상 폼 준비 여부 | |
| business_ | object | 사업장 컨텍스트 객체 | |
| selected_ | array | 검증 대상으로 고른 보험 목록 | |
| enabled_ | array | 화면 기준 섹션 사용 가능 상태 배열(key · label · enabled) | |
| required_ | array | 화면 기준 필수 입력 항목 배열(field_key · label · section · required_when) | |
| missing_ | array | 빠진 필수 입력 항목 배열(required_fields 와 같은 모양) | |
| field_ | array | 입력 누락 · 형식 오류 배열(field_key · label · section · message) | |
| warnings | array | 주의 메시지 배열(code · section · message · field_key) | |
| screen_ | array | 화면 확인 메모 배열 | |
| field_ | object | 입력 키와 화면 필드의 대응 맵 | |
| normalized_ | object | 정규화한 입력값 맵 | |
| draft_ | object | 화면 필드에 채울 값 미리보기 맵 | |
| followup_ | array | 기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다 | |
| workflow_ | object | 진행 판정 객체(input_ready · blocking_issue_count · can_save=false · can_submit_report · report_status · blocked_reason) | |
| safety | object | 안전 플래그 객체(input_only=true · save_executed=false · submit_executed=false) | |
| implementation_ | string | 구현 상태 식별자 |
// result.data
{
"success": true,
"feature_name": "...",
"phase": "draft_validate",
"workflow_step": "member_qualification_acquisition_draft_validated",
"route_kind": "live_context_local_validation",
"source_url": "...",
"current_view": "...",
"target_ready": true,
"business_context": {},
"selected_insurances": [],
"enabled_sections": [],
"required_fields": [],
"missing_required_fields": [],
"field_errors": [],
"warnings": [],
"screen_notes": [],
"field_bindings": {},
"normalized_input": {},
"draft_form_preview": {},
"followup_endpoints": [],
"workflow_gate": {},
"safety": {},
"implementation_status": "implemented_input_only_draft_validation"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. |
3. 자격취득 입력 서식 조회fourinsure. b1. member_ qualification. acqs_ init
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
가입자 자격취득 신고서 화면을 열어 미리 채워진 사업장 정보와 보험별 가입 여부, 수정할 수 없는 항목을 돌려줍니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
- params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.
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 와 함께 쓰지 않습니다. |
추가 파라미터가 없습니다. params 는 {} 로 보냅니다.
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: acqs_init-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.acqs_init",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- result.data 에서 입력 항목(fields)과 화면 정보를 확인해 다음 단계(fourinsure.b1.member_qualification.acqs_draft_validate, fourinsure.b1.member_qualification.acqs_member_lookup, fourinsure.b1.member_qualification.acqs_precheck, fourinsure.b1.member_qualification.acqs_save)의 요청 본문을 만듭니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| page | object | 화면 페이지 메타 객체 | |
| forms | array | form 메타데이터 배열 | |
| fields | array | 입력 필드 계약 배열 | |
| semantic_ | array | 의미 단위 입력 컨트롤 배열 | |
| semantic_ | object | 의미 필드 키-값 맵 | |
| semantic_ | number | 의미 필드 개수 | |
| csrf_ | boolean | CSRF 토큰 존재 여부 | |
| followup_ | array | 기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다 | |
| navigation_ | array | 화면 내비게이션 단계 배열 | |
| current_ | string | 현재 화면 식별자 | |
| target_ | boolean | 대상 폼 준비 여부 | |
| raw_ | number | 원본 HTML 길이 | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
// result.data (form contract — 주요 필드)
{
"success": true,
"current_view": "target_form",
"target_ready": true,
"csrf_token_present": true,
"semantic_field_count": 52,
"page": {},
"forms": [],
"fields": [{ "tag": "input", "name": "dclrmst[cvrcNo]", "required": false }],
"semantic_fields": [],
"semantic_payload": {},
"followup_endpoints": [{ "url": "https://..." }],
"navigation_steps": [],
"raw_html_len": 0,
"source_url": "https://..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. |
4. 자격취득 가입자 조회fourinsure. b1. member_ qualification. acqs_ member_ lookup
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
입사자의 성명과 주민등록번호를 넣으면 자격취득 초안 저장에 쓸 자격키와 보험별 기존 취득일, 상실일을 돌려줍니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
- 가입자를 찾지 못하면 작업은 성공하고 lookup_ok 가 false, rrkey 는 빈 값입니다. 기관 안내 문장이 있으면 alert_message 에 옵니다.
- REST 요청 표와 MCP 도구 규격의 필수 표시가 다릅니다.MCP 도구의 입력 규격(inputSchema)은 resident_registration_number 를 필수로 표시하므로 arguments 에 반드시 포함하세요. 값은 REST 와 같은 작업 제출 경로에서 검사합니다.나머지 필수 입력과 업무 조건은 아래 요청 표를 함께 따릅니다.
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 파라미터 표의 필수 항목을 채우고 resident_registration_number 또는 rrno_front 중 하나 이상, resident_registration_number 또는 rrno_back 중 하나 이상을 함께 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| applicant_ | string | - | Y | 대상자 성명(한글) | |
| resident_ | string | - | 조건부 | 주민등록번호 13자리 | |
| rrno_ | string | - | 조건부 | 주민등록번호 앞자리 | |
| rrno_ | string | - | 조건부 | 주민등록번호 뒷자리 | |
| declaration_ | string | 8 | N | 신고 적용일(비우면 기관 화면 값을 쓴다) | |
| bpmno | string | - | N | 사업장관리번호(비우면 기관 화면 값을 쓴다) | |
| cvrc_ | string | - | N | 작성 중인 초안의 접수번호(없으면 비운다) | |
| up_ | string | - | N | 상위 접수번호(비우면 기관 화면 값을 쓴다) |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: acqs_member_lookup-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.acqs_member_lookup",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"applicant_name": "<필수>",
"resident_registration_number": "<필수>"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- 기관에 저장하거나 신고하지 않는 조회입니다.result.data 의 lookup_ok 가 true 면 rrkey 를 받고, qualification_acquisition_dates 와 qualification_loss_dates 로 보험별 기존 취득일과 상실일을, representative_yn 으로 대표자 여부를 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| lookup_ | boolean | 가입자를 찾았는지 여부(false 면 rrkey 가 빈 값) | |
| alert_ | string | 기관이 돌려준 안내 문장(없으면 빈 값) | |
| rrkey | string | 가입자 자격키, 같은 신고의 다음 조회에 그대로 넣는 값 | |
| applicant_ | string | 조회한 대상자 성명 | |
| rrno_ | string | 가린 주민등록번호 | |
| representative_ | boolean | 대표자 여부 | |
| is_ | string | 가족 여부 표시(기관 값 그대로) | |
| status_ | string | 상태 코드 | |
| exists | object | 보험별 존재 표시 맵(기관이 돌려준 값 그대로) | |
| qualification_ | object | 보험별 기존 자격취득일 맵 | |
| qualification_ | object | 보험별 기존 자격상실일 맵 | |
| save_ | boolean | 기관 저장 수행 여부(조회라 항상 false) | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.acqs_member_lookup",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| VALIDATION_ | 필수 칸 누락 — 필수 칸(applicant_name)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다. | |
| PROVIDER_ | 검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다. |
5. 자격취득 사전 확인fourinsure. b1. member_ qualification. acqs_ precheck
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
자격취득 신고서를 쓰기 전에 상위 접수번호를 넣으면 그 번호에 이미 작성된 건수를 돌려줍니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]확인할 기존 상위 접수번호를 up_cvrc_no 로 보냅니다. 생략하면 자격취득 화면에 있는 값을 쓰고, 화면에도 없으면 확인 대상이 아니라고 답합니다(check_applicable 이 false).화면의 값은 fourinsure.b1.member_qualification.acqs_init 응답의 fields 에서 name 이 dclrmst[upCvrcNo] 인 항목의 value 로 확인할 수 있습니다.
- 유효한 상위 접수번호로 확인한 작성 건수가 없으면 count 가 0, check_applicable 이 true 로 옵니다. 실패가 아닙니다.
- 작업은 성공하고 result.data 의 check_applicable 이 false, count 는 0, up_cvrc_no 는 빈 값입니다.요청의 up_cvrc_no 와 자격취득 화면의 상위 접수번호가 모두 비어 있으면 기관에 묻지 않습니다.이 count 0 은 작성된 건이 없다는 확인이 아니라 확인하지 않았다는 뜻이므로, 중복 확인 결과로 쓰기 전에 check_applicable 을 먼저 봅니다.
- params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| up_ | string | N | 확인할 상위 접수번호(비우면 기관 화면 값을 쓴다. 화면에도 없으면 확인 대상이 아니라고 답한다) |
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: acqs_precheck-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.acqs_precheck",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- 기관에 저장하거나 신고하지 않는 확인입니다.result.data 의 count 가 up_cvrc_no(상위 접수번호)에 이미 작성된 건수입니다. up_cvrc_no 를 보내지 않으면 자격취득 화면에 있는 값을 씁니다.요청과 화면 모두에 값이 없으면 기관에 묻지 않고 확인 대상이 아니라고 답합니다(아래 「확인 대상 아님」).
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| up_ | string | 확인한 상위 접수번호 | |
| check_ | boolean | 사전 확인 대상인지 여부. 상위 접수번호가 요청에도 자격취득 화면에도 없으면 false 이고 기관에 묻지 않습니다. 이때 count 는 0 이지만 확인한 결과가 아닙니다. | |
| count | number | 상위 접수번호에 이미 작성된 건수 | |
| save_ | boolean | 기관 저장 수행 여부(조회라 항상 false) | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.acqs_precheck",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. |
6. 자격취득 초안 저장fourinsure. b1. member_ qualification. acqs_ save
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
입사자 자격키와 성명, 주민등록번호, 자격취득일, 월 보수, 건강보험 취득부호, 고용보험 직종을 넣으면 자격취득 신고서를 정보연계센터에 초안으로 저장하고 접수번호를 받습니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
- dry_run 을 true 로 보내면 기관에 보내지 않고 저장할 내용을 result.data 의 preview 로 돌려줍니다(save_executed=false).이때는 confirm 이 필요 없습니다.
- REST 요청 표와 MCP 도구 규격의 필수 표시가 다릅니다.MCP 도구의 입력 규격(inputSchema)은 common_acquisition_date, common_monthly_amount, epi_occupation_code, epi_occupation_name, health_insurance, resident_registration_number 를 필수로 표시하므로 arguments 에 반드시 포함하세요.값은 REST 와 같은 작업 제출 경로에서 검사합니다. 나머지 필수 입력과 업무 조건은 아래 요청 표를 함께 따릅니다.
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 파라미터 표의 필수 항목을 채우고 resident_registration_number 또는 rrno_front 중 하나 이상, resident_registration_number 또는 rrno_back 중 하나 이상, common_acquisition_date 또는 hire_date 중 하나 이상, common_monthly_amount 또는 monthly_wage 중 하나 이상을 함께 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| selected_ | array | - | N | 신고할 보험 목록(national_pension, health_insurance, employment_insurance, workers_compensation, 기본은 네 보험 모두, 이미 취득 중인 보험은 뺀다) | |
| applicant_ | string | - | Y | 대상자 성명(한글) | |
| resident_ | string | - | 조건부 | 주민등록번호 13자리 | |
| rrno_ | string | - | 조건부 | 주민등록번호 앞자리 | |
| rrno_ | string | - | 조건부 | 주민등록번호 뒷자리 | |
| common_ | string | 8 | 조건부 | 자격취득일(입사일) | |
| common_ | string | number | - | 조건부 | 공통 월 소득액. 저장할 때는 0 보다 큰 값을 입력해야 합니다 | |
| nationality_ | string | - | N | 국적 코드 | |
| nationality_ | string | - | N | 국적 | |
| stay_ | string | - | N | 체류자격 코드 | |
| stay_ | string | - | N | 체류자격 | |
| representative_ | string | boolean | - | N | 대표자 여부 | |
| national_ | object | - | N | 국민연금 | |
| national_ | string | number | - | N | 국민연금 소득월액 생략 시 기본값: null | |
| national_ | string | - | N | 국민연금 자격취득일 생략 시 기본값: "" | |
| national_ | string | - | N | 국민연금 자격취득부호 생략 시 기본값: "" | |
| national_ | string | - | N | 국민연금 자격취득 사유 이름입니다. 생략 시 기본값: "" | |
| national_ | string | boolean | - | N | 국민연금 취득월납부여부 생략 시 기본값: null | |
| national_ | string | - | N | 국민연금 특수직종부호 생략 시 기본값: "" | |
| national_ | string | - | N | 국민연금 특수직종 이름입니다. 생략 시 기본값: "" | |
| national_ | string | - | N | 국민연금 직역연금부호 생략 시 기본값: "" | |
| national_ | string | - | N | 특수직역연금 이름입니다. 생략 시 기본값: "" | |
| health_ | object | - | N | 건강보험 취득 사유. 코드와 이름을 둘 다 입력합니다. 코드는 4대보험 공통코드 목록 조회 결과에서 받습니다 | |
| health_ | string | number | - | N | 건강보험 보수월액 생략 시 기본값: null | |
| health_ | string | - | N | 건강보험 자격취득일 생략 시 기본값: "" | |
| health_ | string | - | 조건부 | 건강보험을 신고할 때 꼭 보내는 취득 사유 코드입니다(예: 00). 이름과 함께 보내야 하고 없으면 저장하지 않고 거절합니다. selected_insurances 를 보내지 않으면 건강보험도 신고합니다 | |
| health_ | string | - | 조건부 | 위 코드에 해당하는 건강보험 취득 사유 이름입니다. 코드와 이름을 둘 다 보내야 하며 하나만 보내도 저장하지 않고 거절합니다 | |
| health_ | string | - | N | 건강보험 감면부호 생략 시 기본값: "" | |
| health_ | string | - | N | 건강보험 감면부호명 생략 시 기본값: "" | |
| health_ | string | - | N | 건강보험 회계코드 생략 시 기본값: "" | |
| health_ | string | - | N | 건강보험 회계명 생략 시 기본값: "" | |
| health_ | string | - | N | 건강보험 직종코드 생략 시 기본값: "" | |
| health_ | string | - | N | 건강보험 직종명 생략 시 기본값: "" | |
| employment_ | object | - | N | 고용보험 | |
| employment_ | string | number | - | N | 고용보험 월평균 보수 생략 시 기본값: null | |
| employment_ | string | - | N | 고용보험 자격취득일 생략 시 기본값: "" | |
| employment_ | string | - | N | 고용보험 직종 생략 시 기본값: "" | |
| employment_ | string | - | N | 고용보험 직종명 생략 시 기본값: "" | |
| employment_ | string | number | - | N | 고용보험 1주 소정근로시간 생략 시 기본값: null | |
| employment_ | string | - | N | 고용보험 비고코드 생략 시 기본값: "" | |
| employment_ | string | - | N | 고용보험 비고명 생략 시 기본값: "" | |
| employment_ | string | boolean | - | N | 고용보험 계약직 여부 생략 시 기본값: null | |
| employment_ | string | - | N | 고용보험 계약종료연월 생략 시 기본값: "" | |
| employment_ | string | - | N | 고용보험 보험료 부과구분 부호 생략 시 기본값: "" | |
| employment_ | string | - | N | 고용보험 보험료 부과구분 부호명 생략 시 기본값: "" | |
| employment_ | string | - | N | 고용보험 보험료 부과구분 사유코드 생략 시 기본값: "" | |
| employment_ | string | - | N | 고용보험 보험료 부과구분 사유명 생략 시 기본값: "" | |
| workers_ | object | - | N | 산재보험 | |
| workers_ | string | number | - | N | 산재보험 월평균 보수 생략 시 기본값: null | |
| workers_ | string | - | N | 산재보험 자격취득일 생략 시 기본값: "" | |
| workers_ | string | - | N | 산재보험 직종코드 생략 시 기본값: "" | |
| workers_ | string | - | N | 산재보험 직종명 생략 시 기본값: "" | |
| workers_ | string | number | - | N | 산재보험 1주 소정근로시간 생략 시 기본값: null | |
| workers_ | string | - | N | 산재보험 비고코드 생략 시 기본값: "" | |
| workers_ | string | - | N | 산재보험 비고명 생략 시 기본값: "" | |
| workers_ | string | boolean | - | N | 산재보험 계약직 여부 생략 시 기본값: null | |
| workers_ | string | - | N | 산재보험 계약종료연월 생략 시 기본값: "" | |
| workers_ | string | - | N | 산재보험 보험료 부과구분 부호 생략 시 기본값: "" | |
| workers_ | string | - | N | 산재보험 보험료 부과구분 부호명 생략 시 기본값: "" | |
| workers_ | string | - | N | 산재보험 보험료 부과구분 사유코드 생략 시 기본값: "" | |
| workers_ | string | - | N | 산재보험 보험료 부과구분 사유명 생략 시 기본값: "" | |
| rrkey | string | - | Y | 자격취득 가입자 조회 결과의 rrkey | |
| cmd | string | - | N | 저장 구분(Regist 신규, Modify 수정) | |
| cvrc_ | string | - | N | 수정할 초안의 접수번호(cmd 가 Modify 일 때 필수) | |
| hire_ | string | - | 조건부 | 입사일(common_acquisition_date 대신 보낼 수 있다) | |
| monthly_ | string | number | - | 조건부 | 월 보수액(common_monthly_amount 대신 보낼 수 있다) | |
| weekly_ | string | number | - | N | 주 소정근로시간(비우면 40) | |
| epi_ | string | - | N | 고용보험 직종 코드(공통코드 목록 조회로 받는다, 고용보험을 신고할 때 필수) | |
| epi_ | string | - | N | 고용보험 직종 이름(고용보험을 신고할 때 필수) | |
| iai_ | string | - | N | 산재보험 직종 코드(비우면 고용보험 직종을 쓴다) | |
| iai_ | string | - | N | 산재보험 직종 이름(비우면 고용보험 직종을 쓴다) | |
| nps_ | string | - | N | 국민연금 기존 자격취득일(가입자 조회 결과, 상실일 없이 있으면 그 보험은 신고에서 뺀다) | |
| nhi_ | string | - | N | 건강보험 기존 자격취득일(가입자 조회 결과, 상실일 없이 있으면 그 보험은 신고에서 뺀다) | |
| epi_ | string | - | N | 고용보험 기존 자격취득일(가입자 조회 결과, 상실일 없이 있으면 그 보험은 신고에서 뺀다) | |
| iai_ | string | - | N | 산재보험 기존 자격취득일(가입자 조회 결과, 상실일 없이 있으면 그 보험은 신고에서 뺀다) | |
| nps_ | string | - | N | 국민연금 기존 자격상실일(가입자 조회 결과) | |
| nhi_ | string | - | N | 건강보험 기존 자격상실일(가입자 조회 결과) | |
| epi_ | string | - | N | 고용보험 기존 자격상실일(가입자 조회 결과) | |
| iai_ | string | - | N | 산재보험 기존 자격상실일(가입자 조회 결과) | |
| exists_ | string | - | N | 국민연금 존재 표시(가입자 조회 결과의 exists 값 그대로) | |
| exists_ | string | - | N | 건강보험 존재 표시(가입자 조회 결과의 exists 값 그대로) | |
| exists_ | string | - | N | 고용보험 존재 표시(가입자 조회 결과의 exists 값 그대로) | |
| exists_ | string | - | N | 산재보험 존재 표시(가입자 조회 결과의 exists 값 그대로) | |
| confirm | boolean | - | N | true 여야 저장한다. 없으면 저장하지 않고 저장할 내용 미리보기와 함께 거절한다 | |
| dry_ | boolean | - | N | true 면 기관에 보내지 않고 저장할 내용만 돌려준다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: acqs_save-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.acqs_save",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"applicant_name": "<필수>",
"rrkey": "<필수>",
"resident_registration_number": "<필수>",
"common_acquisition_date": "<필수>",
"common_monthly_amount": "<필수: string | number>"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- 자격취득 신고 초안이 정보연계센터에 저장되며 저장한 초안을 되돌리는 API 는 없습니다.result.data 의 save_ok 가 true 이고 cvrc_no 에 기관이 새로 발번한 접수번호가 옵니다. 기관 전송은 하지 않습니다(submit_executed=false).
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| save_ | boolean | 기관이 초안 저장을 받아들였는지 여부(새 접수번호를 받았을 때만 true) | |
| save_ | boolean | 기관에 저장 요청을 보냈는지 여부(dry_run 이면 false) | |
| submit_ | boolean | 기관 전송 수행 여부(이 API 는 전송하지 않아 항상 false) | |
| dry_ | boolean | 접수 없이 검증만 한 호출이면 true | |
| alert_ | string | 기관이 돌려준 안내 문장(없으면 빈 값) | |
| cvrc_ | string | 기관이 새로 발번한 신고 초안 접수번호(save_ok 가 true 일 때만 값이 있다) | |
| bpmno | string | 사업장관리번호(save_ok 가 true 일 때만 값이 있다) | |
| dong_ | string | 기관이 돌려준 동 코드 | |
| preview | object | 기관에 보낼 저장 내용 미리보기 맵 | |
| source_ | string | 서버가 요청한 기관 화면 주소 | |
| outcome | string | 기관 쓰기 판정입니다. 새 접수번호를 받아 저장을 확인했으면 confirmed 입니다. 확인하지 못하면 작업 API 는 결과 대신 실패(error_code PROVIDER_OUTCOME_UNCONFIRMED, 재시도 불가)로 끝나고, REST 응답은 이 칸이 unconfirmed 이고 success 가 false 입니다. 실제 저장 때만 옵니다. dry_run 이면 이 칸이 없습니다 | |
| message_ | string | REST 응답에서 outcome 이 unconfirmed 일 때만 값이 있는 안내 문장입니다. 작업 API 는 이 문장을 실패의 오류 문장 앞부분으로 줍니다. 실제 저장 때만 옵니다. dry_run 이면 이 칸이 없습니다 | |
| how_ | string | REST 응답에서 outcome 이 unconfirmed 일 때만 값이 있습니다. 다시 저장하기 전에 방금 저장이 됐는지 확인하는 방법을 알려 줍니다. 작업 API 는 이 문장을 실패의 오류 문장 뒤에 붙여 줍니다. 실제 저장 때만 옵니다. dry_run 이면 이 칸이 없습니다 | |
| action | string | 작업 API 결과에만 있는 칸입니다. 저장을 확인했을 때 이 액션 이름이 그대로 옵니다. REST 응답에는 없습니다. 실제 저장 때만 옵니다. dry_run 이면 이 칸이 없습니다 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.acqs_save",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 확인 필요 — confirm 없이 보내면 저장하지 않고 이 오류로 끝나며, error.message 에 저장될 내용의 [미리보기] 가 담깁니다. 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 confirm=true 를 더해 다시 호출합니다. | |
| POLICY_ | 일시 중지 — 상품이 일시 중지 상태입니다. 다시 보내도 풀리지 않습니다. | |
| AUTH_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 결과 불명 — 저장 요청을 보낸 뒤 기관이 새 접수번호를 주지 않거나 오류로 답하거나 연결이 끊기면, 다시 실행하지 말고 자격취득 신고 화면에서 방금 저장한 초안이 있는지 먼저 확인합니다. 기관이 오류 응답을 보내거나 응답이 오지 않거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 결과 불명 — 저장 요청을 보낸 뒤 기관이 새 접수번호를 주지 않거나 오류로 답하거나 연결이 끊기면, 다시 실행하지 말고 자격취득 신고 화면에서 방금 저장한 초안이 있는지 먼저 확인합니다. 기관이 오류 응답을 보내거나 응답이 오지 않거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| VALIDATION_ | 필수 칸 누락 — 필수 칸(applicant_name, rrkey)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다. | |
| PROVIDER_ | 검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다. |
7. 가입자 내용변경 신고 입력 초안 검증fourinsure. b1. member_ qualification. chg_ draft_ validate
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
정정할 가입자의 성명과 주민등록번호, 변경부호, 변경후 값, 변경일자를 넣으면 저장 없이 점검해 빠진 항목과 오류, 신고 가능 여부를 돌려줍니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
- params 를 빈 객체로 보내도 작업은 성공하지만, 그러면 필수 입력이 missing_required_fields 로 돌아오고 workflow_gate.input_ready 가 false 입니다.검증할 초안 값을 params 에 담아 보냅니다. 사용할 인증서는 account_link_id 로 지정합니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| selected_ | array | N | 반영 보험 | |
| applicant_ | string | N | 성명 | |
| resident_ | string | N | 주민등록번호 | |
| rrno_ | string | N | 주민등록번호 앞자리 | |
| rrno_ | string | N | 주민등록번호 뒷자리 | |
| change_ | string | N | 변경부호 | |
| change_ | string | N | 변경전 | |
| change_ | string | N | 변경후 | |
| change_ | string | N | 변경일자 | |
| modification_ | string | boolean | N | 변경 내용 확인 여부입니다. 생략하면 N 으로 정리됩니다. 이 값이 있어도 검증 호출은 저장이나 신고를 실행하지 않습니다 |
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: chg_draft_validate-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.chg_draft_validate",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- 저장 · 신고 없이 입력만 검증합니다. result.data 의 missing_required_fields 와 field_errors 로 고칠 항목을, workflow_gate 의 input_ready 와 can_submit_report 로 다음 단계로 갈 수 있는지 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| feature_ | string | 기능 식별자 | |
| phase | string | 처리 단계(draft_validate) | |
| workflow_ | string | 처리 단계 식별자 | |
| route_ | string | 처리 방식 — live_context_local_validation(화면 계약을 불러와 서버에서 검증) | |
| source_ | string | 서버가 요청한 기관 화면 주소 | |
| current_ | string | 현재 화면 식별자 | |
| target_ | boolean | 대상 폼 준비 여부 | |
| business_ | object | 사업장 컨텍스트 객체 | |
| selected_ | array | 검증 대상으로 고른 보험 목록 | |
| enabled_ | array | 화면 기준 섹션 사용 가능 상태 배열(key · label · enabled) | |
| required_ | array | 화면 기준 필수 입력 항목 배열(field_key · label · section · required_when) | |
| missing_ | array | 빠진 필수 입력 항목 배열(required_fields 와 같은 모양) | |
| field_ | array | 입력 누락 · 형식 오류 배열(field_key · label · section · message) | |
| warnings | array | 주의 메시지 배열(code · section · message · field_key) | |
| screen_ | array | 화면 확인 메모 배열 | |
| field_ | object | 입력 키와 화면 필드의 대응 맵 | |
| normalized_ | object | 정규화한 입력값 맵 | |
| draft_ | object | 화면 필드에 채울 값 미리보기 맵 | |
| followup_ | array | 기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다 | |
| workflow_ | object | 진행 판정 객체(input_ready · blocking_issue_count · can_save=false · can_submit_report · report_status · blocked_reason) | |
| safety | object | 안전 플래그 객체(input_only=true · save_executed=false · submit_executed=false) | |
| implementation_ | string | 구현 상태 식별자 |
// result.data
{
"success": true,
"feature_name": "...",
"phase": "draft_validate",
"workflow_step": "member_qualification_change_draft_validated",
"route_kind": "live_context_local_validation",
"source_url": "...",
"current_view": "...",
"target_ready": true,
"business_context": {},
"selected_insurances": [],
"enabled_sections": [],
"required_fields": [],
"missing_required_fields": [],
"field_errors": [],
"warnings": [],
"screen_notes": [],
"field_bindings": {},
"normalized_input": {},
"draft_form_preview": {},
"followup_endpoints": [],
"workflow_gate": {},
"safety": {},
"implementation_status": "implemented_input_only_draft_validation"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. |
8. 가입자 내용변경 입력 서식 조회fourinsure. b1. member_ qualification. chg_ init
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
가입자 내용변경 신고서 화면을 열어 변경 항목별 보험 변경후 입력란과 특수직종 선택 목록, 미리 채워진 사업장 값을 돌려줍니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
- params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.
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 와 함께 쓰지 않습니다. |
추가 파라미터가 없습니다. params 는 {} 로 보냅니다.
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: chg_init-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.chg_init",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- result.data 에서 입력 항목(fields)과 화면 정보를 확인해 다음 단계(fourinsure.b1.member_qualification.chg_draft_validate)의 요청 본문을 만듭니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| page | object | 화면 페이지 메타 객체 | |
| forms | array | form 메타데이터 배열 | |
| fields | array | 입력 필드 계약 배열 | |
| semantic_ | array | 의미 단위 입력 컨트롤 배열 | |
| semantic_ | object | 의미 필드 키-값 맵 | |
| semantic_ | number | 의미 필드 개수 | |
| csrf_ | boolean | CSRF 토큰 존재 여부 | |
| followup_ | array | 기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다 | |
| navigation_ | array | 화면 내비게이션 단계 배열 | |
| current_ | string | 현재 화면 식별자 | |
| target_ | boolean | 대상 폼 준비 여부 | |
| raw_ | number | 원본 HTML 길이 | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
// result.data
{
"success": true,
"page": {},
"forms": [],
"fields": [],
"semantic_fields": [],
"semantic_payload": {},
"semantic_field_count": 1,
"csrf_token_present": true,
"followup_endpoints": [],
"navigation_steps": [],
"current_view": "...",
"target_ready": true,
"raw_html_len": 0,
"source_url": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. |
9. 피부양자 자격 신고 입력 초안 검증fourinsure. b1. member_ qualification. dependent_ draft_ validate
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
취득 또는 상실 구분, 직장가입자, 피부양자 명단, 연락처를 넣으면 빠진 필수 항목과 형식 오류, 신고 가능 여부를 돌려줍니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
- params 를 빈 객체로 보내도 작업은 성공하지만, 그러면 필수 입력이 missing_required_fields 로 돌아오고 workflow_gate.input_ready 가 false 입니다.검증할 초안 값을 params 에 담아 보냅니다. 사용할 인증서는 account_link_id 로 지정합니다.
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 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| action_ | string | N | 취득 또는 상실 구분 | |
| applicant_ | string | N | 직장가입자 성명입니다. 피부양자 성명은 dependents 의 name 에 보냅니다 | |
| resident_ | string | N | 주민등록번호 | |
| rrno_ | string | N | 주민등록번호 앞자리 | |
| rrno_ | string | N | 주민등록번호 뒷자리 | |
| report_ | string | N | 신고일자 | |
| reporter_ | string | N | 신고인 성명 | |
| bplc_ | string | N | 사업장 전화번호 (3칸 중 1번째) | |
| bplc_ | string | N | 사업장 전화번호 (3칸 중 2번째) | |
| bplc_ | string | N | 사업장 전화번호 (3칸 중 3번째) | |
| bplc_ | string | N | 사업장 팩스번호 (3칸 중 1번째) | |
| bplc_ | string | N | 사업장 팩스번호 (3칸 중 2번째) | |
| bplc_ | string | N | 사업장 팩스번호 (3칸 중 3번째) | |
| home_ | string | N | 자택 전화번호 (3칸 중 1번째) | |
| home_ | string | N | 자택 전화번호 (3칸 중 2번째) | |
| home_ | string | N | 자택 전화번호 (3칸 중 3번째) | |
| co_ | string | N | 직장 전화번호 (3칸 중 1번째) | |
| co_ | string | N | 직장 전화번호 (3칸 중 2번째) | |
| co_ | string | N | 직장 전화번호 (3칸 중 3번째) | |
| mbl_ | string | N | 휴대전화번호 (3칸 중 1번째) | |
| mbl_ | string | N | 휴대전화번호 (3칸 중 2번째) | |
| mbl_ | string | N | 휴대전화번호 (3칸 중 3번째) | |
| dependents | array | N | 피부양자 | |
| dependents[]. | string | N | 피부양자 주민등록번호입니다. 분리 입력 시 rrno_front 와 rrno_back 을 함께 보냅니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 피부양자 주민등록번호 앞자리입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 피부양자 주민등록번호 뒷자리입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 피부양자 성명입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 가입자와의 관계 코드입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 가입자와의 관계 이름입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 피부양자 자격취득일입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 피부양자 취득 사유 코드입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 피부양자 취득 사유 이름입니다. 생략 시 기본값: "" | |
| dependents[]. | string | boolean | N | 첨부서류 필요 여부입니다. 생략 시 기본값: null | |
| dependents[]. | string | N | 장애인 또는 국가유공자 구분 코드입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 장애인 또는 국가유공자 구분 이름입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 장애 또는 보훈 등급 코드입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 장애 또는 보훈 등급 이름입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 장애인 또는 국가유공자 등록일입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 국적 코드입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 국적 이름입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 체류자격 코드입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 체류자격 이름입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 체류기간 시작일입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 체류기간 종료일입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 피부양자 자격상실일입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 피부양자 상실 사유 코드입니다. 생략 시 기본값: "" | |
| dependents[]. | string | N | 피부양자 상실 사유 이름입니다. 생략 시 기본값: "" |
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: dependent_draft_validate-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.dependent_draft_validate",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- 저장 · 신고 없이 입력만 검증합니다. result.data 의 missing_required_fields 와 field_errors 로 고칠 항목을, workflow_gate 의 input_ready 와 can_submit_report 로 다음 단계로 갈 수 있는지 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| feature_ | string | 기능 식별자 | |
| phase | string | 처리 단계(draft_validate) | |
| workflow_ | string | 처리 단계 식별자 | |
| route_ | string | 처리 방식 — live_context_local_validation(화면 계약을 불러와 서버에서 검증) | |
| source_ | string | 서버가 요청한 기관 화면 주소 | |
| current_ | string | 현재 화면 식별자 | |
| target_ | boolean | 대상 폼 준비 여부 | |
| business_ | object | 사업장 컨텍스트 객체 | |
| selected_ | array | 검증 대상으로 고른 보험 목록 | |
| enabled_ | array | 화면 기준 섹션 사용 가능 상태 배열(key · label · enabled) | |
| required_ | array | 화면 기준 필수 입력 항목 배열(field_key · label · section · required_when) | |
| missing_ | array | 빠진 필수 입력 항목 배열(required_fields 와 같은 모양) | |
| field_ | array | 입력 누락 · 형식 오류 배열(field_key · label · section · message) | |
| warnings | array | 주의 메시지 배열(code · section · message · field_key) | |
| screen_ | array | 화면 확인 메모 배열 | |
| field_ | object | 입력 키와 화면 필드의 대응 맵 | |
| normalized_ | object | 정규화한 입력값 맵 | |
| draft_ | object | 화면 필드에 채울 값 미리보기 맵 | |
| followup_ | array | 기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다 | |
| workflow_ | object | 진행 판정 객체(input_ready · blocking_issue_count · can_save=false · can_submit_report · report_status · blocked_reason) | |
| safety | object | 안전 플래그 객체(input_only=true · save_executed=false · submit_executed=false) | |
| implementation_ | string | 구현 상태 식별자 |
// result.data
{
"success": true,
"feature_name": "...",
"phase": "draft_validate",
"workflow_step": "member_qualification_dependent_draft_validated",
"route_kind": "live_context_local_validation",
"source_url": "...",
"current_view": "...",
"target_ready": true,
"business_context": {},
"selected_insurances": [],
"enabled_sections": [],
"required_fields": [],
"missing_required_fields": [],
"field_errors": [],
"warnings": [],
"screen_notes": [],
"field_bindings": {},
"normalized_input": {},
"draft_form_preview": {},
"followup_endpoints": [],
"workflow_gate": {},
"safety": {},
"implementation_status": "implemented_input_only_draft_validation"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. |
10. 피부양자 자격 취득/상실 입력 서식 조회fourinsure. b1. member_ qualification. dependent_ init
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
로그인한 연동으로 부르면 건강보험 피부양자 신고서 화면의 신고서 종류, 채워진 사업장 정보와 신고일, 빈 가입자와 연락처 칸을 받습니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
- params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.
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 와 함께 쓰지 않습니다. |
추가 파라미터가 없습니다. params 는 {} 로 보냅니다.
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: dependent_init-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.dependent_init",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- result.data 에서 입력 항목(fields)과 화면 정보를 확인해 다음 단계(fourinsure.b1.member_qualification.dependent_draft_validate)의 요청 본문을 만듭니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| page | object | 화면 페이지 메타 객체 | |
| forms | array | form 메타데이터 배열 | |
| fields | array | 입력 필드 계약 배열 | |
| semantic_ | array | 의미 단위 입력 컨트롤 배열 | |
| semantic_ | object | 의미 필드 키-값 맵 | |
| semantic_ | number | 의미 필드 개수 | |
| csrf_ | boolean | CSRF 토큰 존재 여부 | |
| followup_ | array | 기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다 | |
| navigation_ | array | 화면 내비게이션 단계 배열 | |
| current_ | string | 현재 화면 식별자 | |
| target_ | boolean | 대상 폼 준비 여부 | |
| raw_ | number | 원본 HTML 길이 | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
// result.data
{
"success": true,
"page": {},
"forms": [],
"fields": [],
"semantic_fields": [],
"semantic_payload": {},
"semantic_field_count": 1,
"csrf_token_present": true,
"followup_endpoints": [],
"navigation_steps": [],
"current_view": "...",
"target_ready": true,
"raw_html_len": 0,
"source_url": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. |
11. 자격상실 신고 입력 초안 검증fourinsure. b1. member_ qualification. los_ draft_ validate
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
상실자 성명과 주민등록번호, 고른 보험, 상실일과 보험별 상실사유, 보수총액을 넣으면 빠진 항목과 오류, 신고 가능 여부를 돌려줍니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
- params 를 빈 객체로 보내도 작업은 성공하지만, 그러면 필수 입력이 missing_required_fields 로 돌아오고 workflow_gate.input_ready 가 false 입니다.검증할 초안 값을 params 에 담아 보냅니다. 사용할 인증서는 account_link_id 로 지정합니다.
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 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| selected_ | array | N | 신고할 보험 목록(national_pension, health_insurance, employment_insurance, workers_compensation) | |
| applicant_ | string | N | 대상자 성명(한글) | |
| resident_ | string | N | 주민등록번호 | |
| rrno_ | string | N | 주민등록번호 앞자리 | |
| rrno_ | string | N | 주민등록번호 뒷자리 | |
| common_ | string | N | 공통 자격상실일 | |
| loss_ | string | N | 상실일 입력 방식(기관 화면 값, 저장 때 비우면 all) | |
| national_ | object | N | 국민연금 | |
| national_ | string | N | 국민연금 상실사유코드 생략 시 기본값: "" | |
| national_ | string | N | 국민연금 상실사유명 생략 시 기본값: "" | |
| national_ | string | N | 국민연금 자격상실일 생략 시 기본값: "" | |
| national_ | string | boolean | N | 국민연금 상실월납부여부 생략 시 기본값: null | |
| health_ | object | N | 건강보험 | |
| health_ | string | N | 건강보험 상실사유코드 생략 시 기본값: "" | |
| health_ | string | N | 건강보험 상실사유명 생략 시 기본값: "" | |
| health_ | string | N | 건강보험 자격상실일 생략 시 기본값: "" | |
| employment_ | object | N | 고용보험 | |
| employment_ | string | N | 고용보험 상실사유코드 생략 시 기본값: "" | |
| employment_ | string | N | 고용보험 상실사유명 생략 시 기본값: "" | |
| employment_ | string | N | 고용보험 구체적사유 생략 시 기본값: "" | |
| employment_ | string | N | 고용보험 자격상실일 생략 시 기본값: "" | |
| employment_ | string | number | N | 고용보험 해당연도 보수총액 생략 시 기본값: null | |
| employment_ | string | number | N | 고용보험 전년도 보수총액 생략 시 기본값: null | |
| workers_ | object | N | 산재보험 | |
| workers_ | string | N | 산재보험 상실사유코드 생략 시 기본값: "" | |
| workers_ | string | N | 산재보험 상실사유명 생략 시 기본값: "" | |
| workers_ | string | N | 산재보험 구체적사유 생략 시 기본값: "" | |
| workers_ | string | N | 산재보험 자격상실일 생략 시 기본값: "" | |
| workers_ | string | number | N | 산재보험 해당연도 보수총액 생략 시 기본값: null | |
| workers_ | string | number | N | 산재보험 전년도 보수총액 생략 시 기본값: null |
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: los_draft_validate-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.los_draft_validate",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- 저장 · 신고 없이 입력만 검증합니다. result.data 의 missing_required_fields 와 field_errors 로 고칠 항목을, workflow_gate 의 input_ready 와 can_submit_report 로 다음 단계로 갈 수 있는지 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| feature_ | string | 기능 식별자 | |
| phase | string | 처리 단계(draft_validate) | |
| workflow_ | string | 처리 단계 식별자 | |
| route_ | string | 처리 방식 — live_context_local_validation(화면 계약을 불러와 서버에서 검증) | |
| source_ | string | 서버가 요청한 기관 화면 주소 | |
| current_ | string | 현재 화면 식별자 | |
| target_ | boolean | 대상 폼 준비 여부 | |
| business_ | object | 사업장 컨텍스트 객체 | |
| selected_ | array | 검증 대상으로 고른 보험 목록 | |
| enabled_ | array | 화면 기준 섹션 사용 가능 상태 배열(key · label · enabled) | |
| required_ | array | 화면 기준 필수 입력 항목 배열(field_key · label · section · required_when) | |
| missing_ | array | 빠진 필수 입력 항목 배열(required_fields 와 같은 모양) | |
| field_ | array | 입력 누락 · 형식 오류 배열(field_key · label · section · message) | |
| warnings | array | 주의 메시지 배열(code · section · message · field_key) | |
| screen_ | array | 화면 확인 메모 배열 | |
| field_ | object | 입력 키와 화면 필드의 대응 맵 | |
| normalized_ | object | 정규화한 입력값 맵 | |
| draft_ | object | 화면 필드에 채울 값 미리보기 맵 | |
| followup_ | array | 기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다 | |
| workflow_ | object | 진행 판정 객체(input_ready · blocking_issue_count · can_save=false · can_submit_report · report_status · blocked_reason) | |
| safety | object | 안전 플래그 객체(input_only=true · save_executed=false · submit_executed=false) | |
| implementation_ | string | 구현 상태 식별자 |
// result.data
{
"success": true,
"feature_name": "...",
"phase": "draft_validate",
"workflow_step": "member_qualification_loss_draft_validated",
"route_kind": "live_context_local_validation",
"source_url": "...",
"current_view": "...",
"target_ready": true,
"business_context": {},
"selected_insurances": [],
"enabled_sections": [],
"required_fields": [],
"missing_required_fields": [],
"field_errors": [],
"warnings": [],
"screen_notes": [],
"field_bindings": {},
"normalized_input": {},
"draft_form_preview": {},
"followup_endpoints": [],
"workflow_gate": {},
"safety": {},
"implementation_status": "implemented_input_only_draft_validation"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. |
12. 자격상실 기존 신고 확인fourinsure. b1. member_ qualification. los_ exist_ check
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
자격키와 보험 하나를 넣으면 그 보험에 기존 상실신고가 있는지 기관에 확인해 신고 막힘 여부와 안내 문구를 돌려줍니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
- 기존 신고가 있어 기관이 안내 문장을 돌려주면 작업은 성공하고 duplicate_blocked 가 true 이며 그 문장이 alert_message 에 옵니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| rrkey | string | Y | 자격상실 가입자 조회 결과의 rrkey | |
| flag | string | Y | 확인할 보험(YG, GG, GY, SJ 또는 national_pension 같은 보험 이름) | |
| check_ | string | N | 기관 확인 구분 값(기본 2) | |
| bpmno | string | N | 사업장관리번호(비우면 기관 화면 값을 쓴다) | |
| workplace_ | string | N | 사업장 이름(비우면 기관 화면 값을 쓴다) | |
| declaration_ | string | N | 신고 적용일(비우면 기관 화면 값을 쓴다) | |
| applicant_ | string | N | 신고인 자격키(비우면 기관 화면 값을 쓴다) |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: los_exist_check-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.los_exist_check",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"rrkey": "<필수>",
"flag": "<필수>"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- 기관에 저장하거나 신고하지 않는 확인입니다. result.data 의 duplicate_blocked 가 false 면 insurance_key 의 보험에 진행을 막는 기존 상실신고가 없습니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| duplicate_ | boolean | 기관이 안내 문장으로 진행을 막았는지 여부(기존 신고가 있을 때 true) | |
| alert_ | string | 기관이 돌려준 안내 문장(없으면 빈 값) | |
| flag | string | 확인한 보험 구분 값(YG, GG, GY, SJ) | |
| insurance_ | string | 확인한 보험 이름 키(national_pension 등) | |
| save_ | boolean | 기관 저장 수행 여부(조회라 항상 false) | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.los_exist_check",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| VALIDATION_ | 필수 칸 누락 — 필수 칸(rrkey, flag)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다. | |
| PROVIDER_ | 검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다. |
13. 자격상실 입력 서식 조회fourinsure. b1. member_ qualification. los_ init
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
로그인한 연동으로 부르면 자격상실 신고 화면의 채워진 사업장 정보와, 비어 있는 상실일과 보험별 상실사유, 보수총액 칸 구성을 받습니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
- params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.
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 와 함께 쓰지 않습니다. |
추가 파라미터가 없습니다. params 는 {} 로 보냅니다.
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: los_init-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.los_init",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- result.data 에서 입력 항목(fields)과 화면 정보를 확인해 다음 단계(fourinsure.b1.member_qualification.los_draft_validate, fourinsure.b1.member_qualification.los_exist_check, fourinsure.b1.member_qualification.los_member_lookup, fourinsure.b1.member_qualification.los_save)의 요청 본문을 만듭니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| page | object | 화면 페이지 메타 객체 | |
| forms | array | form 메타데이터 배열 | |
| fields | array | 입력 필드 계약 배열 | |
| semantic_ | array | 의미 단위 입력 컨트롤 배열 | |
| semantic_ | object | 의미 필드 키-값 맵 | |
| semantic_ | number | 의미 필드 개수 | |
| csrf_ | boolean | CSRF 토큰 존재 여부 | |
| followup_ | array | 기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다 | |
| navigation_ | array | 화면 내비게이션 단계 배열 | |
| current_ | string | 현재 화면 식별자 | |
| target_ | boolean | 대상 폼 준비 여부 | |
| raw_ | number | 원본 HTML 길이 | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
// result.data
{
"success": true,
"page": {},
"forms": [],
"fields": [],
"semantic_fields": [],
"semantic_payload": {},
"semantic_field_count": 1,
"csrf_token_present": true,
"followup_endpoints": [],
"navigation_steps": [],
"current_view": "...",
"target_ready": true,
"raw_html_len": 0,
"source_url": "..."
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. |
14. 자격상실 가입자 조회fourinsure. b1. member_ qualification. los_ member_ lookup
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
퇴사자의 성명과 주민등록번호를 넣으면 자격상실 신고서에 쓸 자격키와 기존 자격취득일, 보험별 상실일을 돌려줍니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
- 기관이 안내 문장을 돌려주면 작업은 성공하고 lookup_ok 가 false, rrkey 는 빈 값이며 그 문장이 alert_message 에 옵니다.
- REST 요청 표와 MCP 도구 규격의 필수 표시가 다릅니다.MCP 도구의 입력 규격(inputSchema)은 resident_registration_number 를 필수로 표시하므로 arguments 에 반드시 포함하세요. 값은 REST 와 같은 작업 제출 경로에서 검사합니다.나머지 필수 입력과 업무 조건은 아래 요청 표를 함께 따릅니다.
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 파라미터 표의 필수 항목을 채우고 resident_registration_number 또는 rrno_front 중 하나 이상, resident_registration_number 또는 rrno_back 중 하나 이상을 함께 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| applicant_ | string | - | Y | 대상자 성명(한글) | |
| resident_ | string | - | 조건부 | 주민등록번호 13자리 | |
| rrno_ | string | - | 조건부 | 주민등록번호 앞 6자리 | |
| rrno_ | string | - | 조건부 | 주민등록번호 뒤 7자리 | |
| declaration_ | string | 8 | N | 신고 적용일(비우면 기관 화면 값을 쓴다) | |
| bpmno | string | - | N | 사업장관리번호(비우면 기관 화면 값을 쓴다) |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: los_member_lookup-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.los_member_lookup",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"applicant_name": "<필수>",
"resident_registration_number": "<필수>"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- 기관에 저장하거나 신고하지 않는 조회입니다.result.data 의 lookup_ok 가 true 면 rrkey 를 자격상실 기존 신고 확인에 그대로 넣고, existing_loss_dates 와 exists 로 보험별 기존 상실일과 존재 표시를 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| lookup_ | boolean | 가입자를 찾았는지 여부(false 면 rrkey 가 빈 값) | |
| alert_ | string | 기관이 돌려준 안내 문장(없으면 빈 값) | |
| rrkey | string | 가입자 자격키, 같은 신고의 다음 조회에 그대로 넣는 값 | |
| applicant_ | string | 조회한 대상자 성명 | |
| rrno_ | string | 가린 주민등록번호 | |
| health_ | string | 건강보험증 번호 | |
| qualification_ | string | 자격취득일 | |
| qualification_ | object | 보험별 기존 자격취득일 맵 | |
| existing_ | object | 보험별 기존 자격상실일 맵 | |
| exists | object | 보험별 존재 표시 맵(기관이 돌려준 값 그대로) | |
| save_ | boolean | 기관 저장 수행 여부(조회라 항상 false) | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.los_member_lookup",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| VALIDATION_ | 필수 칸 누락 — 필수 칸(applicant_name)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다. | |
| PROVIDER_ | 검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다. |
15. 자격상실 초안 저장fourinsure. b1. member_ qualification. los_ save
MCP 도구 이름 fourinsure__
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
퇴사자 자격키와 성명, 주민등록번호, 공통 자격상실일, 보험마다 상실 사유, 당해연도 보수총액, 건강보험 산정 개월수를 넣으면 자격상실 신고서를 정보연계센터에 초안으로 저장하고 접수번호를 받습니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
- dry_run 을 true 로 보내면 기관에 보내지 않고 저장할 내용을 result.data 의 preview 로 돌려줍니다(save_executed=false).이때는 confirm 이 필요 없습니다.
- REST 요청 표와 MCP 도구 규격의 필수 표시가 다릅니다.MCP 도구의 입력 규격(inputSchema)은 current_year_salary_amount, employment_insurance, health_insurance, health_insurance_month_count, national_pension, resident_registration_number, workers_compensation 를 필수로 표시하므로 arguments 에 반드시 포함하세요.값은 REST 와 같은 작업 제출 경로에서 검사합니다. 나머지 필수 입력과 업무 조건은 아래 요청 표를 함께 따릅니다.
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 파라미터 표의 필수 항목을 채우고 resident_registration_number 또는 rrno_front 중 하나 이상, resident_registration_number 또는 rrno_back 중 하나 이상을 함께 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| selected_ | array | - | N | 신고할 보험 목록(national_pension, health_insurance, employment_insurance, workers_compensation, 기본은 네 보험 모두) | |
| applicant_ | string | - | Y | 대상자 성명(한글) | |
| resident_ | string | - | 조건부 | 주민등록번호 13자리 | |
| rrno_ | string | - | 조건부 | 주민등록번호 앞자리 | |
| rrno_ | string | - | 조건부 | 주민등록번호 뒷자리 | |
| common_ | string | 8 | Y | 공통 상실일 | |
| loss_ | string | - | N | 상실일 입력 방식(기관 화면 값, 저장 때 비우면 all) | |
| national_ | object | - | N | 국민연금 상실 사유. 코드와 이름을 둘 다 입력합니다. 비우면 저장하지 않습니다 | |
| national_ | string | - | 조건부 | 국민연금을 신고할 때 꼭 보내는 상실 사유 코드입니다. 이름과 함께 보내야 하고 없으면 저장하지 않고 거절합니다. selected_insurances 를 보내지 않으면 국민연금도 신고합니다 | |
| national_ | string | - | 조건부 | 위 코드에 해당하는 국민연금 상실 사유 이름입니다. 코드와 이름을 둘 다 보내야 하며 하나만 보내도 저장하지 않고 거절합니다 | |
| national_ | string | - | N | 국민연금 자격상실일 생략 시 기본값: "" | |
| national_ | string | boolean | - | N | 국민연금 상실월납부여부 생략 시 기본값: null | |
| health_ | object | - | N | 건강보험 상실 사유. 코드와 이름을 둘 다 입력합니다. 비우면 저장하지 않습니다 | |
| health_ | string | - | 조건부 | 건강보험을 신고할 때 꼭 보내는 상실 사유 코드입니다. 이름과 함께 보내야 하고 없으면 저장하지 않고 거절합니다. selected_insurances 를 보내지 않으면 건강보험도 신고합니다 | |
| health_ | string | - | 조건부 | 위 코드에 해당하는 건강보험 상실 사유 이름입니다. 코드와 이름을 둘 다 보내야 하며 하나만 보내도 저장하지 않고 거절합니다 | |
| health_ | string | - | N | 건강보험 자격상실일 생략 시 기본값: "" | |
| employment_ | object | - | N | 고용보험 상실 사유. 코드와 이름을 둘 다 입력합니다. 비우면 저장하지 않습니다 | |
| employment_ | string | - | 조건부 | 고용보험을 신고할 때 꼭 보내는 상실 사유 코드입니다. 이름과 함께 보내야 하고 없으면 저장하지 않고 거절합니다. selected_insurances 를 보내지 않으면 고용보험도 신고합니다 | |
| employment_ | string | - | 조건부 | 위 코드에 해당하는 고용보험 상실 사유 이름입니다. 코드와 이름을 둘 다 보내야 하며 하나만 보내도 저장하지 않고 거절합니다 | |
| employment_ | string | - | N | 구체적 사유. 입력하지 않으면 비워 저장합니다 | |
| employment_ | string | - | N | 고용보험 자격상실일 생략 시 기본값: "" | |
| employment_ | string | number | - | N | 고용보험 해당연도 보수총액 생략 시 기본값: null | |
| employment_ | string | number | - | N | 고용보험 전년도 보수총액 생략 시 기본값: null | |
| workers_ | object | - | N | 산재보험 상실 사유. 코드와 이름을 둘 다 입력합니다. 비우면 저장하지 않습니다 | |
| workers_ | string | - | 조건부 | 산재보험을 신고할 때 꼭 보내는 상실 사유 코드입니다. 이름과 함께 보내야 하고 없으면 저장하지 않고 거절합니다. selected_insurances 를 보내지 않으면 산재보험도 신고합니다 | |
| workers_ | string | - | 조건부 | 위 코드에 해당하는 산재보험 상실 사유 이름입니다. 코드와 이름을 둘 다 보내야 하며 하나만 보내도 저장하지 않고 거절합니다 | |
| workers_ | string | - | N | 구체적 사유. 입력하지 않으면 비워 저장합니다 | |
| workers_ | string | - | N | 산재보험 자격상실일 생략 시 기본값: "" | |
| workers_ | string | number | - | N | 산재보험 해당연도 보수총액 생략 시 기본값: null | |
| workers_ | string | number | - | N | 산재보험 전년도 보수총액 생략 시 기본값: null | |
| rrkey | string | - | Y | 자격상실 가입자 조회 결과의 rrkey | |
| cmd | string | - | N | 저장 구분(Regist 신규, Modify 수정) | |
| cvrc_ | string | - | N | 수정할 초안의 접수번호(cmd 가 Modify 일 때 필수) | |
| current_ | string | number | - | N | 당해연도 보수총액(건강보험, 고용보험, 산재보험을 신고할 때 필수). 0 보다 큰 값을 입력합니다 | |
| previous_ | string | number | - | N | 전년도 보수총액 | |
| health_ | string | - | N | 건강보험 당해연도 산정월수(건강보험을 신고할 때 필수) | |
| qualification_ | string | - | N | 자격취득일(가입자 조회 결과의 qualification_acquisition_date) | |
| health_ | string | - | N | 건강보험증 번호(가입자 조회 결과의 health_card_no) | |
| confirm | boolean | - | N | true 여야 저장한다. 없으면 저장하지 않고 저장할 내용 미리보기와 함께 거절한다 | |
| dry_ | boolean | - | N | true 면 기관에 보내지 않고 저장할 내용만 돌려준다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: los_save-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.los_save",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"applicant_name": "<필수>",
"common_loss_date": "<필수>",
"rrkey": "<필수>",
"resident_registration_number": "<필수>"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- 자격상실 신고 초안이 정보연계센터에 저장되며 저장한 초안을 되돌리는 API 는 없습니다.result.data 의 save_ok 가 true 이고 cvrc_no 에 기관이 새로 발번한 접수번호가 옵니다. 기관 전송은 하지 않습니다(submit_executed=false).
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| save_ | boolean | 기관이 초안 저장을 받아들였는지 여부(새 접수번호를 받았을 때만 true) | |
| save_ | boolean | 기관에 저장 요청을 보냈는지 여부(dry_run 이면 false) | |
| submit_ | boolean | 기관 전송 수행 여부(이 API 는 전송하지 않아 항상 false) | |
| dry_ | boolean | 접수 없이 검증만 한 호출이면 true | |
| alert_ | string | 기관이 돌려준 안내 문장(없으면 빈 값) | |
| cvrc_ | string | 기관이 새로 발번한 신고 초안 접수번호(save_ok 가 true 일 때만 값이 있다) | |
| bpmno | string | 사업장관리번호(save_ok 가 true 일 때만 값이 있다) | |
| dong_ | string | 기관이 돌려준 동 코드 | |
| preview | object | 기관에 보낼 저장 내용 미리보기 맵 | |
| source_ | string | 서버가 요청한 기관 화면 주소 | |
| outcome | string | 기관 쓰기 판정입니다. 새 접수번호를 받아 저장을 확인했으면 confirmed 입니다. 확인하지 못하면 작업 API 는 결과 대신 실패(error_code PROVIDER_OUTCOME_UNCONFIRMED, 재시도 불가)로 끝나고, REST 응답은 이 칸이 unconfirmed 이고 success 가 false 입니다. 실제 저장 때만 옵니다. dry_run 이면 이 칸이 없습니다 | |
| message_ | string | REST 응답에서 outcome 이 unconfirmed 일 때만 값이 있는 안내 문장입니다. 작업 API 는 이 문장을 실패의 오류 문장 앞부분으로 줍니다. 실제 저장 때만 옵니다. dry_run 이면 이 칸이 없습니다 | |
| how_ | string | REST 응답에서 outcome 이 unconfirmed 일 때만 값이 있습니다. 다시 저장하기 전에 방금 저장이 됐는지 확인하는 방법을 알려 줍니다. 작업 API 는 이 문장을 실패의 오류 문장 뒤에 붙여 줍니다. 실제 저장 때만 옵니다. dry_run 이면 이 칸이 없습니다 | |
| action | string | 작업 API 결과에만 있는 칸입니다. 저장을 확인했을 때 이 액션 이름이 그대로 옵니다. REST 응답에는 없습니다. 실제 저장 때만 옵니다. dry_run 이면 이 칸이 없습니다 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "fourinsure",
"action": "fourinsure.b1.member_qualification.los_save",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| VALIDATION_ | 확인 필요 — confirm 없이 보내면 저장하지 않고 이 오류로 끝나며, error.message 에 저장될 내용의 [미리보기] 가 담깁니다. 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 confirm=true 를 더해 다시 호출합니다. | |
| POLICY_ | 일시 중지 — 상품이 일시 중지 상태입니다. 다시 보내도 풀리지 않습니다. | |
| AUTH_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 결과 불명 — 저장 요청을 보낸 뒤 기관이 새 접수번호를 주지 않거나 오류로 답하거나 연결이 끊기면, 다시 실행하지 말고 자격상실 신고 화면에서 방금 저장한 초안이 있는지 먼저 확인합니다. 기관이 오류 응답을 보내거나 응답이 오지 않거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| PROVIDER_ | 결과 불명 — 저장 요청을 보낸 뒤 기관이 새 접수번호를 주지 않거나 오류로 답하거나 연결이 끊기면, 다시 실행하지 말고 자격상실 신고 화면에서 방금 저장한 초안이 있는지 먼저 확인합니다. 기관이 오류 응답을 보내거나 응답이 오지 않거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다. | |
| VALIDATION_ | 필수 칸 누락 — 필수 칸(applicant_name, rrkey, common_loss_date)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다. | |
| PROVIDER_ | 검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다. |