개발자 문서
API 레퍼런스

급여 - 4대보험

이 쪽의 모든 작업에 해당

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]

1. 보수월액 변경신청 입력 초안 검증fourinsure.b1.payroll.amount_change.draft_validate

MCP 도구 이름 fourinsure__b1__payroll__amount_change__draft_validate

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

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

가입자별 성명과 주민등록번호, 변경 전후 기준소득월액, 근로자 동의, 보험별 변경 금액과 변경연월을 넣으면 오류와 신고 가능 여부를 돌려줍니다.

  • params 를 빈 객체로 보내도 작업은 성공하지만, 그러면 필수 입력이 missing_required_fields 로 돌아오고 workflow_gate.input_ready 가 false 입니다.

Request

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

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

[참고] 인증

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

[참고] 환경

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

[참고] 재시도

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

예시 : fourinsure

actionstring-Y호출할 작업입니다.
  • fourinsure.b1.payroll.amount_change.draft_validate이 API 고정값 (기본값)

예시 : fourinsure.b1.payroll.amount_change.draft_validate

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

  • 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
순번변수명타입필수설명
selected_insurancesarrayN반영 보험
applicant_namestringN성명
resident_registration_numberstringN주민등록번호
rrno_frontstringN주민등록번호 앞자리
rrno_backstringN주민등록번호 뒷자리
change_reason_codestringN변경사유 코드. 1 보수인상, 2 보수인하, 3 착오정정 가운데 하나를 입력합니다
change_reason_namestringN보수월액 변경 사유 이름입니다
business_contactobjectN사업장 전화번호와 팩스번호를 담은 객체입니다
business_contact.tel_areastringN전화번호 지역 생략 시 기본값: ""
business_contact.tel_middlestringN전화번호 중간 생략 시 기본값: ""
business_contact.tel_laststringN전화번호 끝 생략 시 기본값: ""
business_contact.fax_areastringN팩스 지역 생략 시 기본값: ""
business_contact.fax_middlestringN팩스 중간 생략 시 기본값: ""
business_contact.fax_laststringN팩스 끝 생략 시 기본값: ""
national_pensionobjectN국민연금
national_pension.current_monthly_amountstring | numberN현재기준소득월액 생략 시 기본값: null
national_pension.changed_monthly_amountstring | numberN변경후 기준소득월액 생략 시 기본값: null
national_pension.worker_agreementstring | booleanN근로자 동의 여부 생략 시 기본값: null
national_pension.member_confirm_codestringN국민연금 인증값 생략 시 기본값: ""
national_pension.rrkeystringN가입자 조회 결과의 주민등록번호 식별키입니다. 생략 시 기본값: ""
national_pension.nhicrd_nostringN가입자 조회 결과의 건강보험증 번호입니다. 생략 시 기본값: ""
health_insuranceobjectN건강보험
health_insurance.applystring | booleanN건강보험 체크 생략 시 기본값: null
health_insurance.changed_monthly_amountstring | numberN건강보험 변경 보수월액 생략 시 기본값: null
health_insurance.change_yearstringN건강보험 변경연도 생략 시 기본값: ""
health_insurance.change_monthstringN건강보험 변경월 생략 시 기본값: ""
health_insurance.change_year_monthstringN건강보험 변경연월 생략 시 기본값: ""
health_insurance.member_confirm_codestringN건강보험 인증값 생략 시 기본값: ""
employment_insuranceobjectN고용보험
employment_insurance.applystring | booleanN고용보험 체크 생략 시 기본값: null
employment_insurance.changed_monthly_amountstring | numberN고용보험 변경 보수월액 생략 시 기본값: null
employment_insurance.change_yearstringN고용보험 변경연도 생략 시 기본값: ""
employment_insurance.change_monthstringN고용보험 변경월 생략 시 기본값: ""
employment_insurance.change_year_monthstringN고용보험 변경연월 생략 시 기본값: ""
employment_insurance.member_confirm_codestringN고용보험 인증값 생략 시 기본값: ""
workers_compensationobjectN산재보험
workers_compensation.applystring | booleanN산재보험 체크 생략 시 기본값: null
workers_compensation.changed_monthly_amountstring | numberN산재보험 변경 보수월액 생략 시 기본값: null
workers_compensation.change_yearstringN산재보험 변경연도 생략 시 기본값: ""
workers_compensation.change_monthstringN산재보험 변경월 생략 시 기본값: ""
workers_compensation.change_year_monthstringN산재보험 변경연월 생략 시 기본값: ""
workers_compensation.member_confirm_codestringN산재보험 인증값 생략 시 기본값: ""
membersarrayN보수월액 변경 대상 근로자 목록
members[].row_indexnumberN변경 대상 가입자 행의 순번입니다. 생략 시 기본값: 0
members[].applicant_namestringN성명 생략 시 기본값: ""
members[].resident_registration_numberstringN주민등록번호 생략 시 기본값: ""
members[].rrno_frontstringN주민등록번호 앞자리 생략 시 기본값: ""
members[].rrno_backstringN주민등록번호 뒷자리 생략 시 기본값: ""
members[].rrkeystringN가입자 조회 결과의 주민등록번호 식별키입니다. 생략 시 기본값: ""
members[].nhicrd_nostringN가입자 조회 결과의 건강보험증 번호입니다. 생략 시 기본값: ""
members[].mbr_nps_confstringN국민연금 가입자 확인값입니다. 생략 시 기본값: ""
members[].mbr_nhi_confstringN건강보험 가입자 확인값입니다. 생략 시 기본값: ""
members[].mbr_epi_confstringN고용보험 가입자 확인값입니다. 생략 시 기본값: ""
members[].mem_iai_confstringN산재보험 가입자 확인값입니다. 생략 시 기본값: ""
members[].selected_insurancesarrayN반영 보험
members[].national_pensionobjectN국민연금
members[].national_pension.current_monthly_amountstring | numberN현재기준소득월액 생략 시 기본값: null
members[].national_pension.changed_monthly_amountstring | numberN변경후 기준소득월액 생략 시 기본값: null
members[].national_pension.worker_agreementstring | booleanN근로자 동의 여부 생략 시 기본값: null
members[].national_pension.member_confirm_codestringN국민연금 인증값 생략 시 기본값: ""
members[].national_pension.rrkeystringN가입자 조회 결과의 주민등록번호 식별키입니다. 생략 시 기본값: ""
members[].national_pension.nhicrd_nostringN가입자 조회 결과의 건강보험증 번호입니다. 생략 시 기본값: ""
members[].health_insuranceobjectN건강보험
members[].health_insurance.applystring | booleanN건강보험 체크 생략 시 기본값: null
members[].health_insurance.changed_monthly_amountstring | numberN건강보험 변경 보수월액 생략 시 기본값: null
members[].health_insurance.change_yearstringN건강보험 변경연도 생략 시 기본값: ""
members[].health_insurance.change_monthstringN건강보험 변경월 생략 시 기본값: ""
members[].health_insurance.change_year_monthstringN건강보험 변경연월 생략 시 기본값: ""
members[].health_insurance.member_confirm_codestringN건강보험 인증값 생략 시 기본값: ""
members[].employment_insuranceobjectN고용보험
members[].employment_insurance.applystring | booleanN고용보험 체크 생략 시 기본값: null
members[].employment_insurance.changed_monthly_amountstring | numberN고용보험 변경 보수월액 생략 시 기본값: null
members[].employment_insurance.change_yearstringN고용보험 변경연도 생략 시 기본값: ""
members[].employment_insurance.change_monthstringN고용보험 변경월 생략 시 기본값: ""
members[].employment_insurance.change_year_monthstringN고용보험 변경연월 생략 시 기본값: ""
members[].employment_insurance.member_confirm_codestringN고용보험 인증값 생략 시 기본값: ""
members[].workers_compensationobjectN산재보험
members[].workers_compensation.applystring | booleanN산재보험 체크 생략 시 기본값: null
members[].workers_compensation.changed_monthly_amountstring | numberN산재보험 변경 보수월액 생략 시 기본값: null
members[].workers_compensation.change_yearstringN산재보험 변경연도 생략 시 기본값: ""
members[].workers_compensation.change_monthstringN산재보험 변경월 생략 시 기본값: ""
members[].workers_compensation.change_year_monthstringN산재보험 변경연월 생략 시 기본값: ""
members[].workers_compensation.member_confirm_codestringN산재보험 인증값 생략 시 기본값: ""
members[].change_reason_codestringN변경사유 코드. 1 보수인상, 2 보수인하, 3 착오정정 가운데 하나를 입력합니다. 생략 시 기본값: ""
members[].change_reason_namestringN보수월액 변경 사유 이름입니다. 생략 시 기본값: ""
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: draft_validate-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "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 로 다음 단계로 갈 수 있는지 확인합니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
feature_namestring기능 식별자
phasestring처리 단계(draft_validate)
workflow_stepstring처리 단계 식별자
route_kindstring처리 방식 — live_context_local_validation(화면 계약을 불러와 서버에서 검증)
source_urlstring서버가 요청한 기관 화면 주소
current_viewstring현재 화면 식별자
target_readyboolean대상 폼 준비 여부
business_contextobject사업장 컨텍스트 객체
selected_insurancesarray검증 대상으로 고른 보험 목록
enabled_sectionsarray화면 기준 섹션 사용 가능 상태 배열(key · label · enabled)
required_fieldsarray화면 기준 필수 입력 항목 배열(field_key · label · section · required_when)
missing_required_fieldsarray빠진 필수 입력 항목 배열(required_fields 와 같은 모양)
field_errorsarray입력 누락 · 형식 오류 배열(field_key · label · section · message)
warningsarray주의 메시지 배열(code · section · message · field_key)
screen_notesarray화면 확인 메모 배열
field_bindingsobject입력 키와 화면 필드의 대응 맵
normalized_inputobject정규화한 입력값 맵
draft_form_previewobject화면 필드에 채울 값 미리보기 맵
followup_endpointsarray기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다
workflow_gateobject진행 판정 객체(input_ready · blocking_issue_count · can_save=false · can_submit_report · report_status · blocked_reason)
safetyobject안전 플래그 객체(input_only=true · save_executed=false · submit_executed=false)
implementation_statusstring구현 상태 식별자
json
// 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_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.

