급여 - 4대보험
이 쪽의 모든 작업에 해당
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
1. 보수월액 변경신청 입력 초안 검증fourinsure. b1. payroll. amount_ change. draft_ validate
MCP 도구 이름 fourinsure__
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
가입자별 성명과 주민등록번호, 변경 전후 기준소득월액, 근로자 동의, 보험별 변경 금액과 변경연월을 넣으면 오류와 신고 가능 여부를 돌려줍니다.
- 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 | 반영 보험 | |
| applicant_ | string | N | 성명 | |
| resident_ | string | N | 주민등록번호 | |
| rrno_ | string | N | 주민등록번호 앞자리 | |
| rrno_ | string | N | 주민등록번호 뒷자리 | |
| change_ | string | N | 변경사유 코드. 1 보수인상, 2 보수인하, 3 착오정정 가운데 하나를 입력합니다 | |
| change_ | string | N | 보수월액 변경 사유 이름입니다 | |
| business_ | object | N | 사업장 전화번호와 팩스번호를 담은 객체입니다 | |
| business_ | string | N | 전화번호 지역 생략 시 기본값: "" | |
| business_ | string | N | 전화번호 중간 생략 시 기본값: "" | |
| business_ | string | N | 전화번호 끝 생략 시 기본값: "" | |
| business_ | string | N | 팩스 지역 생략 시 기본값: "" | |
| business_ | string | N | 팩스 중간 생략 시 기본값: "" | |
| business_ | string | N | 팩스 끝 생략 시 기본값: "" | |
| national_ | object | N | 국민연금 | |
| national_ | string | number | N | 현재기준소득월액 생략 시 기본값: null | |
| national_ | string | number | N | 변경후 기준소득월액 생략 시 기본값: null | |
| national_ | string | boolean | N | 근로자 동의 여부 생략 시 기본값: null | |
| national_ | string | N | 국민연금 인증값 생략 시 기본값: "" | |
| national_ | string | N | 가입자 조회 결과의 주민등록번호 식별키입니다. 생략 시 기본값: "" | |
| national_ | string | N | 가입자 조회 결과의 건강보험증 번호입니다. 생략 시 기본값: "" | |
| health_ | object | N | 건강보험 | |
| health_ | string | boolean | N | 건강보험 체크 생략 시 기본값: null | |
| health_ | string | number | N | 건강보험 변경 보수월액 생략 시 기본값: null | |
| health_ | string | N | 건강보험 변경연도 생략 시 기본값: "" | |
| health_ | string | N | 건강보험 변경월 생략 시 기본값: "" | |
| health_ | string | N | 건강보험 변경연월 생략 시 기본값: "" | |
| health_ | string | N | 건강보험 인증값 생략 시 기본값: "" | |
| employment_ | object | N | 고용보험 | |
| employment_ | string | boolean | N | 고용보험 체크 생략 시 기본값: null | |
| employment_ | string | number | N | 고용보험 변경 보수월액 생략 시 기본값: null | |
| employment_ | string | N | 고용보험 변경연도 생략 시 기본값: "" | |
| employment_ | string | N | 고용보험 변경월 생략 시 기본값: "" | |
| employment_ | string | N | 고용보험 변경연월 생략 시 기본값: "" | |
| employment_ | string | N | 고용보험 인증값 생략 시 기본값: "" | |
| workers_ | object | N | 산재보험 | |
| workers_ | string | boolean | N | 산재보험 체크 생략 시 기본값: null | |
| workers_ | string | number | N | 산재보험 변경 보수월액 생략 시 기본값: null | |
| workers_ | string | N | 산재보험 변경연도 생략 시 기본값: "" | |
| workers_ | string | N | 산재보험 변경월 생략 시 기본값: "" | |
| workers_ | string | N | 산재보험 변경연월 생략 시 기본값: "" | |
| workers_ | string | N | 산재보험 인증값 생략 시 기본값: "" | |
| members | array | N | 보수월액 변경 대상 근로자 목록 | |
| members[]. | number | N | 변경 대상 가입자 행의 순번입니다. 생략 시 기본값: 0 | |
| members[]. | string | N | 성명 생략 시 기본값: "" | |
| members[]. | string | N | 주민등록번호 생략 시 기본값: "" | |
| members[]. | string | N | 주민등록번호 앞자리 생략 시 기본값: "" | |
| members[]. | string | N | 주민등록번호 뒷자리 생략 시 기본값: "" | |
| members[]. | string | N | 가입자 조회 결과의 주민등록번호 식별키입니다. 생략 시 기본값: "" | |
| members[]. | string | N | 가입자 조회 결과의 건강보험증 번호입니다. 생략 시 기본값: "" | |
| members[]. | string | N | 국민연금 가입자 확인값입니다. 생략 시 기본값: "" | |
| members[]. | string | N | 건강보험 가입자 확인값입니다. 생략 시 기본값: "" | |
| members[]. | string | N | 고용보험 가입자 확인값입니다. 생략 시 기본값: "" | |
| members[]. | string | N | 산재보험 가입자 확인값입니다. 생략 시 기본값: "" | |
| members[]. | array | N | 반영 보험 | |
| members[]. | object | N | 국민연금 | |
| members[]. | string | number | N | 현재기준소득월액 생략 시 기본값: null | |
| members[]. | string | number | N | 변경후 기준소득월액 생략 시 기본값: null | |
| members[]. | string | boolean | N | 근로자 동의 여부 생략 시 기본값: null | |
| members[]. | string | N | 국민연금 인증값 생략 시 기본값: "" | |
| members[]. | string | N | 가입자 조회 결과의 주민등록번호 식별키입니다. 생략 시 기본값: "" | |
| members[]. | string | N | 가입자 조회 결과의 건강보험증 번호입니다. 생략 시 기본값: "" | |
| members[]. | object | N | 건강보험 | |
| members[]. | string | boolean | N | 건강보험 체크 생략 시 기본값: null | |
| members[]. | string | number | N | 건강보험 변경 보수월액 생략 시 기본값: null | |
| members[]. | string | N | 건강보험 변경연도 생략 시 기본값: "" | |
| members[]. | string | N | 건강보험 변경월 생략 시 기본값: "" | |
| members[]. | string | N | 건강보험 변경연월 생략 시 기본값: "" | |
| members[]. | string | N | 건강보험 인증값 생략 시 기본값: "" | |
| members[]. | object | N | 고용보험 | |
| members[]. | string | boolean | N | 고용보험 체크 생략 시 기본값: null | |
| members[]. | string | number | N | 고용보험 변경 보수월액 생략 시 기본값: null | |
| members[]. | string | N | 고용보험 변경연도 생략 시 기본값: "" | |
| members[]. | string | N | 고용보험 변경월 생략 시 기본값: "" | |
| members[]. | string | N | 고용보험 변경연월 생략 시 기본값: "" | |
| members[]. | string | N | 고용보험 인증값 생략 시 기본값: "" | |
| members[]. | object | N | 산재보험 | |
| members[]. | string | boolean | N | 산재보험 체크 생략 시 기본값: null | |
| members[]. | string | number | N | 산재보험 변경 보수월액 생략 시 기본값: null | |
| members[]. | string | N | 산재보험 변경연도 생략 시 기본값: "" | |
| members[]. | string | N | 산재보험 변경월 생략 시 기본값: "" | |
| members[]. | string | N | 산재보험 변경연월 생략 시 기본값: "" | |
| members[]. | string | N | 산재보험 인증값 생략 시 기본값: "" | |
| members[]. | string | N | 변경사유 코드. 1 보수인상, 2 보수인하, 3 착오정정 가운데 하나를 입력합니다. 생략 시 기본값: "" | |
| members[]. | 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: draft_validate-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.payroll.amount_change.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": "payroll_amount_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 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. |
2. 보수월액 변경신청 입력 서식 조회fourinsure. b1. payroll. amount_ change. init
MCP 도구 이름 fourinsure__
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
로그인한 연동으로 부르면 보수월액 변경신청 화면의 사업장 관리번호와 명칭, 소재지, 보험별 가입 여부, 전화와 팩스 칸을 받습니다.
- 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: init-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "fourinsure",
"action": "fourinsure.b1.payroll.amount_change.init",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- result.data 에서 입력 항목(fields)과 화면 정보를 확인해 다음 단계(fourinsure.b1.payroll.amount_change.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 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. |