2. 보수월액 변경신청 입력 서식 조회fourinsure.b1.payroll.amount_change.init

MCP 도구 이름 fourinsure__b1__payroll__amount_change__init

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

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

로그인한 연동으로 부르면 보수월액 변경신청 화면의 사업장 관리번호와 명칭, 소재지, 보험별 가입 여부, 전화와 팩스 칸을 받습니다.

  • params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.

Request

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

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

[참고] 인증

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

[참고] 환경

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

[참고] 재시도

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

예시 : fourinsure

actionstring-Y호출할 작업입니다.
  • fourinsure.b1.payroll.amount_change.init이 API 고정값 (기본값)

예시 : fourinsure.b1.payroll.amount_change.init

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

추가 파라미터가 없습니다. params 는 {} 로 보냅니다.

bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: init-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "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)의 요청 본문을 만듭니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
pageobject화면 페이지 메타 객체
formsarrayform 메타데이터 배열
fieldsarray입력 필드 계약 배열
semantic_fieldsarray의미 단위 입력 컨트롤 배열
semantic_payloadobject의미 필드 키-값 맵
semantic_field_countnumber의미 필드 개수
csrf_token_presentbooleanCSRF 토큰 존재 여부
followup_endpointsarray기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다
navigation_stepsarray화면 내비게이션 단계 배열
current_viewstring현재 화면 식별자
target_readyboolean대상 폼 준비 여부
raw_html_lennumber원본 HTML 길이
source_urlstring서버가 요청한 기관 화면 주소
json
// 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_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.